domain-driven-design

---
name: domain-driven-design
description: Use when modeling software around the business domain: bounded contexts, aggregates, ubiquitous language, domain events, or splitting a monolith into services.
category: Design
version: 1.0.0
tools: []
---

# Domain-Driven Design Framework

Framework for tackling software complexity by modeling code around the business domain. The greatest risk in software is not technical failure — it is building a model that does not reflect how the business actually works.

## Core Principle

**The model is the code; the code is the model.** Software should embody a deep, shared understanding of the business domain. When domain experts and developers speak the same language and that language is directly expressed in the codebase, complexity becomes manageable and the system evolves gracefully as the business changes.

## Scoring

**Goal: 10/10.** Score a domain model by awarding 1 point per satisfied row of the Quick Diagnostic (7 rows) plus up to 3 points for depth: +1 if the Core Domain has a genuinely rich model (not just CRUD), +1 if invariants live inside aggregates rather than in services, +1 if the ubiquitous language is consistent across conversation, code, and tests. Bands: **9-10** = expert-readable names, explicit context boundaries with ACLs, small aggregates, behavior-rich entities, events for cross-aggregate flow, an identified Core Domain; **5-6** = some domain language but leaky boundaries or anemic objects; **≤3** = technical naming, one model for everything, logic scattered in services. Report the score and the failing rows.

## Framework

### 1. Ubiquitous Language

A shared, rigorous language between developers and domain experts, used consistently in conversation, documentation, and code — awkward naming in code feeds back into refining the language. Ambiguity ("order" vs. "purchase request") is the root cause of most modeling failures; if a concept is hard to name, the model is likely wrong. Technical jargon (`DataProcessor` vs. `ClaimAdjudicator`) hides domain logic from the experts who could correct it. Different bounded contexts may use the same word with different meanings — that's fine.

**Code applications:** name classes/methods after domain concepts and verbs (`LoanApplication`, `policy.underwrite()`, not `RequestHandler`/`process()`); organize modules by domain concept (`shipping/`, `billing/`, not `controllers/`, `services/`); flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells in review.

### 2. Bounded Contexts and Context Mapping

A bounded context is an explicit boundary within which a particular domain model applies. The same word ("Customer") can mean different things in different contexts; context maps define the relationships and translation strategies between them — large systems that try to maintain one unified model inevitably collapse into inconsistency. A bounded context is not a microservice — it's a linguistic/model boundary that may contain multiple services, often aligned with team boundaries (Conway's Law). Nine context-mapping patterns describe political and technical relationships between teams. **Anti-Corruption Layer (ACL)** is the most important defensive pattern — never let a foreign model leak into your core domain. **Shared Kernel** couples two teams; keep it small and governed. Start by mapping what exists (Big Ball of Mud), then define target boundaries.

**Code applications:** ACL translates external API responses into your domain objects at the boundary; Conformist/ACL wraps a legacy system behind an adapter speaking your domain language; Open Host Service + Published Language exposes a well-documented API with a canonical schema for integrations.

### 3. Entities, Value Objects, and Aggregates

Entities have identity that persists across state changes (test: "same thing even if all attributes change?" — a person who changes name/address is still the same person). Value Objects are defined entirely by their attributes and are immutable (test: "defined only by attributes?" — any $10 bill is interchangeable). Most things should be Value Objects, not Entities. Aggregates are clusters of entities/value objects with a single root enforcing consistency boundaries — everything inside is guaranteed consistent, everything outside is eventually consistent. Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference.

| Context | Pattern | Example |
|---------|---------|---------|
| Identity tracking | Entity with ID | `Order` identified by `orderId`, survives state changes |
| Immutable attributes | Value Object | `Address(street, city, zip)` — replace, never mutate |
| Consistency boundary | Aggregate Root | `Order` is root; `OrderLine` items exist only through it |
| Concurrency control | Optimistic locking on root | Version field on `Order`; conflict if two edits race |

### 4. Domain Events

A domain event captures something that happened in the domain that experts care about, named in past tense (`OrderPlaced`, `PaymentReceived`) — an immutable fact, never changed or retracted once published. Events decouple cause from effect: when `OrderPlaced` publishes, shipping, billing, and notifications react independently without the ordering context knowing about them. Domain events are internal to a bounded context; integration events cross boundaries. Event sourcing stores the full event history as the source of truth, deriving current state by replay. Not every state change deserves an event — only publish what the domain cares about.

