java-spring-enterprise

When to activate

• Scaffolding a new Spring Boot enterprise project
• "How do I structure this feature?" in a Java/Spring context
• Designing a service layer, use case, or domain model
• Configuring @Transactional — any question about transactions, isolation, or rollback
• Setting up HikariCP connection pool tuning
• Implementing Virtual Threads (Java 21+) for I/O-heavy operations
• Adding observability: Micrometer, Prometheus, Grafana, OpenTelemetry tracing
• Refactoring a fat controller or a service with too many responsibilities
• Any mention of Hexagonal Architecture, ports/adapters, DDD, or use cases in Java

Rules — Non-negotiable

1. No business logic in controllers. Controllers receive HTTP input, delegate to a use case or service, and return a response. Nothing else.

2. Domain layer has zero Spring dependencies. Entities and domain services must not import Spring annotations. Domain is framework-agnostic.

3. @Transactional is not a default annotation. Apply it deliberately, with the correct isolation level. Add readOnly = true for all read operations.

4. Never expose domain entities in API responses. Always map to DTOs or response records before returning from the controller.

5. HikariCP pool size must be tuned explicitly. The default pool size (10) is wrong for most enterprise workloads. Always configure based on load profile.

Project Structure — Clean / Hexagonal Architecture

src/main/java/com/company/app/
├── domain/
│   ├── model/              # Entities, Value Objects, Aggregates — NO Spring here
│   ├── port/
│   │   ├── in/             # Use case interfaces (driving ports)
│   │   └── out/            # Repository + external service interfaces (driven ports)
│   └── service/            # Domain services — pure business logic
│
├── application/
│   └── usecase/            # Use case implementations — orchestrate domain + ports
│       ├── CreateOrderUseCase.java
│       └── GetOrderByIdUseCase.java
│
├── adapter/
│   ├── in/
│   │   └── web/            # Controllers, request/response DTOs, mappers
│   └── out/
│       ├── persistence/    # JPA entities, repositories (Spring Data)
│       └── external/       # HTTP clients, message producers
│
└── config/                 # Spring configuration, beans, security