/clean-architecture

name: clean-architecture
description: Provides implementation patterns for Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design in Java 21+ Spring Boot 3.5+ applications. Use when structuring layered architectures, separating domain logic from frameworks, implementing ports and adapters, creating entities/value objects/aggregates, or refactoring monolithic codebases for testability and maintainability.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Clean Architecture, Hexagonal Architecture & DDD for Spring Boot

Overview

This skill provides comprehensive guidance for implementing Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design tactical patterns in Java 21+ Spring Boot 3.5+ applications. It ensures clear separation of concerns, framework-independent domain logic, and highly testable codebases through proper layering and dependency management.

When to Use

• Architecting new Spring Boot applications with clear separation of concerns
• Refactoring tightly coupled code into testable, layered architectures
• Implementing domain logic independent of frameworks and infrastructure
• Designing ports and adapters for swappable implementations
• Applying Domain-Driven Design tactical patterns (entities, value objects, aggregates)
• Creating testable business logic without Spring context dependencies

Instructions

1. Understand the Core Concepts

Clean Architecture Layers (Dependency Rule)

Dependencies flow inward. Inner layers know nothing about outer layers.

| Layer | Responsibility | Spring Boot Equivalent | |-------|---------------|----------------------| | **Domain** | Entities, value objects, domain events, repository interfaces | `domain/` - no Spring annotations | | **Application** | Use cases, application services, DTOs, ports | `application/` - `@`Service, `@`Transactional | | **Infrastructure** | Frameworks, database, external APIs | `infrastructure/` - `@`Repository, `@`Entity | | **Adapter** | Controllers, presenters, external gateways | `adapter/` - `@`RestController |

Hexagonal Architecture (Ports & Adapters)

• **Domain Core**: Pure Java business logic, no framework dependencies
• **Ports**: Interfaces defining contracts (driven and driving)
• **Adapters**: Concrete implementations (JPA, REST, messaging)

Domain-Driven Design Tactical Patterns

• **Entities**: Objects with identity and lifecycle (e.g., `Order`, `Customer`)
• **Value Objects**: Immutable, defined by attributes (e.g., `Money`, `Email`)
• **Aggregates**: Consistency boundary with root entity
• **Domain Events**: Capture significant business occurrences
• **Repositories**: Persistence abstraction, implemented in infrastructure

2. Organize Package Structure

Follow this feature-based package organization:

com.example.order/
├── domain/
│   ├── model/              # Entities, value objects
│   ├── event/              # Domain events
│   ├── repository/         # Repository interfaces (ports)
│   └── exception/          # Domain exceptions
├── application/
│   ├── port/in/            # Driving ports (use case interfaces)
│   ├── port/out/           # Driven ports (external service interfaces)
│   ├── service/            # Application services
│   └── dto/                # Request/response DTOs
├── infrastructure/
│   ├── persistence/        # JPA entities, repository adapters
│   └── external/           # External service adapters
└── adapter/
    └── rest/               # REST controllers

3. Implement the Domain Layer (Framework-Free)

The domain layer must have zero dependencies on Spring or any framework.

• Use Java records for immutable value objects with built-in validation
• Place business logic in entities, not services (Rich Domain Model)
• Define repository interfaces (ports) in the domain layer
• Use strongly-typed IDs to prevent ID confusion
• Implement domain events for decoupling side effects
• Use factory methods for entity creation to enforce invariants

4. Implement the Application Layer

• Create use case interfaces (driving ports) in `application/port/in/`
• Create external service interfaces (driven ports) in `application/port/out/`
• Implement application services with `@Service` and `@Transactional`
• Use DTOs for request/response, separate from domain models
• Publish domain events after successful operations

5. Implement the Infrastructure Layer (Adapters)

• Create JPA entities in `infrastructure/persistence/`
• Implement repository adapters that map between domain and JPA entities
• Use MapStruct or manual mappers for domain-JPA conversion
• Configure conditional beans for swappable implementations
• Keep infrastructure concerns isolated from domain logic

6. Implement the Adapter Layer (REST)

• Create REST controllers in `adapter/rest/`
• Inject use case interfaces, not implementations
• Use Bean Validation on DTOs
• Return proper HTTP status codes and responses
• Handle exceptions with global exception handlers

7. Apply Best Practices

1. **Dependency Rule**: Domain has zero dependencies on Spring or other frameworks 2. **Immutable Value Objects**: Use Java records for value objects with built-in validation 3. **Rich Domain Models**: Place business logic in entities, not services 4. **Repository Pattern**: Domain defines interface, infrastructure implements 5. **Domain Events**: Decouple side effects from primary operations 6. **Constructor Injection**: Mandatory dependencies via final fields 7. **DTO Mapping**: Separate domain models from API contracts 8. **Transaction Boundaries**: Place `@`Transactional in application services 9. **Factory Methods**: Use `Entity.create()` for invariant enforcement during construction 10. **Separate JPA Entities**: Keep domain entities separate from JPA entities with mappers

8. Validate Architecture Compliance

After implementing each layer, verify the dependency rules are respected:

• **Domain