nw-domain-driven-design

Domain-Driven Design

When to Apply DDD

DDD addresses domain complexity (business rules, language, boundaries), not technical complexity (scaling, performance). Apply selectively.

Domain Type (Cynefin)	DDD Investment	Approach
Clear/Simple	None -- use CRUD	Standard patterns, no modeling overhead
Complicated	Tactical only	Expert analysis, pragmatic patterns suffice
Complex	Full strategic + tactical	Iterative modeling, bounded contexts, continuous refinement
Chaotic	Stabilize first	Emergency patches, then apply DDD incrementally

Signs You Need DDD

• Domain experts and developers frequently misunderstand each other
• Business rules are complex, interconnected, frequently changing
• Multiple teams work on the same codebase with conflicting models
• System has grown into a "big ball of mud"
• Business logic scattered across services, controllers, database procedures

Signs DDD Is Overkill

• Simple CRUD without complex business rules
• Technical complexity outweighs domain complexity
• Small team, small codebase, single bounded context
• For simple microservices, anemic domain model is acceptable (not an anti-pattern)

Strategic DDD

Subdomain Classification

Criterion	Core	Supporting	Generic
Competitive advantage	Yes	No	No
Unique to organization	Yes	Partially	No
Build or buy	Build	Build (simplified)	Buy/integrate
DDD investment	Full strategic + tactical	Pragmatic tactical	Minimal/none
Developer allocation	Senior/best talent	Mid-level	Junior/integration

Bounded Contexts

A bounded context is the boundary within which a particular domain model is defined and applicable. Different from subdomains: a bounded context is a software boundary; a subdomain is a problem-space concept. They should align but are not the same.

Discovery techniques:

• Language divergence: same term means different things to different groups -- you have crossed a boundary
• Organizational structure: different departments often correspond to different contexts
• Consistency requirements: where true invariants must be maintained transactionally
• EventStorming: Big Picture workshops surface boundaries through hotspots and swimlane divergences
• Domain Storytelling: actors, work objects, activity arrows reveal natural boundaries

Common mistakes:

1. Confusing contexts with subdomains (software boundary vs. problem-space concept)
2. Assuming one microservice = one bounded context (Evans calls this an "oversimplification")
3. Making contexts too large (big ball of mud with conflicting models)
4. Making contexts too small (excessive cross-context communication overhead)

Context Mapping Patterns

Nine patterns organized by team relationship type.

Pattern	Relationship	When to Use
Partnership	Mutually dependent	Teams must deliver together; true reciprocal dependency
Shared Kernel	Shared model subset	Close coordination around common concepts. Keep small
Customer-Supplier	Upstream-downstream	Asymmetric dependencies requiring structured negotiation
Conformist	Downstream adopts upstream	Integration simplicity outweighs design freedom
Anti-Corruption Layer	Isolating translation	Protecting domain from poor upstream models; legacy integration
Open Host Service	Standardized API	Supporting multiple downstream teams
Published Language	Shared schema/format	Standardized formats for inter-context translation (iCalendar, vCard)
Separate Ways	No connection	Contexts have no meaningful interdependencies
Big Ball of Mud	Recognition only	Demarcate and quarantine legacy/poorly-structured systems

Relationship categories: Mutually Dependent (Partnership) | Upstream/Downstream (Customer-Supplier, Conformist, ACL) | Free (Separate Ways)

Evolution: context maps evolve during refactoring. A Conformist relationship can be refactored to Customer-Supplier with an ACL. Draw context maps before writing code.

Ubiquitous Language

A common, rigorous vocabulary shared between developers and domain experts, scoped per bounded context.

Rules:

1. Never use generic technical terms when a domain term exists
2. If developers and domain experts use different words for the same concept, resolve the conflict
3. When the model becomes hard to express in code, the language needs refinement
4. The same word may mean different things in different contexts -- this is expected

Code must reflect the language: class names, method names, variable names use domain terms. When the language changes, the code changes.

Tactical DDD

Aggregates -- Four Design Rules (Vernon)

1. Model true invariants in consistency boundaries: only include elements that must be consistent within the same transaction
2. Design small aggregates: ~70% of aggregates contain only a root entity with value-typed properties. Large aggregates create concurrency contention and scalability failures
3. Reference other aggregates by identity: use ProductId not Product. Prevents accidental cross-aggregate transactions
4. Use eventual consistency outside the boundary: domain events are the vehicle. One transaction = one aggregate

