Domain-Driven Design

Reference: Domain-Driven Design (Evans), Implementing DDD (Vernon), Learning DDD (Khononov)

When to Apply

• Modeling a complex business domain where the logic is the competitive differentiator
• Defining boundaries between subdomains or microservices
• Designing aggregates, entities, and value objects
• Establishing ubiquitous language between developers and domain experts
• Running Event Storming to discover domain events and bounded contexts
• Implementing CQRS or Event Sourcing for a specific bounded context
• Reviewing domain models for anemic models, oversized aggregates, or leaking contexts

MUST NOT apply full DDD tactical patterns to simple CRUD applications — the overhead is not justified.

Strategic Design

Ubiquitous Language

• MUST use a single, shared language within each bounded context — reflected in code, documentation, and conversation
• MUST NOT translate between "business terms" and "technical terms" — the code IS the language
• Different bounded contexts MAY use different terms for the same real-world concept (e.g., "Customer" in Sales vs "Account" in Billing)

Bounded Contexts

A bounded context is the boundary within which a domain model is consistent and a ubiquitous language applies.

• MUST define explicit boundaries — a model is valid only within its context
• SHOULD map one bounded context to one deployable unit (microservice, module)
• Microsoft guidance: "No smaller than an aggregate, no larger than a bounded context"

Context Mapping

Define relationships between bounded contexts using these patterns:

• MUST use an Anti-Corruption Layer when integrating with legacy systems or external services
• SHOULD default to Customer-Supplier for inter-team context relationships
• SHOULD document all context maps and keep them updated as relationships evolve

Subdomains

• MUST identify the Core Domain and invest DDD effort there
• SHOULD NOT apply full DDD tactical patterns to Generic Subdomains

Tactical Design

Entities

• Have unique identity that persists over time; equality is by ID, not attributes
• Are mutable but state changes MUST be modeled as business verbs: order.cancel() not order.setStatus("cancelled")
• SHOULD be kept lean — push behavior to Value Objects where possible

Value Objects

• Immutable, defined by their value (not identity), interchangeable when equal
• Contain behavior: Money.add(other), EmailAddress.validate()
• Thread-safe by nature (no shared mutable state)
• Design guidance: aim for many Value Objects and few Entities

Aggregates

An aggregate is a cluster of objects treated as a single unit for data changes, defining a consistency boundary.

Vaughn Vernon's aggregate design rules:

1. Design small aggregates — prefer single-entity aggregates; add entities only when invariants require it
2. Protect business invariants inside aggregate boundaries — the aggregate root enforces all rules
3. Reference other aggregates by identity only — never hold direct object references to other aggregates
4. Use eventual consistency across aggregate boundaries — do not span transactions across aggregates
5. Update one aggregate per transaction — if multiple aggregates must change, use domain events

• MUST have exactly one Aggregate Root with global identity as the single entry point
• MUST NOT modify multiple aggregates in a single transaction
• SHOULD keep aggregates as small as invariant protection allows

Repositories

• Provide a collection-like interface for aggregate persistence: save(), findById(), remove()
• One repository per aggregate root — MUST NOT create repositories for non-root entities
• MUST hide persistence details — the domain layer sees only the interface

Domain Events

• Named in past tense: OrderPlaced, PaymentReceived, InventoryReserved
• Represent meaningful business occurrences, not technical events
• Enable eventual consistency across aggregate boundaries
• SHOULD be immutable and carry all data needed by consumers

Domain Services

• Stateless operations that don't naturally belong to any entity or value object
• Typically coordinate multiple aggregates or perform calculations requiring data from several objects
• MUST NOT become a dumping ground — check if the behavior belongs on an entity first

Application Services

• Orchestrate use cases by coordinating domain objects, repositories, and infrastructure
• MUST NOT contain business logic — delegate to domain objects
• Handle transactions, security, logging, and other cross-cutting concerns

Event Storming

A collaborative workshop technique (Brandolini) for discovering domain events, commands, and bounded context boundaries.

Three Levels

Sticky Note Colors (Standard Convention)

CQRS and Event Sourcing

CQRS (Command Query Responsibility Segregation)

Separate read and write models. Apply selectively — Greg Young: "CQRS is a supporting pattern, not a top-level architecture."

• Write side: rich domain model with aggregates enforcing invariants
• Read side: optimized projections (denormalized views) for queries
• SHOULD apply CQRS only to bounded contexts with complex domain logic AND different read/write performance needs
• MUST NOT apply CQRS everywhere — it adds significant complexity

Event Sourcing

Store state changes as an immutable, append-only sequence of events. Current state is derived by replaying events.

• SHOULD use projections to build read-optimized views from the event stream
• SHOULD implement snapshots for aggregates with long event histories (performance optimization)
• Provides: complete audit trail, temporal queries, debugging capability, flexible projection creation
• MUST NOT use Event Sourcing for simple state management — the complexity cost is high

Anti-Patterns and Remedies

Checklist

Before finalizing a domain model, verify:

• Core Domain is identified and receives the highest modeling investment
• Each bounded context has its own ubiquitous language reflected in code
• Context relationships are mapped using explicit patterns (ACL, Customer-Supplier, etc.)
• Aggregates are small — single entity where possible
• Aggregate boundaries protect business invariants
• Other aggregates are referenced by identity only, never by direct object reference
• One aggregate is updated per transaction; cross-aggregate consistency uses domain events
• Entities model state changes as business verbs, not setters
• Value Objects are used for domain concepts without identity (Money, Email, DateRange)
• Domain events are named in past tense and carry necessary data
• Repositories exist only for aggregate roots
• Application services orchestrate but contain no business logic

Key References