| Context | Pattern | Example |
|---------|---------|---------|
| State transitions | Raise event on domain action | `order.place()` raises `OrderPlaced` |
| Cross-context integration | Publish integration event | `OrderPlaced` triggers `ShippingLabelRequested` in shipping |
| Eventual consistency | Async event handlers | Inventory handler updates stock after `OrderPlaced` |

### 5. Repositories and Factories

Repositories provide the illusion of an in-memory collection of domain objects, hiding persistence so the domain stays testable without a database — interface in the domain layer, implementation in infrastructure. Repository methods speak the ubiquitous language (`findPendingOrders()`, not `getByStatusCode(3)`); collection-oriented repositories mimic `add`/`remove`, persistence-oriented ones use `save`. Factories encapsulate complex creation logic so aggregates are always born in a valid state — warranted for complex rules or multi-part assembly, not a two-field Value Object. The Specification pattern encapsulates query criteria as domain objects (`OverdueInvoiceSpecification`).

| Context | Pattern | Example |
|---------|---------|---------|
| Data access abstraction | Repository interface | `OrderRepository.findByCustomer(id)` in domain; `PostgresOrderRepository` in infrastructure |
| Complex creation | Factory method | `Order.createFromQuote(quote)` validates and assembles from a `Quote` aggregate |
| Query encapsulation | Specification | `spec = OverdueBy(days=30); repo.findMatching(spec)` |

### 6. Strategic Design and Distillation

Not all parts of a system are equally important. Strategic design identifies the **Core Domain** — where competitive advantage lives — and distinguishes it from **Supporting Subdomains** (necessary, not differentiating) and **Generic Subdomains** (commodity: auth, email, payments — buy or use open-source). Concentrate your best developers and deepest modeling on the Core Domain; don't over-engineer supporting or generic parts. Distillation extracts and highlights the Core Domain from surrounding complexity; a Domain Vision Statement is a one-page description of its value proposition. Revisit what is "core" as the business evolves — today's differentiator may become tomorrow's commodity.

| Context | Pattern | Example |
|---------|---------|---------|
| Build vs. buy | Classify subdomain type | Build custom pricing engine (core); use Stripe for payments (generic) |
| Team allocation | Best developers on Core Domain | Seniors model underwriting rules; juniors integrate email |
| Code organization | Separate core from generic | `domain/pricing/` (deep model) vs. `infrastructure/email/` (thin adapter) |

## Common Mistakes

| Mistake | Why It Fails | Fix |
|---------|-------------|-----|
| Technical names instead of domain language | Experts can't validate the model | Rename to domain terms; if none exists, the concept may be wrong |
| One model to rule them all | A single `Customer` for billing/shipping/marketing becomes bloated | Bounded contexts: each gets its own `Customer` with only needed attributes |
| Giant aggregates | Concurrency conflicts, slow loads | Keep aggregates small; reference by ID; accept eventual consistency |
| Anemic domain model | Logic scatters across services and duplicates | Move behavior into entities and value objects |
| No Anti-Corruption Layer | Foreign models leak in, coupling you to external schemas | Wrap every external system behind a translation layer |
| Bounded context = microservice | Premature extraction, distributed complexity without benefit | A context is a model boundary, not a deployment unit |

## Quick Diagnostic

| Question | If No | Action |
|----------|-------|--------|
| Can a domain expert read your class names and understand them? | Technical jargon hides the model | Rename to ubiquitous language |
| Are bounded context boundaries explicitly defined? | Models bleed; same term means different things | Draw a context map; define boundaries and translations |
| Are aggregates small (one root + minimal cluster)? | Slow loads, concurrency issues | Split aggregates; reference by ID |
| Do domain objects contain behavior, not just data? | Anemic model; logic scattered in services | Move business rules into entities and value objects |
| Are domain events used for cross-aggregate communication? | Tight coupling, synchronous chains | Introduce events; react asynchronously |
| Is there an Anti-Corruption Layer at every external integration? | Foreign models pollute your domain | Add a translation layer at each boundary |
| Have you identified which subdomain is core? | Best talent spread thin | Classify subdomains; focus on the Core Domain |

Based on Eric Evans's *Domain-Driven Design: Tackling Complexity in the Heart of Software*.