Tech stack design

Tech Stack Design

<!-- 中文说明: 技术选型不能拍脑袋，必须先基于业务规模、企业约束和官方兼容性资料生成候选方案。 -->

Purpose

Use this skill to produce a defensible technology stack decision. The output must be based on project constraints plus Context7 or official documentation, not model memory.

Preconditions

Before recommending a stack, confirm that the project has at least:

• Business domain and target users.
• System type: internal admin, public web, mobile/client, integration service, batch/data processing, API platform, or microservice system.
• Rough functional scope.
• Rough non-functional needs: scale, concurrency, latency, availability, data volume, security, compliance.
• Enterprise constraints: existing JDK, Spring Boot line, database, middleware, deployment platform, team skill, legacy integration.

If these are missing, ask clarification questions first.

Evidence Rules

• First use Context7 for current official or versioned documentation.
• If Context7 cannot resolve the library, use official documentation via web search.
• If neither source is available, mark the option as needs-confirmation and do not present it as a recommendation.
• For every recommended version, record the evidence source, compatibility constraints, and risk.
• Do not recommend the newest version by default. Prefer supported, mature, ecosystem-compatible versions.
• Do not select JDK 17, JDK 21, Spring Boot 3.x, Spring Boot 4.x, or any major version just because it is common or modern. Present supported options and ask the user to confirm enterprise constraints.
• Do not collapse technology selection into one pre-filled stack. Present choices by dimension, with a recommended default and alternatives.
• Native choice widgets are client-dependent. When asking the user to choose between stack options, show a numbered list and ask for the number or option name if no structured choice UI is available.

Selection Workflow

1. Identify project type and business scale.
2. Identify runtime and organizational constraints: JDK baseline, deployment platform, database, middleware, compliance, team familiarity, release timeline.
3. Build a compatibility matrix before recommending:
   • JDK.
   • Spring Boot.
   • Spring Framework.
   • Spring Cloud.
   • Spring Cloud Alibaba.
   • MyBatis Plus or other data access library.
   • springdoc-openapi or API documentation tooling.
   • frontend framework and build tool.
4. Identify component-level choices and present options before finalizing:
   • Build tool and dependency management.
   • Web model.
   • Logging and trace correlation.
   • Global exception handling.
   • Validation.
   • ORM/data access.
   • Connection pool.
   • Database migration.
   • Cache.
   • Messaging.
   • Registry/discovery and config center.
   • Gateway/API entry.
   • Resilience/circuit breaking.
   • Security/authentication.
   • Observability.
   • Code quality and architecture checks.
5. Produce 2-3 viable stack baselines, then ask the user to confirm the recommended path if enterprise constraints are uncertain. Use numbered options in non-UI clients.
6. Output an ADR-style decision record.

Choice Fallback Format

When presenting stack candidates, use a fallback like:

Choose a stack option:
1. Legacy-compatible baseline - only when enterprise constraints require older versions
2. Conservative supported baseline - mature Spring Boot line with broad ecosystem compatibility
3. Current major baseline - Spring Boot 4.x or latest major only when ecosystem compatibility is proven

Reply with a number or option name.

Never hard-code Spring Boot 3.x in the option label unless the compatibility matrix has already shown why 3.x is the recommended line for this project.

Java Stack Decision Points

<!-- 中文说明: 后端不是只选 JDK 和 Spring Boot，还要覆盖日志、异常、校验、数据访问、迁移、安全、观测和质量工具。 -->

For Java/Spring projects, cover at least:

