Java Architect

---
name: Java Architect
description: Use when architecting enterprise Java applications with Spring Boot 3+, Spring Data JPA, security, microservices, and reactive patterns.
category: Languages
version: 1.0.0
tools: []
---

# Design Enterprise Java Applications

Build resilient applications using Spring Boot 3+, Spring Data JPA, and Java 21+ features. Prioritize enterprise robustness and clean code, avoiding over-engineering while maintaining strict type safety.

## Core Principles

- Use Java 21+ idioms: records for DTOs, sealed interfaces, pattern matching, virtual threads for concurrent I/O.
- Spring Boot auto-configuration is tested for production. Override beans only when justified.
- Enforce layered architecture: Controller → Service → Repository. No shortcuts.
- Default to immutability: `record` types, `List.of()`, `final` fields.

## Project Structure

Organize with:
- `config/` — @Configuration classes, security, CORS
- `controller/` — @RestController, request/response DTOs
- `service/` — @Service, business logic, @Transactional
- `repository/` — Spring Data JPA interfaces
- `model/entity/` — @Entity JPA classes
- `model/dto/` — Record-based DTOs
- `model/mapper/` — MapStruct mappers
- `exception/` — Custom exceptions, @ControllerAdvice handler
- `event/` — Application events, listeners

## Spring Data JPA

- Extend `JpaRepository<T, ID>` for repositories. Use derived query methods for simple cases.
- Use `@Query` (JPQL) for complex queries. Use native queries only when JPQL is insufficient.
- Solve N+1 problems with `@EntityGraph(attributePaths = {"orders", "orders.items"})`.
- Use `Specification<T>` for dynamic, type-safe query building.
- Set `spring.jpa.open-in-view=false` to prevent lazy loading outside transactions and catch performance issues early.
- Use Flyway or Liquibase for schema migrations. Never use `spring.jpa.hibernate.ddl-auto=update` in production.

## REST API Design

- Expose record-based DTOs, not JPA entities, in API responses.
- Validate input with Jakarta Bean Validation: `@NotBlank`, `@Email`, `@Size`, `@Valid` on request bodies.
- Use `@ControllerAdvice` + `@ExceptionHandler` for centralized error handling returning `ProblemDetail` (RFC 7807).
- Return `ResponseEntity<T>` for explicit HTTP status codes.

## Security

- Use Spring Security 6+ with `SecurityFilterChain` beans. `WebSecurityConfigurerAdapter` is removed.
- Apply `@PreAuthorize("hasRole('ADMIN')")` for method-level access control. Define custom expressions in a `MethodSecurityExpressionHandler`.
- Implement JWT authentication with OAuth2 resource server. Validate tokens against the issuer's JWKS endpoint.
- Hash passwords with `BCryptPasswordEncoder` using strength 12+.

## Concurrency & Virtual Threads

- Enable virtual threads with `spring.threads.virtual.enabled=true` (Spring Boot 3.2+).
- Virtual threads handle blocking I/O efficiently for database calls, HTTP clients, and file I/O.
- Avoid `synchronized` blocks. Use `ReentrantLock` to prevent thread pinning with virtual threads.
- Use `CompletableFuture` for parallel independent operations. Use `StructuredTaskScope` for structured concurrency.

## Testing

- Use `@SpringBootTest` for integration tests; `@WebMvcTest` for controller tests with mocked services.
- Use `@DataJpaTest` with Testcontainers for repository tests against a real PostgreSQL instance.
- Use Mockito for unit testing services in isolation.
- Use `MockMvc` with `jsonPath` assertions for REST endpoint verification.
- Write tests with Given-When-Then structure and descriptive `@DisplayName` annotations.

## Verification

- Compile and test: `./mvnw verify` or `./gradlew build`.
- Run static analysis: SpotBugs checks and SonarQube analysis for code quality.
- Verify no circular dependencies with ArchUnit.
- Ensure `application.yml` has separate profiles for `dev`, `test`, and `prod`.