@wazir-dev/cli 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +111 -0
- package/CHANGELOG.md +14 -0
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +314 -0
- package/assets/composition-engine.mmd +34 -0
- package/assets/demo-script.sh +17 -0
- package/assets/logo-dark.svg +14 -0
- package/assets/logo.svg +14 -0
- package/assets/pipeline.mmd +39 -0
- package/assets/record-demo.sh +51 -0
- package/docs/README.md +51 -0
- package/docs/adapters/context-mode.md +60 -0
- package/docs/concepts/architecture.md +87 -0
- package/docs/concepts/artifact-model.md +60 -0
- package/docs/concepts/composition-engine.md +36 -0
- package/docs/concepts/indexing-and-recall.md +160 -0
- package/docs/concepts/observability.md +41 -0
- package/docs/concepts/roles-and-workflows.md +59 -0
- package/docs/concepts/terminology-policy.md +27 -0
- package/docs/getting-started/01-installation.md +78 -0
- package/docs/getting-started/02-first-run.md +102 -0
- package/docs/getting-started/03-adding-to-project.md +15 -0
- package/docs/getting-started/04-host-setup.md +15 -0
- package/docs/guides/ci-integration.md +15 -0
- package/docs/guides/creating-skills.md +15 -0
- package/docs/guides/expertise-module-authoring.md +15 -0
- package/docs/guides/hook-development.md +15 -0
- package/docs/guides/memory-and-learnings.md +34 -0
- package/docs/guides/multi-host-export.md +15 -0
- package/docs/guides/troubleshooting.md +101 -0
- package/docs/guides/writing-custom-roles.md +15 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
- package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
- package/docs/readmes/INDEX.md +99 -0
- package/docs/readmes/features/expertise/README.md +171 -0
- package/docs/readmes/features/exports/README.md +222 -0
- package/docs/readmes/features/hooks/README.md +103 -0
- package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
- package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
- package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
- package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
- package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
- package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
- package/docs/readmes/features/hooks/session-start.md +119 -0
- package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
- package/docs/readmes/features/roles/README.md +157 -0
- package/docs/readmes/features/roles/clarifier.md +152 -0
- package/docs/readmes/features/roles/content-author.md +190 -0
- package/docs/readmes/features/roles/designer.md +193 -0
- package/docs/readmes/features/roles/executor.md +184 -0
- package/docs/readmes/features/roles/learner.md +210 -0
- package/docs/readmes/features/roles/planner.md +182 -0
- package/docs/readmes/features/roles/researcher.md +164 -0
- package/docs/readmes/features/roles/reviewer.md +184 -0
- package/docs/readmes/features/roles/specifier.md +162 -0
- package/docs/readmes/features/roles/verifier.md +215 -0
- package/docs/readmes/features/schemas/README.md +178 -0
- package/docs/readmes/features/skills/README.md +63 -0
- package/docs/readmes/features/skills/brainstorming.md +96 -0
- package/docs/readmes/features/skills/debugging.md +148 -0
- package/docs/readmes/features/skills/design.md +120 -0
- package/docs/readmes/features/skills/prepare-next.md +109 -0
- package/docs/readmes/features/skills/run-audit.md +159 -0
- package/docs/readmes/features/skills/scan-project.md +109 -0
- package/docs/readmes/features/skills/self-audit.md +176 -0
- package/docs/readmes/features/skills/tdd.md +137 -0
- package/docs/readmes/features/skills/using-skills.md +92 -0
- package/docs/readmes/features/skills/verification.md +120 -0
- package/docs/readmes/features/skills/writing-plans.md +104 -0
- package/docs/readmes/features/tooling/README.md +320 -0
- package/docs/readmes/features/workflows/README.md +186 -0
- package/docs/readmes/features/workflows/author.md +181 -0
- package/docs/readmes/features/workflows/clarify.md +154 -0
- package/docs/readmes/features/workflows/design-review.md +171 -0
- package/docs/readmes/features/workflows/design.md +169 -0
- package/docs/readmes/features/workflows/discover.md +162 -0
- package/docs/readmes/features/workflows/execute.md +173 -0
- package/docs/readmes/features/workflows/learn.md +167 -0
- package/docs/readmes/features/workflows/plan-review.md +165 -0
- package/docs/readmes/features/workflows/plan.md +170 -0
- package/docs/readmes/features/workflows/prepare-next.md +167 -0
- package/docs/readmes/features/workflows/review.md +169 -0
- package/docs/readmes/features/workflows/run-audit.md +191 -0
- package/docs/readmes/features/workflows/spec-challenge.md +159 -0
- package/docs/readmes/features/workflows/specify.md +160 -0
- package/docs/readmes/features/workflows/verify.md +177 -0
- package/docs/readmes/packages/README.md +50 -0
- package/docs/readmes/packages/ajv.md +117 -0
- package/docs/readmes/packages/context-mode.md +118 -0
- package/docs/readmes/packages/gray-matter.md +116 -0
- package/docs/readmes/packages/node-test.md +137 -0
- package/docs/readmes/packages/yaml.md +112 -0
- package/docs/reference/configuration-reference.md +159 -0
- package/docs/reference/expertise-index.md +52 -0
- package/docs/reference/git-flow.md +43 -0
- package/docs/reference/hooks.md +87 -0
- package/docs/reference/host-exports.md +50 -0
- package/docs/reference/launch-checklist.md +172 -0
- package/docs/reference/marketplace-listings.md +76 -0
- package/docs/reference/release-process.md +34 -0
- package/docs/reference/roles-reference.md +77 -0
- package/docs/reference/skills.md +33 -0
- package/docs/reference/templates.md +29 -0
- package/docs/reference/tooling-cli.md +94 -0
- package/docs/truth-claims.yaml +222 -0
- package/expertise/PROGRESS.md +63 -0
- package/expertise/README.md +18 -0
- package/expertise/antipatterns/PROGRESS.md +56 -0
- package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
- package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
- package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
- package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
- package/expertise/antipatterns/backend/index.md +24 -0
- package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
- package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
- package/expertise/antipatterns/code/async-antipatterns.md +622 -0
- package/expertise/antipatterns/code/code-smells.md +1186 -0
- package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
- package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
- package/expertise/antipatterns/code/index.md +27 -0
- package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
- package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
- package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
- package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
- package/expertise/antipatterns/design/dark-patterns.md +1121 -0
- package/expertise/antipatterns/design/index.md +22 -0
- package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
- package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
- package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
- package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
- package/expertise/antipatterns/frontend/index.md +23 -0
- package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
- package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
- package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
- package/expertise/antipatterns/index.md +31 -0
- package/expertise/antipatterns/performance/index.md +20 -0
- package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
- package/expertise/antipatterns/performance/premature-optimization.md +623 -0
- package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
- package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
- package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
- package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
- package/expertise/antipatterns/process/index.md +23 -0
- package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
- package/expertise/antipatterns/security/index.md +20 -0
- package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
- package/expertise/antipatterns/security/security-theater.md +843 -0
- package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
- package/expertise/architecture/PROGRESS.md +70 -0
- package/expertise/architecture/data/caching-architecture.md +671 -0
- package/expertise/architecture/data/data-consistency.md +574 -0
- package/expertise/architecture/data/data-modeling.md +536 -0
- package/expertise/architecture/data/event-streams-and-queues.md +634 -0
- package/expertise/architecture/data/index.md +25 -0
- package/expertise/architecture/data/search-architecture.md +663 -0
- package/expertise/architecture/data/sql-vs-nosql.md +708 -0
- package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
- package/expertise/architecture/decisions/build-vs-buy.md +616 -0
- package/expertise/architecture/decisions/index.md +23 -0
- package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
- package/expertise/architecture/decisions/technology-selection.md +616 -0
- package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
- package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
- package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
- package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
- package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
- package/expertise/architecture/distributed/index.md +25 -0
- package/expertise/architecture/distributed/saga-pattern.md +797 -0
- package/expertise/architecture/foundations/architectural-thinking.md +460 -0
- package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
- package/expertise/architecture/foundations/design-principles-solid.md +649 -0
- package/expertise/architecture/foundations/domain-driven-design.md +719 -0
- package/expertise/architecture/foundations/index.md +25 -0
- package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
- package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
- package/expertise/architecture/index.md +34 -0
- package/expertise/architecture/integration/api-design-graphql.md +638 -0
- package/expertise/architecture/integration/api-design-grpc.md +804 -0
- package/expertise/architecture/integration/api-design-rest.md +892 -0
- package/expertise/architecture/integration/index.md +25 -0
- package/expertise/architecture/integration/third-party-integration.md +795 -0
- package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
- package/expertise/architecture/integration/websockets-realtime.md +791 -0
- package/expertise/architecture/mobile-architecture/index.md +22 -0
- package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
- package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
- package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
- package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
- package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
- package/expertise/architecture/patterns/event-driven.md +797 -0
- package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
- package/expertise/architecture/patterns/index.md +27 -0
- package/expertise/architecture/patterns/layered-architecture.md +736 -0
- package/expertise/architecture/patterns/microservices.md +753 -0
- package/expertise/architecture/patterns/modular-monolith.md +692 -0
- package/expertise/architecture/patterns/monolith.md +626 -0
- package/expertise/architecture/patterns/plugin-architecture.md +735 -0
- package/expertise/architecture/patterns/serverless.md +780 -0
- package/expertise/architecture/scaling/database-scaling.md +615 -0
- package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
- package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
- package/expertise/architecture/scaling/index.md +24 -0
- package/expertise/architecture/scaling/multi-tenancy.md +800 -0
- package/expertise/architecture/scaling/stateless-design.md +787 -0
- package/expertise/backend/embedded-firmware.md +625 -0
- package/expertise/backend/go.md +853 -0
- package/expertise/backend/index.md +24 -0
- package/expertise/backend/java-spring.md +448 -0
- package/expertise/backend/node-typescript.md +625 -0
- package/expertise/backend/python-fastapi.md +724 -0
- package/expertise/backend/rust.md +458 -0
- package/expertise/backend/solidity.md +711 -0
- package/expertise/composition-map.yaml +443 -0
- package/expertise/content/foundations/content-modeling.md +395 -0
- package/expertise/content/foundations/editorial-standards.md +449 -0
- package/expertise/content/foundations/index.md +24 -0
- package/expertise/content/foundations/microcopy.md +455 -0
- package/expertise/content/foundations/terminology-governance.md +509 -0
- package/expertise/content/index.md +34 -0
- package/expertise/content/patterns/accessibility-copy.md +518 -0
- package/expertise/content/patterns/index.md +24 -0
- package/expertise/content/patterns/notification-content.md +433 -0
- package/expertise/content/patterns/sample-content.md +486 -0
- package/expertise/content/patterns/state-copy.md +439 -0
- package/expertise/design/PROGRESS.md +58 -0
- package/expertise/design/disciplines/dark-mode-theming.md +577 -0
- package/expertise/design/disciplines/design-systems.md +595 -0
- package/expertise/design/disciplines/index.md +25 -0
- package/expertise/design/disciplines/information-architecture.md +800 -0
- package/expertise/design/disciplines/interaction-design.md +788 -0
- package/expertise/design/disciplines/responsive-design.md +552 -0
- package/expertise/design/disciplines/usability-testing.md +516 -0
- package/expertise/design/disciplines/user-research.md +792 -0
- package/expertise/design/foundations/accessibility-design.md +796 -0
- package/expertise/design/foundations/color-theory.md +797 -0
- package/expertise/design/foundations/iconography.md +795 -0
- package/expertise/design/foundations/index.md +26 -0
- package/expertise/design/foundations/motion-and-animation.md +653 -0
- package/expertise/design/foundations/rtl-design.md +585 -0
- package/expertise/design/foundations/spacing-and-layout.md +607 -0
- package/expertise/design/foundations/typography.md +800 -0
- package/expertise/design/foundations/visual-hierarchy.md +761 -0
- package/expertise/design/index.md +32 -0
- package/expertise/design/patterns/authentication-flows.md +474 -0
- package/expertise/design/patterns/content-consumption.md +789 -0
- package/expertise/design/patterns/data-display.md +618 -0
- package/expertise/design/patterns/e-commerce.md +1494 -0
- package/expertise/design/patterns/feedback-and-states.md +642 -0
- package/expertise/design/patterns/forms-and-input.md +819 -0
- package/expertise/design/patterns/gamification.md +801 -0
- package/expertise/design/patterns/index.md +31 -0
- package/expertise/design/patterns/microinteractions.md +449 -0
- package/expertise/design/patterns/navigation.md +800 -0
- package/expertise/design/patterns/notifications.md +705 -0
- package/expertise/design/patterns/onboarding.md +700 -0
- package/expertise/design/patterns/search-and-filter.md +601 -0
- package/expertise/design/patterns/settings-and-preferences.md +768 -0
- package/expertise/design/patterns/social-and-community.md +748 -0
- package/expertise/design/platforms/desktop-native.md +612 -0
- package/expertise/design/platforms/index.md +25 -0
- package/expertise/design/platforms/mobile-android.md +825 -0
- package/expertise/design/platforms/mobile-cross-platform.md +983 -0
- package/expertise/design/platforms/mobile-ios.md +699 -0
- package/expertise/design/platforms/tablet.md +794 -0
- package/expertise/design/platforms/web-dashboard.md +790 -0
- package/expertise/design/platforms/web-responsive.md +550 -0
- package/expertise/design/psychology/behavioral-nudges.md +449 -0
- package/expertise/design/psychology/cognitive-load.md +1191 -0
- package/expertise/design/psychology/error-psychology.md +778 -0
- package/expertise/design/psychology/index.md +22 -0
- package/expertise/design/psychology/persuasive-design.md +736 -0
- package/expertise/design/psychology/user-mental-models.md +623 -0
- package/expertise/design/tooling/open-pencil.md +266 -0
- package/expertise/frontend/angular.md +1073 -0
- package/expertise/frontend/desktop-electron.md +546 -0
- package/expertise/frontend/flutter.md +782 -0
- package/expertise/frontend/index.md +27 -0
- package/expertise/frontend/native-android.md +409 -0
- package/expertise/frontend/native-ios.md +490 -0
- package/expertise/frontend/react-native.md +1160 -0
- package/expertise/frontend/react.md +808 -0
- package/expertise/frontend/vue.md +1089 -0
- package/expertise/humanize/domain-rules-code.md +79 -0
- package/expertise/humanize/domain-rules-content.md +67 -0
- package/expertise/humanize/domain-rules-technical-docs.md +56 -0
- package/expertise/humanize/index.md +35 -0
- package/expertise/humanize/self-audit-checklist.md +87 -0
- package/expertise/humanize/sentence-patterns.md +218 -0
- package/expertise/humanize/vocabulary-blacklist.md +105 -0
- package/expertise/i18n/PROGRESS.md +65 -0
- package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
- package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
- package/expertise/i18n/advanced/complex-scripts.md +30 -0
- package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
- package/expertise/i18n/advanced/testing-i18n.md +28 -0
- package/expertise/i18n/content/content-adaptation.md +23 -0
- package/expertise/i18n/content/locale-specific-formatting.md +23 -0
- package/expertise/i18n/content/machine-translation-integration.md +28 -0
- package/expertise/i18n/content/translation-management.md +29 -0
- package/expertise/i18n/foundations/date-time-calendars.md +67 -0
- package/expertise/i18n/foundations/i18n-architecture.md +272 -0
- package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
- package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
- package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
- package/expertise/i18n/foundations/string-externalization.md +236 -0
- package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
- package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
- package/expertise/i18n/index.md +38 -0
- package/expertise/i18n/platform/backend-i18n.md +31 -0
- package/expertise/i18n/platform/flutter-i18n.md +148 -0
- package/expertise/i18n/platform/native-android-i18n.md +36 -0
- package/expertise/i18n/platform/native-ios-i18n.md +36 -0
- package/expertise/i18n/platform/react-i18n.md +103 -0
- package/expertise/i18n/platform/web-css-i18n.md +81 -0
- package/expertise/i18n/rtl/arabic-specific.md +175 -0
- package/expertise/i18n/rtl/hebrew-specific.md +149 -0
- package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
- package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
- package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
- package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
- package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
- package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
- package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
- package/expertise/i18n/rtl/rtl-typography.md +160 -0
- package/expertise/index.md +113 -0
- package/expertise/index.yaml +216 -0
- package/expertise/infrastructure/cloud-aws.md +597 -0
- package/expertise/infrastructure/cloud-gcp.md +599 -0
- package/expertise/infrastructure/cybersecurity.md +816 -0
- package/expertise/infrastructure/database-mongodb.md +447 -0
- package/expertise/infrastructure/database-postgres.md +400 -0
- package/expertise/infrastructure/devops-cicd.md +787 -0
- package/expertise/infrastructure/index.md +27 -0
- package/expertise/performance/PROGRESS.md +50 -0
- package/expertise/performance/backend/api-latency.md +1204 -0
- package/expertise/performance/backend/background-jobs.md +506 -0
- package/expertise/performance/backend/connection-pooling.md +1209 -0
- package/expertise/performance/backend/database-query-optimization.md +515 -0
- package/expertise/performance/backend/index.md +23 -0
- package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
- package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
- package/expertise/performance/foundations/caching-strategies.md +489 -0
- package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
- package/expertise/performance/foundations/index.md +24 -0
- package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
- package/expertise/performance/foundations/memory-management.md +964 -0
- package/expertise/performance/foundations/performance-budgets.md +1314 -0
- package/expertise/performance/index.md +31 -0
- package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
- package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
- package/expertise/performance/infrastructure/index.md +22 -0
- package/expertise/performance/infrastructure/load-balancing.md +1081 -0
- package/expertise/performance/infrastructure/observability.md +1079 -0
- package/expertise/performance/mobile/index.md +23 -0
- package/expertise/performance/mobile/mobile-animations.md +544 -0
- package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
- package/expertise/performance/mobile/mobile-network.md +452 -0
- package/expertise/performance/mobile/mobile-rendering.md +599 -0
- package/expertise/performance/mobile/mobile-startup-time.md +505 -0
- package/expertise/performance/platform-specific/flutter-performance.md +647 -0
- package/expertise/performance/platform-specific/index.md +22 -0
- package/expertise/performance/platform-specific/node-performance.md +1307 -0
- package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
- package/expertise/performance/platform-specific/react-performance.md +1403 -0
- package/expertise/performance/web/bundle-optimization.md +1239 -0
- package/expertise/performance/web/image-and-media.md +636 -0
- package/expertise/performance/web/index.md +24 -0
- package/expertise/performance/web/network-optimization.md +1133 -0
- package/expertise/performance/web/rendering-performance.md +1098 -0
- package/expertise/performance/web/ssr-and-hydration.md +918 -0
- package/expertise/performance/web/web-vitals.md +1374 -0
- package/expertise/quality/accessibility.md +985 -0
- package/expertise/quality/evidence-based-verification.md +499 -0
- package/expertise/quality/index.md +24 -0
- package/expertise/quality/ml-model-audit.md +614 -0
- package/expertise/quality/performance.md +600 -0
- package/expertise/quality/testing-api.md +891 -0
- package/expertise/quality/testing-mobile.md +496 -0
- package/expertise/quality/testing-web.md +849 -0
- package/expertise/security/PROGRESS.md +54 -0
- package/expertise/security/agentic-identity.md +540 -0
- package/expertise/security/compliance-frameworks.md +601 -0
- package/expertise/security/data/data-encryption.md +364 -0
- package/expertise/security/data/data-privacy-gdpr.md +692 -0
- package/expertise/security/data/database-security.md +1171 -0
- package/expertise/security/data/index.md +22 -0
- package/expertise/security/data/pii-handling.md +531 -0
- package/expertise/security/foundations/authentication.md +1041 -0
- package/expertise/security/foundations/authorization.md +603 -0
- package/expertise/security/foundations/cryptography.md +1001 -0
- package/expertise/security/foundations/index.md +25 -0
- package/expertise/security/foundations/owasp-top-10.md +1354 -0
- package/expertise/security/foundations/secrets-management.md +1217 -0
- package/expertise/security/foundations/secure-sdlc.md +700 -0
- package/expertise/security/foundations/supply-chain-security.md +698 -0
- package/expertise/security/index.md +31 -0
- package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
- package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
- package/expertise/security/infrastructure/container-security.md +721 -0
- package/expertise/security/infrastructure/incident-response.md +1295 -0
- package/expertise/security/infrastructure/index.md +24 -0
- package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
- package/expertise/security/infrastructure/network-security.md +1337 -0
- package/expertise/security/mobile/index.md +23 -0
- package/expertise/security/mobile/mobile-android-security.md +1218 -0
- package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
- package/expertise/security/mobile/mobile-data-storage.md +1265 -0
- package/expertise/security/mobile/mobile-ios-security.md +1401 -0
- package/expertise/security/mobile/mobile-network-security.md +1520 -0
- package/expertise/security/smart-contract-security.md +594 -0
- package/expertise/security/testing/index.md +22 -0
- package/expertise/security/testing/penetration-testing.md +1258 -0
- package/expertise/security/testing/security-code-review.md +1765 -0
- package/expertise/security/testing/threat-modeling.md +1074 -0
- package/expertise/security/testing/vulnerability-scanning.md +1062 -0
- package/expertise/security/web/api-security.md +586 -0
- package/expertise/security/web/cors-and-headers.md +433 -0
- package/expertise/security/web/csrf.md +562 -0
- package/expertise/security/web/file-upload.md +1477 -0
- package/expertise/security/web/index.md +25 -0
- package/expertise/security/web/injection.md +1375 -0
- package/expertise/security/web/session-management.md +1101 -0
- package/expertise/security/web/xss.md +1158 -0
- package/exports/README.md +17 -0
- package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
- package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
- package/exports/hosts/claude/.claude/agents/designer.md +55 -0
- package/exports/hosts/claude/.claude/agents/executor.md +55 -0
- package/exports/hosts/claude/.claude/agents/learner.md +51 -0
- package/exports/hosts/claude/.claude/agents/planner.md +53 -0
- package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
- package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
- package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
- package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
- package/exports/hosts/claude/.claude/commands/author.md +42 -0
- package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
- package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
- package/exports/hosts/claude/.claude/commands/design.md +44 -0
- package/exports/hosts/claude/.claude/commands/discover.md +37 -0
- package/exports/hosts/claude/.claude/commands/execute.md +48 -0
- package/exports/hosts/claude/.claude/commands/learn.md +38 -0
- package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
- package/exports/hosts/claude/.claude/commands/plan.md +39 -0
- package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
- package/exports/hosts/claude/.claude/commands/review.md +40 -0
- package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
- package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
- package/exports/hosts/claude/.claude/commands/specify.md +38 -0
- package/exports/hosts/claude/.claude/commands/verify.md +37 -0
- package/exports/hosts/claude/.claude/settings.json +34 -0
- package/exports/hosts/claude/CLAUDE.md +19 -0
- package/exports/hosts/claude/export.manifest.json +38 -0
- package/exports/hosts/claude/host-package.json +67 -0
- package/exports/hosts/codex/AGENTS.md +19 -0
- package/exports/hosts/codex/export.manifest.json +38 -0
- package/exports/hosts/codex/host-package.json +41 -0
- package/exports/hosts/cursor/.cursor/hooks.json +16 -0
- package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
- package/exports/hosts/cursor/export.manifest.json +38 -0
- package/exports/hosts/cursor/host-package.json +42 -0
- package/exports/hosts/gemini/GEMINI.md +19 -0
- package/exports/hosts/gemini/export.manifest.json +38 -0
- package/exports/hosts/gemini/host-package.json +41 -0
- package/hooks/README.md +18 -0
- package/hooks/definitions/loop_cap_guard.yaml +21 -0
- package/hooks/definitions/post_tool_capture.yaml +24 -0
- package/hooks/definitions/pre_compact_summary.yaml +19 -0
- package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
- package/hooks/definitions/protected_path_write_guard.yaml +19 -0
- package/hooks/definitions/session_start.yaml +19 -0
- package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
- package/hooks/loop-cap-guard +17 -0
- package/hooks/post-tool-lint +36 -0
- package/hooks/protected-path-write-guard +17 -0
- package/hooks/session-start +41 -0
- package/llms-full.txt +2355 -0
- package/llms.txt +43 -0
- package/package.json +79 -0
- package/roles/README.md +20 -0
- package/roles/clarifier.md +42 -0
- package/roles/content-author.md +63 -0
- package/roles/designer.md +55 -0
- package/roles/executor.md +55 -0
- package/roles/learner.md +51 -0
- package/roles/planner.md +53 -0
- package/roles/researcher.md +43 -0
- package/roles/reviewer.md +54 -0
- package/roles/specifier.md +47 -0
- package/roles/verifier.md +71 -0
- package/schemas/README.md +24 -0
- package/schemas/accepted-learning.schema.json +20 -0
- package/schemas/author-artifact.schema.json +156 -0
- package/schemas/clarification.schema.json +19 -0
- package/schemas/design-artifact.schema.json +80 -0
- package/schemas/docs-claim.schema.json +18 -0
- package/schemas/export-manifest.schema.json +20 -0
- package/schemas/hook.schema.json +67 -0
- package/schemas/host-export-package.schema.json +18 -0
- package/schemas/implementation-plan.schema.json +19 -0
- package/schemas/proposed-learning.schema.json +19 -0
- package/schemas/research.schema.json +18 -0
- package/schemas/review.schema.json +29 -0
- package/schemas/run-manifest.schema.json +18 -0
- package/schemas/spec-challenge.schema.json +18 -0
- package/schemas/spec.schema.json +20 -0
- package/schemas/usage.schema.json +102 -0
- package/schemas/verification-proof.schema.json +29 -0
- package/schemas/wazir-manifest.schema.json +173 -0
- package/skills/README.md +40 -0
- package/skills/brainstorming/SKILL.md +77 -0
- package/skills/debugging/SKILL.md +50 -0
- package/skills/design/SKILL.md +61 -0
- package/skills/dispatching-parallel-agents/SKILL.md +128 -0
- package/skills/executing-plans/SKILL.md +70 -0
- package/skills/finishing-a-development-branch/SKILL.md +169 -0
- package/skills/humanize/SKILL.md +123 -0
- package/skills/init-pipeline/SKILL.md +124 -0
- package/skills/prepare-next/SKILL.md +20 -0
- package/skills/receiving-code-review/SKILL.md +123 -0
- package/skills/requesting-code-review/SKILL.md +105 -0
- package/skills/requesting-code-review/code-reviewer.md +108 -0
- package/skills/run-audit/SKILL.md +197 -0
- package/skills/scan-project/SKILL.md +41 -0
- package/skills/self-audit/SKILL.md +153 -0
- package/skills/subagent-driven-development/SKILL.md +154 -0
- package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
- package/skills/subagent-driven-development/implementer-prompt.md +102 -0
- package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
- package/skills/tdd/SKILL.md +23 -0
- package/skills/using-git-worktrees/SKILL.md +163 -0
- package/skills/using-skills/SKILL.md +95 -0
- package/skills/verification/SKILL.md +22 -0
- package/skills/wazir/SKILL.md +463 -0
- package/skills/writing-plans/SKILL.md +30 -0
- package/skills/writing-skills/SKILL.md +157 -0
- package/skills/writing-skills/anthropic-best-practices.md +122 -0
- package/skills/writing-skills/persuasion-principles.md +50 -0
- package/templates/README.md +20 -0
- package/templates/artifacts/README.md +10 -0
- package/templates/artifacts/accepted-learning.md +19 -0
- package/templates/artifacts/accepted-learning.template.json +12 -0
- package/templates/artifacts/author.md +74 -0
- package/templates/artifacts/author.template.json +19 -0
- package/templates/artifacts/clarification.md +21 -0
- package/templates/artifacts/clarification.template.json +12 -0
- package/templates/artifacts/execute-notes.md +19 -0
- package/templates/artifacts/implementation-plan.md +21 -0
- package/templates/artifacts/implementation-plan.template.json +11 -0
- package/templates/artifacts/learning-proposal.md +19 -0
- package/templates/artifacts/next-run-handoff.md +21 -0
- package/templates/artifacts/plan-review.md +19 -0
- package/templates/artifacts/proposed-learning.template.json +12 -0
- package/templates/artifacts/research.md +21 -0
- package/templates/artifacts/research.template.json +12 -0
- package/templates/artifacts/review-findings.md +19 -0
- package/templates/artifacts/review.template.json +11 -0
- package/templates/artifacts/run-manifest.template.json +8 -0
- package/templates/artifacts/spec-challenge.md +19 -0
- package/templates/artifacts/spec-challenge.template.json +11 -0
- package/templates/artifacts/spec.md +21 -0
- package/templates/artifacts/spec.template.json +12 -0
- package/templates/artifacts/verification-proof.md +19 -0
- package/templates/artifacts/verification-proof.template.json +11 -0
- package/templates/examples/accepted-learning.example.json +14 -0
- package/templates/examples/author.example.json +152 -0
- package/templates/examples/clarification.example.json +15 -0
- package/templates/examples/docs-claim.example.json +8 -0
- package/templates/examples/export-manifest.example.json +7 -0
- package/templates/examples/host-export-package.example.json +11 -0
- package/templates/examples/implementation-plan.example.json +17 -0
- package/templates/examples/proposed-learning.example.json +13 -0
- package/templates/examples/research.example.json +15 -0
- package/templates/examples/research.example.md +6 -0
- package/templates/examples/review.example.json +17 -0
- package/templates/examples/run-manifest.example.json +9 -0
- package/templates/examples/spec-challenge.example.json +14 -0
- package/templates/examples/spec.example.json +21 -0
- package/templates/examples/verification-proof.example.json +21 -0
- package/templates/examples/wazir-manifest.example.yaml +65 -0
- package/templates/task-definition-schema.md +99 -0
- package/tooling/README.md +20 -0
- package/tooling/src/adapters/context-mode.js +50 -0
- package/tooling/src/capture/command.js +376 -0
- package/tooling/src/capture/store.js +99 -0
- package/tooling/src/capture/usage.js +270 -0
- package/tooling/src/checks/branches.js +50 -0
- package/tooling/src/checks/brand-truth.js +110 -0
- package/tooling/src/checks/changelog.js +231 -0
- package/tooling/src/checks/command-registry.js +36 -0
- package/tooling/src/checks/commits.js +102 -0
- package/tooling/src/checks/docs-drift.js +103 -0
- package/tooling/src/checks/docs-truth.js +201 -0
- package/tooling/src/checks/runtime-surface.js +156 -0
- package/tooling/src/cli.js +116 -0
- package/tooling/src/command-options.js +56 -0
- package/tooling/src/commands/validate.js +320 -0
- package/tooling/src/doctor/command.js +91 -0
- package/tooling/src/export/command.js +77 -0
- package/tooling/src/export/compiler.js +498 -0
- package/tooling/src/guards/loop-cap-guard.js +52 -0
- package/tooling/src/guards/protected-path-write-guard.js +67 -0
- package/tooling/src/index/command.js +152 -0
- package/tooling/src/index/storage.js +1061 -0
- package/tooling/src/index/summarizers.js +261 -0
- package/tooling/src/loaders.js +18 -0
- package/tooling/src/project-root.js +22 -0
- package/tooling/src/recall/command.js +225 -0
- package/tooling/src/schema-validator.js +30 -0
- package/tooling/src/state-root.js +40 -0
- package/tooling/src/status/command.js +71 -0
- package/wazir.manifest.yaml +135 -0
- package/workflows/README.md +19 -0
- package/workflows/author.md +42 -0
- package/workflows/clarify.md +38 -0
- package/workflows/design-review.md +46 -0
- package/workflows/design.md +44 -0
- package/workflows/discover.md +37 -0
- package/workflows/execute.md +48 -0
- package/workflows/learn.md +38 -0
- package/workflows/plan-review.md +42 -0
- package/workflows/plan.md +39 -0
- package/workflows/prepare-next.md +37 -0
- package/workflows/review.md +40 -0
- package/workflows/run-audit.md +41 -0
- package/workflows/spec-challenge.md +41 -0
- package/workflows/specify.md +38 -0
- package/workflows/verify.md +37 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Directory Purpose
|
|
2
|
+
|
|
3
|
+
The `backend` directory provides language and framework-specific guidelines for building robust, secure, and scalable server-side applications and APIs.
|
|
4
|
+
|
|
5
|
+
# Key Concepts
|
|
6
|
+
|
|
7
|
+
- Backend framework idioms and conventions
|
|
8
|
+
- Dependency injection and routing
|
|
9
|
+
- Managing asynchronous operations and concurrency
|
|
10
|
+
|
|
11
|
+
# File Map
|
|
12
|
+
|
|
13
|
+
- `index.md` — semantic map of the backend directory
|
|
14
|
+
- `go.md` — Goroutines, channels, and standard library idioms
|
|
15
|
+
- `java-spring.md` — Spring Boot, dependency injection, and JPA
|
|
16
|
+
- `node-typescript.md` — Express/NestJS, event loop, and TS typing
|
|
17
|
+
- `python-fastapi.md` — Pydantic, async/await, and dependency injection
|
|
18
|
+
- `rust.md` — Cargo, ownership model, and safe concurrency
|
|
19
|
+
|
|
20
|
+
# Reading Guide
|
|
21
|
+
|
|
22
|
+
If writing a Node service → read `node-typescript.md`
|
|
23
|
+
If writing a high-performance systems service → read `go.md` or `rust.md`
|
|
24
|
+
If writing a Python API → read `python-fastapi.md`
|
|
@@ -0,0 +1,448 @@
|
|
|
1
|
+
# Java + Spring Boot — Expertise Module
|
|
2
|
+
|
|
3
|
+
> A Java/Spring Boot specialist designs, builds, and maintains backend services using the Spring ecosystem on
|
|
4
|
+
> Java 21+. Scope covers REST/GraphQL APIs, data access, security, messaging, observability, and cloud-native
|
|
5
|
+
> deployment — from monolith to microservices — with emphasis on production-grade reliability and performance.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Core Patterns & Conventions
|
|
10
|
+
|
|
11
|
+
### 1.1 Project Structure
|
|
12
|
+
|
|
13
|
+
**Feature-based packaging** over layer-based for anything beyond trivial services. Group all layers
|
|
14
|
+
(controller, service, repository, model) per domain concept for cohesion and future extractability.
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
com.example.app
|
|
18
|
+
├── order/ # Feature package
|
|
19
|
+
│ ├── OrderController.java
|
|
20
|
+
│ ├── OrderService.java
|
|
21
|
+
│ ├── OrderRepository.java
|
|
22
|
+
│ ├── Order.java
|
|
23
|
+
│ └── OrderDto.java
|
|
24
|
+
├── product/
|
|
25
|
+
├── shared/ # Cross-cutting: exceptions, config, security
|
|
26
|
+
└── Application.java
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Multi-module** rule: one module per deployable artifact. Common split: `app-api` (controllers),
|
|
30
|
+
`app-domain` (entities, services, ports — no Spring), `app-infrastructure` (JPA, messaging adapters),
|
|
31
|
+
`app-common` (shared DTOs, exceptions).
|
|
32
|
+
|
|
33
|
+
### 1.2 Naming Conventions
|
|
34
|
+
|
|
35
|
+
| Element | Convention | Example |
|
|
36
|
+
|------------------|------------------------|----------------------------------|
|
|
37
|
+
| Classes | PascalCase, noun | `OrderService`, `PaymentGateway` |
|
|
38
|
+
| Interfaces | No `I` prefix | `OrderRepository` |
|
|
39
|
+
| Methods | camelCase, verb-first | `findByStatus()`, `cancelOrder()`|
|
|
40
|
+
| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
|
|
41
|
+
| REST endpoints | kebab-case, plural | `/api/v1/purchase-orders` |
|
|
42
|
+
| Config properties| kebab-case | `app.order-service.max-retries` |
|
|
43
|
+
| DB tables/cols | snake_case | `purchase_order`, `created_at` |
|
|
44
|
+
|
|
45
|
+
### 1.3 Architecture Patterns
|
|
46
|
+
|
|
47
|
+
- **Layered** (simple CRUD): Controller -> Service -> Repository -> DB. Quick, sufficient for small contexts.
|
|
48
|
+
- **Hexagonal / Ports & Adapters** (complex domains): Domain at center with zero framework deps. Inbound ports define use cases; outbound ports define infra contracts. Preferred for DDD, well-supported by Spring Modulith.
|
|
49
|
+
- **DDD tactical patterns**: Entities (identity + lifecycle), Value Objects (immutable, use records), Aggregates (consistency boundaries), Domain Events (via `ApplicationEventPublisher`), Repositories (one per aggregate root).
|
|
50
|
+
|
|
51
|
+
### 1.4 Spring Boot 3.x Patterns
|
|
52
|
+
|
|
53
|
+
- **Auto-configuration**: Override selectively via `@ConditionalOnProperty` / `@ConditionalOnMissingBean`. Exclude specific classes, not wholesale: `@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})`
|
|
54
|
+
- **Profiles**: `application-{profile}.yml` for env config (`dev`, `test`, `prod`). Prefer externalized config (env vars, config maps) over profile-specific `@Configuration` classes.
|
|
55
|
+
- **Custom starters**: For shared cross-cutting concerns in multi-service orgs: `company-spring-boot-starter-observability`.
|
|
56
|
+
|
|
57
|
+
### 1.5 Dependency Injection
|
|
58
|
+
|
|
59
|
+
**Constructor injection is mandatory** (Spring team recommendation). Immutable fields, testable without reflection, fails fast. Single constructor needs no `@Autowired`. Use `@Qualifier` for disambiguation. Never use `@Autowired` on fields.
|
|
60
|
+
|
|
61
|
+
### 1.6 Data Access
|
|
62
|
+
|
|
63
|
+
- **Spring Data JPA** (default): `JpaRepository<T, ID>`, derived queries, `@Query` JPQL, `@Transactional(readOnly = true)` on reads, projections (interfaces/records) for read-only queries.
|
|
64
|
+
- **JdbcClient** (Spring Boot 3.2+): Lightweight alternative for simple/bulk queries.
|
|
65
|
+
- **R2DBC**: Only with WebFlux end-to-end; mixing with blocking JPA defeats the purpose.
|
|
66
|
+
|
|
67
|
+
### 1.7 Error Handling — RFC 7807 ProblemDetail
|
|
68
|
+
|
|
69
|
+
Enable globally with `spring.mvc.problemdetails.enabled: true`. Combine with `@RestControllerAdvice extends ResponseEntityExceptionHandler` for custom exception mapping. Return `ProblemDetail` with `type`, `title`, `status`, `detail`, and custom properties.
|
|
70
|
+
|
|
71
|
+
### 1.8 Logging & Observability
|
|
72
|
+
|
|
73
|
+
- **Structured logging**: SLF4J + Logback with `logstash-logback-encoder` (JSON in prod). Include trace/span IDs via Micrometer.
|
|
74
|
+
- **Micrometer + OpenTelemetry**: Micrometer as metrics facade; OTLP export for metrics, traces, logs (Spring Boot 3.2+). Use `@Observed` for custom observations. Spring Boot 4 adds `spring-boot-starter-opentelemetry`.
|
|
75
|
+
|
|
76
|
+
### 1.9 Virtual Threads (Project Loom)
|
|
77
|
+
|
|
78
|
+
Enable: `spring.threads.virtual.enabled: true` (Spring Boot 3.2+). Configures Tomcat/Jetty + `@Async` + executors.
|
|
79
|
+
|
|
80
|
+
**Rules**: Replace `synchronized` with `ReentrantLock` (avoid carrier-thread pinning). Never pool virtual threads. Use `ScopedValue` over `ThreadLocal`. Monitor pinning: `-Djdk.tracePinnedThreads=short`. Increase HikariCP pool size for higher concurrency.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## 2. Anti-Patterns & Pitfalls
|
|
85
|
+
|
|
86
|
+
### 2.1 Field Injection Everywhere
|
|
87
|
+
`@Autowired` on fields hides dependencies, prevents immutability, requires reflection for testing. Use constructor injection.
|
|
88
|
+
|
|
89
|
+
### 2.2 God Service Classes
|
|
90
|
+
Services with 20+ methods spanning multiple domains violate SRP. Split by bounded context or use case.
|
|
91
|
+
|
|
92
|
+
### 2.3 Catching Exception/Throwable Generically
|
|
93
|
+
Swallows programming errors (`NullPointerException`, `IllegalStateException`). Catch specific exceptions; let unexpected ones reach the global handler.
|
|
94
|
+
|
|
95
|
+
### 2.4 N+1 Query Problem
|
|
96
|
+
Lazy-loaded collections trigger one query per entity (100 orders = 101 queries). Fix: `@EntityGraph`, `JOIN FETCH`, or DTO projections.
|
|
97
|
+
|
|
98
|
+
### 2.5 Missing @Transactional(readOnly = true)
|
|
99
|
+
Read-write transactions on read paths hold write locks, prevent replica routing, waste connection time.
|
|
100
|
+
|
|
101
|
+
### 2.6 Unbounded Caches
|
|
102
|
+
`@Cacheable` without TTL or max-size causes OOM. Always configure eviction; monitor hit rates.
|
|
103
|
+
|
|
104
|
+
### 2.7 Full Spring Context in Unit Tests
|
|
105
|
+
`@SpringBootTest` for a single class loads everything — tests take seconds instead of ms. Use JUnit + Mockito for units; slice tests for layers.
|
|
106
|
+
|
|
107
|
+
### 2.8 Business Logic in Controllers
|
|
108
|
+
Controllers should handle HTTP concerns only. Business rules in controllers can't be reused (messaging, scheduled tasks) and are harder to test.
|
|
109
|
+
|
|
110
|
+
### 2.9 Ignoring Connection Pool Configuration
|
|
111
|
+
HikariCP defaults (`maximumPoolSize=10`) are rarely optimal. With virtual threads, connection starvation is common. Size based on load: `connections = (core_count * 2) + spindle_count`.
|
|
112
|
+
|
|
113
|
+
### 2.10 Returning JPA Entities from Controllers
|
|
114
|
+
Exposes internal schema, creates DB-API coupling, risks infinite recursion with bidirectional relationships, leaks sensitive fields. Map to DTOs (records).
|
|
115
|
+
|
|
116
|
+
### 2.11 Hardcoded Configuration Values
|
|
117
|
+
Connection strings, timeouts in code require recompilation. Use `@ConfigurationProperties` with `@Validated`.
|
|
118
|
+
|
|
119
|
+
### 2.12 No Database Migrations
|
|
120
|
+
`ddl-auto=update` in production causes unpredictable changes and data loss. Use Flyway or Liquibase.
|
|
121
|
+
|
|
122
|
+
### 2.13 Synchronous Microservice Chains
|
|
123
|
+
HTTP calls across 5+ services multiply latency and cascade failures. Use async messaging for non-critical flows; circuit breakers (Resilience4j) for sync calls.
|
|
124
|
+
|
|
125
|
+
### 2.14 Missing Input Validation
|
|
126
|
+
Trusting client input leads to injection, corrupt data, cryptic errors. Bean Validation (`@Valid`) at controller boundary; domain validation in constructors.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 3. Testing Strategy
|
|
131
|
+
|
|
132
|
+
### 3.1 Unit Testing (JUnit 5 + Mockito + AssertJ)
|
|
133
|
+
Test classes in isolation, no Spring context. `@ExtendWith(MockitoExtension.class)`, `@Mock`, `@InjectMocks`. Use AssertJ fluent assertions (`assertThat`, `assertThatThrownBy`).
|
|
134
|
+
|
|
135
|
+
### 3.2 Slice Testing
|
|
136
|
+
- **@WebMvcTest**: Controller layer with MockMvc; mock services via `@MockBean`.
|
|
137
|
+
- **@DataJpaTest**: JPA repos with embedded DB or Testcontainers. Auto-configures `EntityManager` only.
|
|
138
|
+
|
|
139
|
+
### 3.3 Integration Testing (Testcontainers)
|
|
140
|
+
Spring Boot 3.1+ first-class support. Use `@ServiceConnection` (replaces `@DynamicPropertySource`) for automatic datasource/broker config from containers. Prefer Testcontainers over H2 for realistic tests.
|
|
141
|
+
|
|
142
|
+
```java
|
|
143
|
+
@SpringBootTest
|
|
144
|
+
@Testcontainers
|
|
145
|
+
class OrderIntegrationTest {
|
|
146
|
+
@Container @ServiceConnection
|
|
147
|
+
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
|
|
148
|
+
|
|
149
|
+
@Autowired OrderService orderService;
|
|
150
|
+
|
|
151
|
+
@Test
|
|
152
|
+
void shouldPersistAndRetrieveOrder() {
|
|
153
|
+
var id = orderService.placeOrder(new CreateOrderCommand(...));
|
|
154
|
+
assertThat(orderService.findById(id).status()).isEqualTo(OrderStatus.PLACED);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 3.4 Contract Testing (Spring Cloud Contract)
|
|
160
|
+
Define contracts in Groovy/YAML. Producer generates tests; consumer gets stub server. Ensures API compatibility without deploying both services.
|
|
161
|
+
|
|
162
|
+
### 3.5 Architecture Testing (ArchUnit)
|
|
163
|
+
Enforce layer dependencies, no-field-injection rules, naming conventions, and cycle-free packages as unit tests. Integrates with JUnit 5. Current version: 1.4.x (2025).
|
|
164
|
+
|
|
165
|
+
### 3.6 Testing Pyramid
|
|
166
|
+
|
|
167
|
+
| Level | Framework | Speed | Ratio |
|
|
168
|
+
|--------------|----------------------------|---------|-------|
|
|
169
|
+
| Unit | JUnit 5 + Mockito | ms | 70% |
|
|
170
|
+
| Slice | @WebMvcTest / @DataJpaTest | ~1-3s | 15% |
|
|
171
|
+
| Integration | @SpringBootTest + TC | ~5-15s | 10% |
|
|
172
|
+
| Contract | Spring Cloud Contract | ~2-5s | 5% |
|
|
173
|
+
| Architecture | ArchUnit | ms | + |
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## 4. Performance Considerations
|
|
178
|
+
|
|
179
|
+
### 4.1 JVM Tuning
|
|
180
|
+
- **GC**: G1GC (default, balanced); ZGC for low-latency (<1ms pauses).
|
|
181
|
+
- **Heap**: `-Xms` = `-Xmx` in containers (avoid resize overhead). JVM auto-detects cgroup limits (Java 10+).
|
|
182
|
+
- **Always on in prod**: `-Xlog:gc*:file=gc.log:time`. Set `-XX:MaxMetaspaceSize`.
|
|
183
|
+
|
|
184
|
+
### 4.2 Startup Optimization
|
|
185
|
+
|
|
186
|
+
| Technique | Impact | Trade-off |
|
|
187
|
+
|------------------------|-----------------|-------------------------------------|
|
|
188
|
+
| GraalVM Native Image | ~50-75ms start | Long build, no runtime reflection |
|
|
189
|
+
| CDS (Class Data Sharing)| 30-50% faster | Requires training run |
|
|
190
|
+
| Lazy init | 30-40% faster | First request slower |
|
|
191
|
+
| Spring AOT | 20-30% faster | Build-time bean resolution |
|
|
192
|
+
|
|
193
|
+
### 4.3 HikariCP Connection Pooling
|
|
194
|
+
Tune `maximum-pool-size` (default 10 is rarely enough), `idle-timeout`, `max-lifetime`, `leak-detection-threshold`. Increase pool size with virtual threads — more concurrent requests means more simultaneous connection demand.
|
|
195
|
+
|
|
196
|
+
### 4.4 Caching
|
|
197
|
+
Caffeine for local (TTL, max-size, async refresh). Redis for distributed. Always set TTL + max-size; monitor hit/miss with Micrometer. Use `@Cacheable(unless = "#result == null")`.
|
|
198
|
+
|
|
199
|
+
### 4.5 Virtual Threads vs WebFlux
|
|
200
|
+
|
|
201
|
+
| Criterion | MVC + Virtual Threads | WebFlux (Reactive) |
|
|
202
|
+
|-----------------|---------------------------|---------------------------|
|
|
203
|
+
| Code style | Imperative (familiar) | Functional/reactive |
|
|
204
|
+
| Debugging | Standard stack traces | Complex async traces |
|
|
205
|
+
| DB support | JDBC, JPA (full ecosystem)| R2DBC (limited) |
|
|
206
|
+
| Backpressure | Manual (semaphore) | Built-in (Reactor) |
|
|
207
|
+
| Best for | 90% of enterprise apps | Streaming, gateways, SSE |
|
|
208
|
+
|
|
209
|
+
**Default (2025+)**: MVC + virtual threads for new projects.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 5. Security Considerations
|
|
214
|
+
|
|
215
|
+
### 5.1 Spring Security 6.x
|
|
216
|
+
Component-based config — no `WebSecurityConfigurerAdapter`. Declare `SecurityFilterChain` bean. Use `requestMatchers()` (not deprecated `antMatchers()`).
|
|
217
|
+
|
|
218
|
+
### 5.2 OAuth2 Resource Server
|
|
219
|
+
Add `spring-boot-starter-oauth2-resource-server`. Configure `spring.security.oauth2.resourceserver.jwt.issuer-uri`. Validate `aud` claim. Use `oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))`.
|
|
220
|
+
|
|
221
|
+
### 5.3 Method-Level Security
|
|
222
|
+
`@EnableMethodSecurity` (replaces `@EnableGlobalMethodSecurity`). Use `@PreAuthorize` / `@PostAuthorize` with SpEL expressions for fine-grained access control.
|
|
223
|
+
|
|
224
|
+
### 5.4 CSRF & CORS
|
|
225
|
+
Disable CSRF only for stateless APIs (JWT/OAuth2). Configure CORS explicitly per origin — never `allowedOrigins("*")` in production. Set allowed methods and headers explicitly.
|
|
226
|
+
|
|
227
|
+
### 5.5 Input Validation
|
|
228
|
+
Bean Validation on DTOs (`@NotNull`, `@Size`, `@Positive`) + `@Valid` at controller boundary. Custom validators for cross-field logic. Domain validation in constructors as second defense.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## 6. Integration Patterns
|
|
233
|
+
|
|
234
|
+
### 6.1 REST API (Spring MVC + OpenAPI)
|
|
235
|
+
Use `springdoc-openapi-starter-webmvc-ui` (2.8.x) for OpenAPI 3.x + Swagger UI. Generate client SDKs with OpenAPI Generator.
|
|
236
|
+
|
|
237
|
+
### 6.2 Messaging
|
|
238
|
+
- **Spring Kafka**: `@KafkaListener(topics, groupId)` for consumers.
|
|
239
|
+
- **Spring Cloud Stream**: Broker-agnostic — define `Function`/`Consumer`/`Supplier` beans, bind via config. Switch Kafka <-> RabbitMQ without code changes.
|
|
240
|
+
|
|
241
|
+
### 6.3 GraphQL
|
|
242
|
+
Built-in support in Spring Boot 3.x. `@QueryMapping`, `@SchemaMapping` for resolvers. Supports batching via `@BatchMapping`.
|
|
243
|
+
|
|
244
|
+
### 6.4 Scheduling
|
|
245
|
+
`@Scheduled(cron = ...)` + ShedLock (`@SchedulerLock`) for distributed locking in multi-instance deployments. Spring Batch or Quartz for complex orchestration.
|
|
246
|
+
|
|
247
|
+
### 6.5 Event-Driven (Spring Modulith)
|
|
248
|
+
Inter-module communication via `ApplicationEventPublisher` + `@ApplicationModuleListener` (transactional, at-least-once). Events externalize to Kafka/RabbitMQ via `@EnableSpringCloudStreamEventExternalization` — no code changes in publisher.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## 7. DevOps & Deployment
|
|
253
|
+
|
|
254
|
+
### 7.1 Build Tools
|
|
255
|
+
- **Gradle Kotlin DSL**: 2-3x faster (incremental + caching). Recommended for multi-module / complex builds.
|
|
256
|
+
- **Maven**: ~52% market share (2025). Simpler, more predictable. Better for conventional single-module projects.
|
|
257
|
+
|
|
258
|
+
### 7.2 Docker
|
|
259
|
+
- **Buildpacks** (preferred): `./gradlew bootBuildImage` — no Dockerfile, OCI-compliant, auto-patched base images.
|
|
260
|
+
- **Layered Jars**: Optimize Docker layer caching when using custom Dockerfiles.
|
|
261
|
+
|
|
262
|
+
### 7.3 CI/CD (GitHub Actions)
|
|
263
|
+
Setup: `actions/setup-java@v4` with `distribution: temurin`, `java-version: 21`, `cache: gradle`. Build + test + `bootBuildImage` + push to GHCR.
|
|
264
|
+
|
|
265
|
+
### 7.4 GraalVM Native Images
|
|
266
|
+
Spring Boot 3+ first-class support via Spring AOT: `./gradlew nativeCompile`. Startup ~50-75ms, memory ~50-80MB. Trade-off: long builds, reflection limitations. Best for serverless / scale-to-zero.
|
|
267
|
+
|
|
268
|
+
### 7.5 Monitoring
|
|
269
|
+
Actuator endpoints: `health`, `metrics`, `prometheus`. Key alerts: `jvm.memory.used`, `http.server.requests` duration, `hikaricp.connections.active`, `jvm.gc.pause`.
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## 8. Decision Trees
|
|
274
|
+
|
|
275
|
+
### 8.1 Spring MVC vs WebFlux vs Virtual Threads
|
|
276
|
+
|
|
277
|
+
```
|
|
278
|
+
I/O-bound app?
|
|
279
|
+
├── YES
|
|
280
|
+
│ ├── Need streaming / SSE / WebSocket with backpressure? → WebFlux
|
|
281
|
+
│ ├── Need >500K concurrent connections (gateway)? → WebFlux
|
|
282
|
+
│ └── Otherwise → Spring MVC + Virtual Threads (Java 21+)
|
|
283
|
+
└── NO (CPU-bound) → Spring MVC (traditional thread pool)
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Default (2025+): **MVC + virtual threads** for new projects.
|
|
287
|
+
|
|
288
|
+
### 8.2 Gradle vs Maven
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
Greenfield project?
|
|
292
|
+
├── YES
|
|
293
|
+
│ ├── Multi-module / complex build logic → Gradle Kotlin DSL
|
|
294
|
+
│ ├── Simple single-module → Maven (simpler) or Gradle (faster)
|
|
295
|
+
│ └── Team has Gradle experience → Gradle
|
|
296
|
+
└── NO → Keep current unless build time is a measurable bottleneck
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### 8.3 Monolith vs Microservices
|
|
300
|
+
|
|
301
|
+
```
|
|
302
|
+
Team size?
|
|
303
|
+
├── 1-3 devs / single team → Modular Monolith (Spring Modulith)
|
|
304
|
+
├── 4-10 devs, 2-3 teams
|
|
305
|
+
│ ├── Boundaries clear and stable? → Microservices (Spring Cloud)
|
|
306
|
+
│ └── Boundaries unclear → Spring Modulith; extract when stable
|
|
307
|
+
└── 10+ devs, many teams → Microservices + service discovery + config server
|
|
308
|
+
+ circuit breakers + distributed tracing
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
**Key insight**: Start with modular monolith. Premature microservices are the #1 architectural mistake. Spring Modulith makes later extraction safe.
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## 9. Code Examples
|
|
316
|
+
|
|
317
|
+
### 9.1 REST Controller with Validation (Java 21+)
|
|
318
|
+
|
|
319
|
+
```java
|
|
320
|
+
@RestController
|
|
321
|
+
@RequestMapping("/api/v1/orders")
|
|
322
|
+
public class OrderController {
|
|
323
|
+
private final OrderService orderService;
|
|
324
|
+
public OrderController(OrderService orderService) { this.orderService = orderService; }
|
|
325
|
+
|
|
326
|
+
@PostMapping
|
|
327
|
+
ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest req) {
|
|
328
|
+
var order = orderService.placeOrder(req.toCommand());
|
|
329
|
+
return ResponseEntity.created(URI.create("/api/v1/orders/" + order.id()))
|
|
330
|
+
.body(OrderResponse.from(order));
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
@GetMapping
|
|
334
|
+
Page<OrderResponse> list(@RequestParam(defaultValue = "0") int page,
|
|
335
|
+
@RequestParam(defaultValue = "20") int size) {
|
|
336
|
+
return orderService.findAll(PageRequest.of(page, size)).map(OrderResponse::from);
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// DTOs as records
|
|
341
|
+
public record CreateOrderRequest(@NotNull @Positive Long productId, @Min(1) int quantity) {
|
|
342
|
+
public CreateOrderCommand toCommand() { return new CreateOrderCommand(productId, quantity); }
|
|
343
|
+
}
|
|
344
|
+
public record OrderResponse(Long id, String status, BigDecimal total, Instant createdAt) {
|
|
345
|
+
public static OrderResponse from(Order o) {
|
|
346
|
+
return new OrderResponse(o.id(), o.status().name(), o.total(), o.createdAt());
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
### 9.2 Domain Entity with DDD Patterns
|
|
352
|
+
|
|
353
|
+
```java
|
|
354
|
+
@Entity @Table(name = "orders")
|
|
355
|
+
public class Order {
|
|
356
|
+
@Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;
|
|
357
|
+
@Enumerated(EnumType.STRING) @Column(nullable = false) private OrderStatus status;
|
|
358
|
+
@Embedded private Money total;
|
|
359
|
+
@Column(nullable = false, updatable = false) private Instant createdAt;
|
|
360
|
+
@OneToMany(cascade = CascadeType.ALL, orphanRemoval = true) private List<OrderItem> items = new ArrayList<>();
|
|
361
|
+
|
|
362
|
+
protected Order() {} // JPA
|
|
363
|
+
public static Order create(CreateOrderCommand cmd) {
|
|
364
|
+
var order = new Order();
|
|
365
|
+
order.status = OrderStatus.PLACED;
|
|
366
|
+
order.createdAt = Instant.now();
|
|
367
|
+
order.items.addAll(cmd.items().stream().map(OrderItem::from).toList());
|
|
368
|
+
order.total = order.items.stream().map(OrderItem::subtotal).reduce(Money.ZERO, Money::add);
|
|
369
|
+
return order;
|
|
370
|
+
}
|
|
371
|
+
public void cancel() {
|
|
372
|
+
if (status != OrderStatus.PLACED)
|
|
373
|
+
throw new IllegalStateException("Cannot cancel order in status: " + status);
|
|
374
|
+
this.status = OrderStatus.CANCELLED;
|
|
375
|
+
}
|
|
376
|
+
// Getters only — no setters
|
|
377
|
+
public Long id() { return id; }
|
|
378
|
+
public OrderStatus status() { return status; }
|
|
379
|
+
public Money total() { return total; }
|
|
380
|
+
}
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
### 9.3 Type-Safe Configuration Properties
|
|
384
|
+
|
|
385
|
+
```java
|
|
386
|
+
@ConfigurationProperties(prefix = "app.order-service")
|
|
387
|
+
@Validated
|
|
388
|
+
public record OrderServiceProperties(
|
|
389
|
+
@NotNull @DurationMin(seconds = 1) Duration paymentTimeout,
|
|
390
|
+
@Min(1) @Max(10) int maxRetries,
|
|
391
|
+
@NotBlank String notificationQueue
|
|
392
|
+
) {}
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
### 9.4 Global Error Handler (RFC 7807)
|
|
396
|
+
|
|
397
|
+
```java
|
|
398
|
+
@RestControllerAdvice
|
|
399
|
+
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
|
|
400
|
+
@ExceptionHandler(OrderNotFoundException.class)
|
|
401
|
+
ProblemDetail handleNotFound(OrderNotFoundException ex) {
|
|
402
|
+
var pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
|
|
403
|
+
pd.setTitle("Order Not Found");
|
|
404
|
+
pd.setType(URI.create("https://api.example.com/errors/order-not-found"));
|
|
405
|
+
pd.setProperty("orderId", ex.getOrderId());
|
|
406
|
+
return pd;
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
### 9.5 Structured Concurrency with Virtual Threads (Java 21+)
|
|
412
|
+
|
|
413
|
+
```java
|
|
414
|
+
@Service
|
|
415
|
+
public class OrderEnrichmentService {
|
|
416
|
+
private final ProductClient productClient;
|
|
417
|
+
private final CustomerClient customerClient;
|
|
418
|
+
|
|
419
|
+
public EnrichedOrder enrich(Long orderId) throws Exception {
|
|
420
|
+
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
|
|
421
|
+
var product = scope.fork(() -> productClient.findById(orderId));
|
|
422
|
+
var customer = scope.fork(() -> customerClient.findByOrderId(orderId));
|
|
423
|
+
scope.join().throwIfFailed();
|
|
424
|
+
return new EnrichedOrder(product.get(), customer.get());
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
*Researched: 2026-03-07 | Sources:*
|
|
433
|
+
- [Spring Boot Official Docs — Structuring Your Code](https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html)
|
|
434
|
+
- [Spring Boot Anti-Patterns (DEV.to)](https://dev.to/haraf/spring-boot-anti-patterns-killing-your-app-performance-in-2025-with-real-fixes-explanations-2p05)
|
|
435
|
+
- [10 Anti-Patterns That Infect Your Architecture](https://medium.com/@praveengaddam319/the-toxic-side-of-spring-boot-10-anti-patterns-that-infect-your-architecture-a771697795ef)
|
|
436
|
+
- [Spring Boot Testcontainers Docs](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html)
|
|
437
|
+
- [Virtual Threads Performance Guide](https://java.elitedev.in/java/spring-boot-virtual-thread-pool-complete-performance-optimization-guide-for-java-21-263d0f04/)
|
|
438
|
+
- [WebFlux vs Virtual Threads Decision Matrix (2026)](https://simplifiedlearningblog.com/webflux-vs-virtual-threads-java/)
|
|
439
|
+
- [OAuth2 Resource Server — Spring Security Docs](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html)
|
|
440
|
+
- [GraalVM + Spring Boot Best Practices](https://www.javacodegeeks.com/2025/08/graalvm-and-spring-boot-best-practices-for-native-image-spring-apps.html)
|
|
441
|
+
- [ProblemDetail / RFC 7807 (Baeldung)](https://www.baeldung.com/spring-boot-return-errors-problemdetail)
|
|
442
|
+
- [OpenTelemetry with Spring Boot (Spring Blog)](https://spring.io/blog/2025/11/18/opentelemetry-with-spring-boot/)
|
|
443
|
+
- [Spring Modulith Event-Driven (Spring I/O 2025)](https://2025.springio.net/sessions/event-driven-architectures-with-spring-modulith-and-asyncapi/)
|
|
444
|
+
- [ArchUnit](https://www.archunit.org/)
|
|
445
|
+
- [Hexagonal Architecture, DDD, and Spring (Baeldung)](https://www.baeldung.com/hexagonal-architecture-ddd-spring)
|
|
446
|
+
- [Paketo Buildpacks for Spring Boot](https://github.com/paketo-buildpacks/spring-boot)
|
|
447
|
+
- [Maven vs Gradle 2025](https://quashbugs.com/blog/maven-vs-gradle-choosing-the-right-build-tool-for-api-heavy-backends-2025)
|
|
448
|
+
- [Spring Boot Observability (Voxxed Days 2026)](https://m.devoxx.com/events/vdcern26/talks/4059/spring-boot-observability-in-practice-actuator-micrometer-and-opentelemetry)
|