• JDK: supported LTS options and enterprise baseline, such as 17, 21, or newer runtime-supported options.
• Spring Boot: supported stable lines and ecosystem compatibility. Include Spring Boot 4.x as a candidate when official support and dependency compatibility can be proven.
• Spring Cloud: only if distributed service patterns are actually needed.
• Spring Cloud Alibaba: only when Nacos/Sentinel/Seata/Alibaba ecosystem is required.
• Web framework: Spring MVC or WebFlux, based on actual concurrency and programming model needs.
• Build tool: Maven or Gradle.
• Data access: MyBatis Plus, MyBatis, Spring Data JPA, jOOQ, or direct SQL, based on team and domain complexity.
• Connection pool: HikariCP default, Druid when monitoring or enterprise convention requires it, or team-standard pool.
• Database migration: Flyway, Liquibase, or team-standard migration process.
• API documentation: springdoc-openapi and optional Apifox collaboration.
• Validation: Jakarta Bean Validation.
• Exception model: global error response and business error code standard.
• Logging: SLF4J with Logback default, Log4j2 when enterprise policy requires it, trace id, and structured logging needs.
• Security: Spring Security, gateway auth, SSO/OIDC, JWT, or enterprise IAM.
• Registry/discovery: Nacos, Consul, Eureka, Kubernetes service discovery, or none.
• Config center: Nacos Config, Spring Cloud Config, Kubernetes ConfigMap/Secret, or none.
• Gateway/API entry: Spring Cloud Gateway, Apache APISIX, Nginx, Kong, or none.
• Resilience: Sentinel, Resilience4j, or team-standard policy.
• Distributed transaction: Seata only when distributed transaction requirements justify it.
• Observability: Actuator, metrics, tracing, log aggregation.
• Testing: JUnit, Spring Boot Test, Testcontainers where applicable.
• Quality: formatter, Checkstyle/PMD/SpotBugs, ArchUnit.
• Upgrade governance: OpenRewrite where useful.

Java Component Selection Checklist

<!-- 中文说明: Spring Boot 工程不是只选版本，常见组件都要给用户机会确认。 -->

Before final ADR, present a compact component checklist:

Confirm Java stack components:
1. Build tool: Maven / Gradle
2. JDK line: 17 / 21 / newer supported runtime
3. Spring Boot line: 3.5.x / 4.x / existing enterprise line
4. Architecture style: monolith / modular monolith / microservices
5. Web model: Spring MVC / WebFlux
6. Data access: MyBatis Plus / MyBatis / Spring Data JPA / jOOQ / direct SQL
7. Connection pool: HikariCP / Druid / team standard
8. Migration: Flyway / Liquibase / manual/team process
9. API docs: springdoc-openapi / Apifox collaboration / none
10. Logging: SLF4J+Logback / Log4j2 / team standard
11. Security: Spring Security / SSO-OIDC / JWT / gateway auth / none for prototype
12. Cache: Redis / none / team standard
13. Messaging: Kafka / RocketMQ / RabbitMQ / none
14. Registry/config: Nacos / Consul / Eureka / Kubernetes / none
15. Gateway: Spring Cloud Gateway / APISIX / Nginx / Kong / none
16. Resilience: Sentinel / Resilience4j / none
17. Observability: Actuator+Micrometer / OpenTelemetry / log-only / team standard
18. Quality: formatter / Checkstyle / PMD / SpotBugs / ArchUnit

Reply with changes, constraints, or "use recommended defaults".

Compatibility Gate

Before finalizing, explicitly check known compatibility risks:

• Spring Boot major version versus third-party autoconfigure APIs.
• MyBatis Plus compatibility with the selected Spring Boot line.
• Spring Cloud and Spring Cloud Alibaba version mapping.
• Java baseline required by Spring Boot and dependencies.
• Jakarta EE namespace changes for Spring Boot 3+.
• Native image or AOT constraints if requested.

If any key dependency is incompatible, reject that stack option.

Project Structure Decision

Project structure is primarily owned by architecture-design. When it is missing, ask the user to confirm or route back to architecture before implementation.

Confirm or reference:

• Repository mode: default backend + frontend monorepo for V1.
• Backend root path, default backend/.
• Frontend root path, default frontend/.
• Java groupId and basePackage; both require user confirmation.
• Service/module naming.
• Documentation path, default docs/.
• Database script path, default scripts/db/.
• Database migration path, default scripts/db/migration/.
• Seed data path, default scripts/db/seed/.
• Integration test script path, default scripts/test/integration/.
• Performance test script path, default scripts/perf/.
• Deployment/config path, default scripts/deploy/.
• Raw verification output path, default reports/verification/.
• Raw integration test output path, default reports/integration/.
• Raw performance test output path, default reports/performance/.
• Root README and .gitignore expectations.

Record this in docs/01-architecture/project-structure.md or the equivalent legacy artifact.

Output Format

Produce:

• Context summary.
• Candidate stack table.
• Compatibility matrix.
• Recommended stack.
• Component selection table.
• Project structure reference or unresolved structure decisions.
• Evidence sources.
• Rejected alternatives and why.
• Risks and mitigations.
• Follow-up decisions.

Use references/java-stack-evidence.md for the evidence checklist.

After producing the technology stack decision or ADR, stop and request explicit user review. Do not proceed to detailed requirements, API/database design, dependency scaffolding, or code generation until the user approves the decision.