spring-boot-architecture

name	spring-boot-architecture
description	Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns.
metadata	{"triggers":{"files":["pom.xml","build.gradle"],"keywords":["structure","layering","dto","controller","@RestController","@Service","@Repository","@Entity","@Bean","@Configuration"]}}

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 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: all API responses using DTOs/Records instead of JPA Entities?
• Validation: @Valid and Jakarta Bean Validation constraints present on all input DTOs?
• Layer coupling: Services depend on Controllers? (Prohibited)
• Transactionality: business transactions correctly bounded with @Transactional in Service layer?
• Error Details: 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