domain-driven-design

Domain-Driven Design Skill

Apply DDD to build software that reflects deep understanding of the business domain.

Quick Reference

Core Workflow

1. Identify the Task Type

Designing new system? → Start with strategic design, then tactical Refactoring existing code? → Assess current state, identify bounded contexts, refactor incrementally Generating scaffolding? → Determine patterns needed, generate code Event Storming? → Follow facilitation guide Code review? → Apply DDD checklist

2. Strategic Before Tactical

Always establish strategic design first:

1. Identify subdomains (Core, Supporting, Generic)
2. Define bounded contexts and their boundaries
3. Map context relationships (upstream/downstream, conformist, ACL, etc.)
4. Establish ubiquitous language per context

3. Select Architecture Pattern

Choose based on domain complexity and requirements:

Patterns can be combined (e.g., Hexagonal + CQRS + Event Sourcing).

4. Apply Tactical Patterns

Select tactical building blocks based on needs:

5. Implementation Guidelines

General principles:

• Domain layer has ZERO infrastructure dependencies
• Depend on abstractions (interfaces/protocols), not concretions
• One aggregate = one repository = one transaction
• Aggregates reference other aggregates by ID only
• Validate invariants within aggregate boundaries
• Use domain events for cross-aggregate communication

Language selection:

• Read python-patterns.md for Python with Pydantic, SQLAlchemy, FastAPI
• Read typescript-patterns.md for TypeScript with NestJS, TypeORM, Prisma

Project Structure Template

src/
├── domain/                    # Pure domain logic (no dependencies)
│   ├── model/                 # Entities, Value Objects, Aggregates
│   ├── service/               # Domain Services
│   ├── event/                 # Domain Events
│   ├── repository/            # Repository interfaces (ports)
│   └── specification/         # Business rule specifications
├── application/               # Use cases, orchestration
│   ├── command/               # Command handlers (write)
│   ├── query/                 # Query handlers (read)
│   ├── dto/                   # Data transfer objects
│   └── service/               # Application services
├── infrastructure/            # External concerns
│   ├── persistence/           # Repository implementations
│   ├── messaging/             # Event bus, message queue
│   └── external/              # Third-party integrations
└── interface/                 # Delivery mechanisms
    ├── api/                   # REST/GraphQL controllers
    ├── cli/                   # Command-line interface
    └── event/                 # Event consumers

Anti-Patterns to Avoid

• Anemic Domain Model: Entities with only getters/setters, logic in services
• God Aggregate: Too many entities in one aggregate
• Shared Kernel Abuse: Overusing shared code between contexts
• Infrastructure Leak: Database concerns in domain layer
• Missing Ubiquitous Language: Technical terms instead of domain terms
• Aggregate Reference by Object: Should reference by ID only
• Transaction Across Aggregates: Violates consistency boundaries

When NOT to Use DDD

DDD adds complexity. Avoid for:

• Simple CRUD applications
• Technical/infrastructure projects without complex business logic
• Prototypes or throwaway code
• Teams unfamiliar with the domain (learn domain first)

Use DDD when:

• Complex, evolving business logic
• Long-lived systems requiring maintainability
• Multiple teams working on related domains
• Domain experts available for collaboration