spring-boot-architecture
Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)
Best use case
spring-boot-architecture is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)
Teams using spring-boot-architecture should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/spring-boot-architecture/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How spring-boot-architecture Compares
| Feature / Agent | spring-boot-architecture | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Spring Boot Architecture Standards ## **Priority: P0 (CRITICAL)** ## Organize by Feature - **Package by Feature**: Prefer `com.app.feature` (e.g., `user`, `order`) over technical layers (`controllers`) for scalability. - **Dependency Rule**: Outer layers (Web) depend on Inner (Service). Inner layers MUST NOT depend on Outer. - **DTO Pattern**: ALWAYS use DTOs for API inputs/outputs. NEVER return `@Entity` directly. - **Java Records**: Use `record` for DTOs to ensure immutability (Java 17+). See [implementation examples](references/implementation.md) for Java Record DTOs, controller patterns, and global exception handling. ## Define Layer Responsibilities 1. **Controller (Web)**: Handle HTTP, Validation (`@Valid`), DTO mapping. Delegate logic to Service. 2. **Service (Business)**: Transaction boundaries, orchestration. Returns Domain/DTOs. 3. **Repository (Data)**: Database interactions only. Returns Entities/Projections. ## Design API Layer - **Global Error Handling**: Use `@RestControllerAdvice` with `ProblemDetails` (RFC 7807). - **Validation**: Use Jakarta Bean Validation (`@NotNull`, `@Size`) on DTOs. - **Response**: Use `ResponseEntity` for explicit status or `ResponseStatusException`. ## Verification Checklist (Mandatory) - [ ] **No Entities in API**: Are all API responses using DTOs/Records instead of JPA Entities? - [ ] **Validation**: Are `@Valid` and Jakarta Bean Validation constraints present on all input DTOs? - [ ] **Layer coupling**: Do Services depend on Controllers? (Prohibited) - [ ] **Transactionality**: Are business transactions correctly bounded with `@Transactional` in the Service layer? - [ ] **Error Details**: Is `ProblemDetails` used for consistent error responses? ## Anti-Patterns - **No Fat Controllers**: Move business logic to Services. - **No Leaking Entities**: Use DTOs instead of JPA Entities in APIs. - **No Circular Dependencies**: Use Events or refactor to decouple services. - **No God Classes**: Split large services into single-responsibility components. ## References - [Implementation Examples](references/implementation.md)
Related Skills
spring-boot-testing
Write unit, integration, and slice tests for Spring Boot 3 applications. Use when writing unit tests, integration tests, or slice tests for Spring Boot 3 applications. (triggers: **/*Test.java, webmvctest, datajpatest, testcontainers, assertj)
spring-boot-security
Configure Spring Security 6+ with Lambda DSL, JWT, and hardening rules. Use when configuring Spring Security 6+, OAuth2, JWT, or security hardening in Spring Boot. (triggers: **/*SecurityConfig.java, **/*Filter.java, security-filter-chain, lambda-dsl, csrf, cors)
spring-boot-scheduling
Configure scheduled tasks and distributed locking with ShedLock in Spring Boot. Use when implementing @Scheduled tasks or distributed locking with ShedLock in Spring Boot. (triggers: **/*Scheduler.java, **/*Job.java, scheduled, shedlock, cron)
spring-boot-observability
Instrument Spring Boot with Micrometer metrics, distributed tracing, and structured logging. Use when adding Micrometer metrics, distributed tracing, or structured logging to Spring Boot. (triggers: logback-spring.xml, application.properties, micrometer, tracing, correlation-id, mdc)
spring-boot-microservices
Standards for Feign clients and asynchronous messaging with Spring Cloud Stream. Use when implementing Feign HTTP clients or async event messaging in Spring Boot microservices. (triggers: **/*Client.java, **/*Consumer.java, feign-client, spring-cloud-stream, rabbitmq, resilience4j)
spring-boot-deployment
Deploy Spring Boot apps with Docker, GraalVM native images, and graceful shutdown. Use when deploying Spring Boot apps as GraalVM native images, containers, or configuring shutdown. (triggers: Dockerfile, compose.yml, docker-layer, native-image, graceful-shutdown)
spring-boot-data-access
Optimize JPA, Hibernate, and database interactions in Spring Boot. Use when implementing JPA entities, repositories, or database access in Spring Boot. (triggers: **/*Repository.java, **/*Entity.java, jpa-repository, entity-graph, transactional, n-plus-1)
spring-boot-best-practices
Apply core coding standards, dependency injection, and configuration for Spring Boot 3. Use when applying Spring Boot 3 coding standards or configuring dependency injection. (triggers: application.properties, **/*Service.java, autowired, requiredargsconstructor, configuration-properties, slf4j)
spring-boot-api-design
Design Spring Boot APIs with OpenAPI, Versioning, and Global Error Handling. Use when designing Spring Boot APIs with OpenAPI specs, versioning, or global error handling. (triggers: **/*Controller.java, openapi, swagger, versioning, problemdetails)
react-native-architecture
Structure React Native projects with feature-first organization and separation of concerns. Use when structuring a React Native project or applying clean architecture patterns. (triggers: src/**/*.tsx, src/**/*.ts, app.json, feature, module, directory structure, separation of concerns, Expo, React Navigation, StyleSheet.create, react-native, mobile architecture)
nextjs-architecture
Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)
nestjs-architecture
Design decoupled, testable NestJS module boundaries with feature, core, and shared modules. Use when structuring module imports, creating feature modules, or enforcing separation of concerns in NestJS. (triggers: **/*.module.ts, main.ts, NestFactory, Module, Controller, Injectable)