Common mistakes: including objects for compositional convenience | "god aggregates" | direct object references | requiring immediate consistency where eventual suffices

Entities vs. Value Objects

Criterion	Entity	Value Object
Identity matters	Yes (tracked over time)	No (interchangeable if same values)
Mutability	Mutable (state changes)	Immutable (replace, do not modify)
Equality	By identity (ID)	By attribute values (structural)
Examples	Customer, Order, Account	Money, Address, DateRange, Email

Self-validating value objects: the only way for a value object to exist is to be valid. Validate in constructor; reject invalid input. Eliminates scattered validation logic.

Context sensitivity: whether something is Entity or Value Object depends on the bounded context. Address is a VO in e-commerce but an Entity in utility billing.

Domain Events

Represent something that happened. Named in past tense: OrderPlaced, UserRegistered, PaymentProcessed.

• Domain events (in-process): within a bounded context, dispatched via mediator. Deferred dispatch preferred (collect during command, dispatch before/after commit)
• Integration events (distributed): cross bounded contexts via message brokers. Always asynchronous. Published only after successful persistence

Repositories

One repository per aggregate (not per entity). Interface in domain layer, implementation in infrastructure. Never expose persistence details to the domain.

• Collection-oriented: add/remove/find operations, repository tracks changes (Unit of Work)
• Persistence-oriented: explicit save/load, common with document DBs or event-sourced systems

Domain Services

Stateless operations spanning multiple aggregates. Named using ubiquitous language. Operate on domain types only.

Danger: overuse strips entities of behavior, creating anemic domain models.

Aspect	Domain Service	Application Service
Contains	Domain logic	Orchestration logic
Dependencies	Domain types only	Domain objects + infrastructure ports
Layer	Domain model	Application
Example	TransferFunds, CalculateDiscount	PlaceOrderHandler, RegisterUserUseCase

Integration Patterns

DDD + Hexagonal Architecture

Natural fit: domain in center (no infrastructure dependencies), ports as use cases, adapters for infrastructure. ACL at adapter boundaries. Each bounded context = a separate hexagon with own ports and adapters.

DDD + CQRS

Command side uses full tactical DDD toolkit. Query side bypasses domain model entirely -- read models are denormalized views. CQRS is NOT event sourcing (they are independent patterns).

CQRS Adds Value	CQRS Adds Complexity Without Value
Complex domain with rich business rules	Simple CRUD applications
Different read/write patterns	Minimal business logic
Scale reads/writes independently	Small team without distributed experience
Event-driven or event-sourced systems	Strong immediate consistency required everywhere

DDD + Event Sourcing

Store domain events instead of current state. State = fold(initialState, events). Apply selectively to core domains only -- "not a top-level architecture" (Greg Young). Use for: audit trails, temporal queries, complex business domains.

DDD + Microservices

Bounded contexts provide decomposition tool, but the mapping is not one-to-one. A bounded context may contain multiple services; a microservice may handle a focused subdomain within a larger context.

Decomposition criteria: subdomain boundaries (primary) | single responsibility | common closure | team autonomy | loose coupling

Cross-context operations: Saga pattern with compensating transactions. Choreography (decentralized, simple workflows) vs. Orchestration (centralized, complex workflows).

Anti-Patterns

Anti-Pattern	Signal	Fix
Anemic Domain Model	Entities = data only, logic in services	Move business rules into entities/aggregates
God Aggregate	Too many entities/VOs, concurrency contention	Split by true invariant boundaries
Domain Logic in App Layer	Business "if" statements in services	Push logic down to domain objects
Primitive Obsession	Raw strings for domain concepts	Create value objects for every domain concept
Missing Boundaries	Single unified model for entire system	Identify bounded contexts via language divergence
Events as RPCs	Events depend on handler response	Events represent facts, fire-and-forget
Database-Driven Design	Entities mirror tables	Model domain first, map to persistence second

EventStorming Quick Reference

Three levels: Big Picture (25-30 people, entire business line) | Process Modeling (structured workflow grammar) | Design Level (DDD vocabulary, 1:1 to code).

Key artifacts: Domain Events (orange, past tense) | Commands (blue, imperative) | Aggregates (yellow, consistency boundaries) | Policies (lilac, automation rules) | Read Models (green, decision info) | External Systems (pink) | Hotspots (red, problems/questions).

Start with chaotic event exploration, enforce timeline, add commands/actors, identify aggregates/policies, mark hotspots. Iterate between divergent and convergent phases.