Clean Architecture + DDD + Hexagonal Skill

Clean Architecture + DDD + Hexagonal

Backend architecture combining DDD tactical patterns, Clean Architecture dependency rules, and Hexagonal ports/adapters for maintainable, testable systems.

When to Use (and When NOT to)

| Use When | Skip When | |----------|-----------| | Complex business domain with many rules | Simple CRUD, few business rules | | Long-lived system (years of maintenance) | Prototype, MVP, throwaway code | | Team of 5+ developers | Solo developer or small team (1-2) | | Multiple entry points (API, CLI, events) | Single entry point, simple API | | Need to swap infrastructure (DB, broker) | Fixed infrastructure, unlikely to change | | High test coverage required | Quick scripts, internal tools |

Start simple. Evolve complexity only when needed. Most systems don't need full CQRS or Event Sourcing.

CRITICAL: The Dependency Rule

Dependencies point inward only. Outer layers depend on inner layers, never the reverse.

Infrastructure → Application → Domain
   (adapters)     (use cases)    (core)

Violations to catch:

Domain importing database/HTTP libraries
Controllers calling repositories directly (bypassing use cases)
Entities depending on application services

Design validation: "Create your application to work without either a UI or a database" — Alistair Cockburn. If you can run your domain logic from tests with no infrastructure, your boundaries are correct.

Quick Decision Trees

"Where does this code go?"

Where does it go?
├─ Pure business logic, no I/O           → domain/
├─ Orchestrates domain + has side effects → application/
├─ Talks to external systems              → infrastructure/
├─ Defines HOW to interact (interface)    → port (domain or application)
└─ Implements a port                      → adapter (infrastructure)

"Is this an Entity or Value Object?"

Entity or Value Object?
├─ Has unique identity that persists → Entity
├─ Defined only by its attributes    → Value Object
├─ "Is this THE same thing?"         → Entity (identity comparison)
└─ "Does this have the same value?"  → Value Object (structural equality)

"Should this be its own Aggregate?"

Aggregate boundaries?
├─ Must be consistent together in a transaction → Same aggregate
├─ Can be eventually consistent                 → Separate aggregates
├─ Referenced by ID only                        → Separate aggregates
└─ >10 entities in aggregate                    → Split it

Rule: One aggregate per transaction. Cross-aggregate consistency via domain events (eventual consistency).

Directory Structure

src/
├── domain/                    # Core business logic (NO external dependencies)
│   ├── {aggregate}/
│   │   ├── entity              # Aggregate root + child entities
│   │   ├── value_objects       # Immutable value types
│   │   ├── events              # Domain events
│   │   ├── repository          # Repository interface (DRIVEN PORT)
│   │   └── services            # Domain services (stateless logic)
│   └── shared/
│       └── errors              # Domain errors
├── application/               # Use cases / Application services
│   ├── {use-case}/
│   │   ├── command             # Command/Query DTOs
│   │   ├── handler             # Use case implementation
│   │   └── port                # Driver port interface
│   └── shared/
│       └── unit_of_work        # Transaction abstraction
├── infrastructure/            # Adapters (external concerns)
│   ├── persistence/           # Database adapters
│   ├── messaging/             # Message broker adapters
│   ├── http/                  # REST/GraphQL adapters (DRIVER)
│   └── config/
│       └── di                  # Dependency injection / composition root
└── main                        # Bootstrap / entry point

DDD Building Blocks

| Pattern | Purpose | Layer | Key Rule | |---------|---------|-------|----------| | Entity | Identity + behavior | Domain | Equality by ID | | Value Object | Immutable data | Domain | Equality by value, no setters | | Aggregate | Consistency boundary | Domain | Only root is referenced externally | | Domain Event | Record of change | Domain | Past tense naming (OrderPlaced) | | Repository | Persistence abstraction | Domain (port) | Per aggregate, not per table | | Domain Service | Stateless logic | Domain | When logic doesn't fit an entity | | Application Service | Orchestration | Application | Coordinates domain + infra |

Anti-Patterns (CRITICAL)

| Anti-Pattern | Problem | Fix | |--------------|---------|-----| | Anemic Domain Model | Entities are data bags, logic in services | Move behavior INTO entities | | Repository per Entity | Breaks aggregate boundaries | One repository per AGGREGATE | | Leaking Infrastructure | Domain imports DB/HTTP libs | Domain has ZERO external deps | | God Aggregate | Too many entities, slow transactions | Split into smaller aggregates | | Skipping Ports | Controllers → Repositories directly | Always go through application layer | | CRUD Thinking | Modeling data, not behavior | Model business operations | | Premature CQRS | Adding complexity before needed | Start with simple read/write, evolve | | Cross-Aggregate TX | Multiple aggregates in one transaction | Use domain events for consistency |

Implementation Order

Discover the Domain — Event Storming, conversations with domain experts
Model the Domain — Entities, value objects, aggregates (no infra)
Define Ports — Repository interfaces, external service interfaces
Implement Use Cases — Application services coordinating domain
Add Adapters last — HTTP, database, messaging implementations

DDD is collaborative. Modeling sessions with domain experts are as important as the code patterns.

Reference Documentation

| File | Purpose | |------|---------| | references/LAYERS.md | Complete layer specifications | | references/DDD-STRATEGIC.md | Bounded contexts, context mapping | | references/DDD-TACTICAL.md | Entities, value objects, aggregates (pseudocode) | | references/HEXAGONAL.md | Ports, adapters, naming | | references/CQRS-EVENTS.md | Command/query separation, events | | references/TESTING.md | Unit, integration, architecture tests | | references/CHEATSHEET.md | Quick decision guide |

Sources

Primary Sources

The Clean Architecture — Robert C. Martin (2012)
Hexagonal Architecture — Alistair Cockburn (2005)
Domain-Driven Design: The Blue Book — Eric Evans (2003)
Implementing Domain-Driven Design — Vaughn Vernon (2013)

Pattern References

CQRS — Martin Fowler
Event Sourcing — Martin Fowler
Repository Pattern — Martin Fowler (PoEAA)
Unit of Work — Martin Fowler (PoEAA)
Bounded Context — Martin Fowler
Transactional Outbox — microservices.io
Effective Aggregate Design — Vaughn Vernon

Implementation Guides

Microsoft: DDD + CQRS Microservices
Domain Events — Udi Dahan

Agent Skills: Clean Architecture + DDD + Hexagonal

Install this agent skill to your local

Skill Files