name: springboot-init description: Use when initializing or extending an enterprise Spring Boot monolith or modular monolith with domain-first packages, MyBatis persistence, DTO/record APIs, and scenario-driven security choices such as session, token, external IdP, or machine credentials, plus optional Redis/Kafka/Elasticsearch/OSS/LLM-RAG integration.

springboot-init

Overview

Use this skill as the entry point for reusable enterprise Spring Boot monolith and modular-monolith work. It encodes the default rules for real-world backend projects, not a CRUD scaffold or microservice playbook. Security must be chosen to fit the client type, trust boundary, and identity source rather than assumed from one preferred auth pattern.

When to Use

• New enterprise Spring Boot backend initialization.
• Adding or refactoring a business domain module.
• Standardizing API, security, persistence, exception, cache, search, or messaging boundaries.
• Integrating Redis, Kafka, Elasticsearch, OSS, or LLM/RAG collaboration.

Technology Baseline

• Spring Boot 3.x and JDK 21.
• MyBatis is the default persistence layer.
• Use Spring Security when the application exposes protected endpoints.
• Select the authentication profile by scenario instead of hardcoding one default across every system.
• Keep an existing OAuth2 Resource Server, session, SSO, or equivalent security setup when the repo already uses it.
• DTO/record-based API models; direct DTO responses or ResponseEntity.
• Optional infrastructure collaborators: Redis/Redisson, Kafka, Elasticsearch, OSS, LLM/RAG.

Architecture Rules

• Organize by business domain first; do not default to global three-layer packaging.
• Keep domain packages focused and route package-layout detail to references/package-layout.md.
• Keep controllers thin, services orchestration-focused, and mappers persistence-only.
• Use common only for cross-domain concerns; route deeper patterns to references/architecture-patterns.md.

API Conventions

• Prefer record for request and response DTOs.
• Return DTOs directly for simple reads; use ResponseEntity when HTTP status or headers matter.
• Do not expose persistence entities to clients.
• Route detailed request, response, pagination, and HTTP semantics to references/api-conventions.md.

Error Handling and Security

• Choose the authentication profile before scaffolding auth code.
• Prefer one of these profiles based on scenario:
  • session-cookie for same-site admin systems or BFF-controlled browser flows
  • access-refresh-token for public user-facing APIs, mobile clients, or multi-device user sessions
  • external-idp for OIDC, SAML, or enterprise SSO environments
  • machine-to-machine for scheduled jobs, service accounts, or system integrations
• Use BusinessException, ErrorCode, and a single GlobalExceptionHandler as the default error model.
• Keep authorization in the security or service layer.
• Route implementation detail to references/security-and-exceptions.md.

Infrastructure Integration Rules

• Treat Redis, Kafka, Elasticsearch, OSS, and LLM/RAG as optional collaborators with isolated boundaries.
• Keep naming and placement rules centralized; route integration detail to references/infra-integration.md.

Actionable Workflows

Initialize an enterprise backend

1. Confirm the domain boundaries, client types, trust boundary, identity source, and required infrastructure collaborators.
2. Select the authentication profile that fits the scenario.
3. Set the domain-oriented package layout and shared foundation.
4. Apply the API, security, and error defaults before feature code.
5. Add infrastructure only when required.

Add a new business domain

1. Create the domain package and API contracts.
2. Define request/response DTOs and validation.
3. Implement service and persistence access.
4. Add infrastructure hooks only when required.

Add an async or read-optimized flow

1. Keep the primary store authoritative.
2. Define the event or read-model boundary.
3. Keep read-side collaborators isolated from write-path logic.
4. Put flow-specific detail in the reference docs.

Integrate a platform capability

1. Wrap the external system behind a domain-local integration service.
2. Centralize resource naming and client configuration.
3. Keep controllers and services free of SDK details.
4. Route capability-specific behavior to references/infra-integration.md.

Anti-Patterns

• Business logic in controllers.
• Returning entities directly from APIs.
• Using BaseResponse<T> as the default contract.
• Treating MyBatis-Plus as the default assumption.
• Treating access-plus-refresh-token auth as the default for every system.
• Using refresh tokens as bearer credentials on normal business endpoints.
• Skipping refresh-token rotation, revocation, or server-side validity checks when the chosen profile requires them.
• Building a local auth domain when an external IdP already owns login and session lifecycle.
• Scattering Redis keys, topic names, index names, or bucket names.
• Using Elasticsearch as the write-path source of truth.
• Coupling every domain to every infrastructure client.
• Leaking raw SDK or stack-trace details to callers.

References

• Use these for package layouts, API rules, security details, integration placement, and code skeletons.
• references/architecture-patterns.md
• references/package-layout.md
• references/api-conventions.md
• references/security-and-exceptions.md
• references/infra-integration.md
• references/code-templates.md