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 adapt