# System Architecture & Invariants: Spring Boot 4 & Java 25 Specialist

## 1. System Overview
Java standards for Spring Boot 4 (Spring Framework 7) on Java 25. Enforces record DTOs, virtual threads, jakarta.* namespaces, HTTP service clients, and Spring Data JPA optimization.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Spring Boot 4 (Spring Framework 7)
- **Language Standard**: Java 25 LTS (Records, Virtual Threads)
- **UI & Styling**: None / API Service
- **Data Persistence**: PostgreSQL / Spring Data JPA / Hibernate 7
- **Engineering Philosophy**: strict

## 2. Core Architectural Invariants
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## 5. Domain-Specific Invariants
- Prefer constructor dependency injection over @Autowired field injection.
- Handle business exceptions via @RestControllerAdvice with ProblemDetail (RFC 7807) responses.

## 6. Implementation Reference Patterns

### Preferred Pattern
```ts
public record CreateOrderRequest(
    @NotBlank String customerId,
    @Positive BigDecimal amount
) {}

public record OrderResponse(Long id, String customerId, BigDecimal amount) {}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {
    private final OrderService orderService;
    public OrderController(OrderService orderService) { this.orderService = orderService; }

    @PostMapping
    public ResponseEntity<OrderResponse> create(@RequestBody @Valid CreateOrderRequest request) {
        return ResponseEntity.ok(orderService.processOrder(request));
    }
}
```

### Forbidden Anti-Pattern
```ts
import javax.persistence.*; // Obsolete since Spring Boot 3; use jakarta.persistence

public class BadOrderDTO {
    private String customerId;
    public String getCustomerId() { return customerId; }
    public void setCustomerId(String id) { this.customerId = id; }
}
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Use jakarta.* packages for persistence, validation, and servlet APIs; ban legacy javax.* imports.
2. Model request and response DTOs using native Java Records with Jakarta validation constraints.
3. Enable virtual threads (spring.threads.virtual.enabled=true) for blocking I/O throughput.
4. Configure Spring Security using SecurityFilterChain beans; never extend WebSecurityConfigurerAdapter.
5. Eliminate JPA N+1 queries using @EntityGraph or JOIN FETCH JPQL expressions.
6. Call other HTTP APIs through @HttpExchange interfaces (HTTP service clients) instead of hand-built RestTemplate code.