--- name: domain-driven-design description: 'Model software around the business domain using bounded contexts, aggregates, and ubiquitous language. Use when the user mentions "domain modeling", "bounded context", "aggregate root", "ubiquitous language", "anti-corruption layer", "context mapping", "domain events", "strategic design", "the code doesnt match the business", or "how do we split this big system". Also trigger when breaking a monolith into services, defining service boundaries, or aligning code structure with business processes. Covers entities vs value objects, domain events, and context mapping strategies. For architecture layers, see clean-architecture. For complexity, see software-design-philosophy.' license: MIT metadata: author: wondelai version: "1.4.0" ---

# 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 specific diagnostic rows failing.

## Framework

### 1. Ubiquitous Language

**Core concept:** A shared, rigorous language between developers and domain experts, used consistently in conversation, documentation, and code. When the language changes, the code changes -- and awkward naming in code feeds back into refining the language.

**Why it works:** Ambiguity is the root cause of most modeling failures. When a developer says "order" and an expert means "purchase request," bugs are inevitable; a ubiquitous language forces every name in code to map to a concept the business recognizes and validates.

**Key insights:** - The language emerges from deep collaboration, not a glossary bolted on after the fact - If a concept is hard to name, the model is likely wrong -- naming difficulty is a design signal - 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 -- and that is fine

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Class/method naming | Name after domain concepts and verbs | `LoanApplication`, `policy.underwrite()` -- not `RequestHandler`, `process()` | | Module structure | Organize by domain concept | `shipping/`, `billing/` -- not `controllers/`, `services/` | | Code review | Reject technical-only names | Flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells |

See: [references/ubiquitous-language.md](references/ubiquitous-language.md) when running modeling sessions or maintaining a glossary -- covers how the language evolves and feeds back into code.

### 2. Bounded Contexts and Context Mapping

**Core concept:** 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.

**Why it works:** Large systems that try to maintain a single unified model inevitably collapse into inconsistency. Bounded contexts accept that different parts of the business need different models; context maps manage the integration between them.

**Key insights:** - A bounded context is not a microservice -- it is a linguistic and model boundary that may contain multiple services - Context boundaries often align with team boundaries (Conway's Law) - The nine context mapping patterns describe political and technical relationships between teams - Anti-Corruption Layer 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 explicitly governed - Start by mapping what exists (Big Ball of Mud), then define target boundaries

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Service integration | Anti-Corruption Layer | Translate external API responses into your domain objects at the boundary | | Legacy migration | Conformist / ACL | Wrap the legacy system behind an adapter that speaks your domain language | | API design | Open Host Service + Published Language | Expose a well-documented REST API with a canonical schema |

See: [references/bounded-contexts.md](references/bounded-contexts.md) for the nine mapping patterns and integration strategies.

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

**Core concept:** Entities have identity that persists across state changes. Value Objects are defined entirely by their attributes and are immutable. Aggregates are clusters of entities and value objects with a single root that enforces consistency boundaries.

**Why it works:** Without these distinctions, everything becomes a mutable, identity-bearing object -- tangled state, inconsistent updates, fragile concurrency. Aggregates draw the line: everything inside is guaranteed consistent; everything outside is eventually consistent.

**Key insights:** - Entity test: "Am I the same thing even if all my attributes change?" (a person changes name and address -- still the same person) - Value Object test: "Am I defined only by my attributes?" (any $10 bill is interchangeable with another) - Most things should be Value Objects, not Entities -- prefer immutability - Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference - Immediate consistency only within an aggregate; design for eventual consistency between aggregates

**Code applications:**

| 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 |

See: [references/building-blocks.md](references/building-blocks.md) for aggregate design rules and consistency boundaries.

### 4. Domain Events

**Core concept:** A domain event captures something that happened in the domain that experts care about, named in past tense (`OrderPlaced`, `PaymentReceived`) -- a fact that has already occurred.

**Why it works:** Domain events decouple cause from effect. When `OrderPlaced` is published, shipping, billing, and notifications each react independently without the ordering context knowing about them -- less coupling, eventual consistency, a natural audit trail.

**Key insights:** - Events are immutable facts -- once published, they cannot be changed or retracted - Domain events are internal to a bounded context; integration events cross boundaries - Events enable temporal decoupling: the producer does not wait for the consumer - 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

**Code applications:**

| 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 context | | Eventual consistency | Async event handlers | Inventory handler updates stock asynchronously after `OrderPlaced` |

See: [references/domain-events.md](references/domain-events.md) for event naming, event sourcing, and integration events.

### 5. Repositories and Factories

**Core concept:** Repositories provide the illusion of an in-memory collection of domain objects, hiding persistence. Factories encapsulate complex creation logic so aggregates are always born in a valid state.

**Why it works:** When persistence and assembly details leak into domain code, every storage change ripples through business rules and aggregates can be constructed in half-valid states. Repositories confine SQL/ORM concerns to infrastructure so the domain stays testable in memory; factories make the only path to an aggregate one that enforces its invariants, so an invalid instance is unrepresentable.

**Key insights:** - The Repository interface belongs in the domain layer; its implementation belongs in infrastructure - Repository methods speak the ubiquitous language: `findPendingOrders()`, not `getByStatusCode(3)` - Collection-oriented repositories mimic `add`/`remove`; persistence-oriented ones use `save` - Factories are warranted for complex rules or multi-part assembly; a two-field Value Object just needs a constructor - The Specification pattern encapsulates query criteria as domain objects: `OverdueInvoiceSpecification`

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Data access abstraction | Repository interface | `OrderRepository.findByCustomer(customerId)` 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)` |

See: [references/repositories-factories.md](references/repositories-factories.md) for Repository, Factory, and Specification patterns.

### 6. Strategic Design and Distillation

**Core concept:** 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).

**Why it works:** Applying the same rigor everywhere spreads your best talent thin and over-engineers commodity functionality. Identifying the Core Domain concentrates the best developers and deepest modeling where they matter most.

**Key insights:** - Core Domain: invest your best people and deepest modeling; Supporting: build, but don't over-engineer; Generic (auth, email, payments): buy or use open-source - Distillation extracts and highlights the Core Domain from surrounding complexity - A Domain Vision Statement is a one-page description of the Core Domain's value proposition - Revisit what is "core" as the business evolves -- today's differentiator may become tomorrow's commodity

**Code applications:**

| 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 the email service | | Code organization | Separate core from generic | `domain/pricing/` (deep model) vs. `infrastructure/email/` (thin a

--- name: domain-driven-design description: 'Model software around the business domain using bounded contexts, aggregates, and ubiquitous language. Use when the user mentions "domain modeling", "bounded context", "aggregate root", "ubiquitous language", "anti-corruption layer", "context mapping", "domain events", "strategic design", "the code doesnt match the business", or "how do we split this big system". Also trigger when breaking a monolith into services, defining service boundaries, or aligning code structure with business processes. Covers entities vs value objects, domain events, and context mapping strategies. For architecture layers, see clean-architecture. For complexity, see software-design-philosophy.' license: MIT metadata: author: wondelai version: "1.4.0" ---

# 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 specific diagnostic rows failing.

## Framework

### 1. Ubiquitous Language

**Core concept:** A shared, rigorous language between developers and domain experts, used consistently in conversation, documentation, and code. When the language changes, the code changes -- and awkward naming in code feeds back into refining the language.

**Why it works:** Ambiguity is the root cause of most modeling failures. When a developer says "order" and an expert means "purchase request," bugs are inevitable; a ubiquitous language forces every name in code to map to a concept the business recognizes and validates.

**Key insights:** - The language emerges from deep collaboration, not a glossary bolted on after the fact - If a concept is hard to name, the model is likely wrong -- naming difficulty is a design signal - 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 -- and that is fine

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Class/method naming | Name after domain concepts and verbs | `LoanApplication`, `policy.underwrite()` -- not `RequestHandler`, `process()` | | Module structure | Organize by domain concept | `shipping/`, `billing/` -- not `controllers/`, `services/` | | Code review | Reject technical-only names | Flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells |

See: [references/ubiquitous-language.md](references/ubiquitous-language.md) when running modeling sessions or maintaining a glossary -- covers how the language evolves and feeds back into code.

### 2. Bounded Contexts and Context Mapping

**Core concept:** 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.

**Why it works:** Large systems that try to maintain a single unified model inevitably collapse into inconsistency. Bounded contexts accept that different parts of the business need different models; context maps manage the integration between them.

**Key insights:** - A bounded context is not a microservice -- it is a linguistic and model boundary that may contain multiple services - Context boundaries often align with team boundaries (Conway's Law) - The nine context mapping patterns describe political and technical relationships between teams - Anti-Corruption Layer 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 explicitly governed - Start by mapping what exists (Big Ball of Mud), then define target boundaries

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Service integration | Anti-Corruption Layer | Translate external API responses into your domain objects at the boundary | | Legacy migration | Conformist / ACL | Wrap the legacy system behind an adapter that speaks your domain language | | API design | Open Host Service + Published Language | Expose a well-documented REST API with a canonical schema |

See: [references/bounded-contexts.md](references/bounded-contexts.md) for the nine mapping patterns and integration strategies.

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

**Core concept:** Entities have identity that persists across state changes. Value Objects are defined entirely by their attributes and are immutable. Aggregates are clusters of entities and value objects with a single root that enforces consistency boundaries.

**Why it works:** Without these distinctions, everything becomes a mutable, identity-bearing object -- tangled state, inconsistent updates, fragile concurrency. Aggregates draw the line: everything inside is guaranteed consistent; everything outside is eventually consistent.

**Key insights:** - Entity test: "Am I the same thing even if all my attributes change?" (a person changes name and address -- still the same person) - Value Object test: "Am I defined only by my attributes?" (any $10 bill is interchangeable with another) - Most things should be Value Objects, not Entities -- prefer immutability - Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference - Immediate consistency only within an aggregate; design for eventual consistency between aggregates

**Code applications:**

| 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 |

See: [references/building-blocks.md](references/building-blocks.md) for aggregate design rules and consistency boundaries.

### 4. Domain Events

**Core concept:** A domain event captures something that happened in the domain that experts care about, named in past tense (`OrderPlaced`, `PaymentReceived`) -- a fact that has already occurred.

**Why it works:** Domain events decouple cause from effect. When `OrderPlaced` is published, shipping, billing, and notifications each react independently without the ordering context knowing about them -- less coupling, eventual consistency, a natural audit trail.

**Key insights:** - Events are immutable facts -- once published, they cannot be changed or retracted - Domain events are internal to a bounded context; integration events cross boundaries - Events enable temporal decoupling: the producer does not wait for the consumer - 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

**Code applications:**

| 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 context | | Eventual consistency | Async event handlers | Inventory handler updates stock asynchronously after `OrderPlaced` |

See: [references/domain-events.md](references/domain-events.md) for event naming, event sourcing, and integration events.

### 5. Repositories and Factories

**Core concept:** Repositories provide the illusion of an in-memory collection of domain objects, hiding persistence. Factories encapsulate complex creation logic so aggregates are always born in a valid state.

**Why it works:** When persistence and assembly details leak into domain code, every storage change ripples through business rules and aggregates can be constructed in half-valid states. Repositories confine SQL/ORM concerns to infrastructure so the domain stays testable in memory; factories make the only path to an aggregate one that enforces its invariants, so an invalid instance is unrepresentable.

**Key insights:** - The Repository interface belongs in the domain layer; its implementation belongs in infrastructure - Repository methods speak the ubiquitous language: `findPendingOrders()`, not `getByStatusCode(3)` - Collection-oriented repositories mimic `add`/`remove`; persistence-oriented ones use `save` - Factories are warranted for complex rules or multi-part assembly; a two-field Value Object just needs a constructor - The Specification pattern encapsulates query criteria as domain objects: `OverdueInvoiceSpecification`

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Data access abstraction | Repository interface | `OrderRepository.findByCustomer(customerId)` 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)` |

See: [references/repositories-factories.md](references/repositories-factories.md) for Repository, Factory, and Specification patterns.

### 6. Strategic Design and Distillation

**Core concept:** 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).

**Why it works:** Applying the same rigor everywhere spreads your best talent thin and over-engineers commodity functionality. Identifying the Core Domain concentrates the best developers and deepest modeling where they matter most.

**Key insights:** - Core Domain: invest your best people and deepest modeling; Supporting: build, but don't over-engineer; Generic (auth, email, payments): buy or use open-source - Distillation extracts and highlights the Core Domain from surrounding complexity - A Domain Vision Statement is a one-page description of the Core Domain's value proposition - Revisit what is "core" as the business evolves -- today's differentiator may become tomorrow's commodity

**Code applications:**

| 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 the email service | | Code organization | Separate core from generic | `domain/pricing/` (deep model) vs. `infrastructure/email/` (thin a

--- name: domain-driven-design description: 'Model software around the business domain using bounded contexts, aggregates, and ubiquitous language. Use when the user mentions "domain modeling", "bounded context", "aggregate root", "ubiquitous language", "anti-corruption layer", "context mapping", "domain events", "strategic design", "the code doesnt match the business", or "how do we split this big system". Also trigger when breaking a monolith into services, defining service boundaries, or aligning code structure with business processes. Covers entities vs value objects, domain events, and context mapping strategies. For architecture layers, see clean-architecture. For complexity, see software-design-philosophy.' license: MIT metadata: author: wondelai version: "1.4.0" ---

# 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 specific diagnostic rows failing.

## Framework

### 1. Ubiquitous Language

**Core concept:** A shared, rigorous language between developers and domain experts, used consistently in conversation, documentation, and code. When the language changes, the code changes -- and awkward naming in code feeds back into refining the language.

**Why it works:** Ambiguity is the root cause of most modeling failures. When a developer says "order" and an expert means "purchase request," bugs are inevitable; a ubiquitous language forces every name in code to map to a concept the business recognizes and validates.

**Key insights:** - The language emerges from deep collaboration, not a glossary bolted on after the fact - If a concept is hard to name, the model is likely wrong -- naming difficulty is a design signal - 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 -- and that is fine

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Class/method naming | Name after domain concepts and verbs | `LoanApplication`, `policy.underwrite()` -- not `RequestHandler`, `process()` | | Module structure | Organize by domain concept | `shipping/`, `billing/` -- not `controllers/`, `services/` | | Code review | Reject technical-only names | Flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells |

See: [references/ubiquitous-language.md](references/ubiquitous-language.md) when running modeling sessions or maintaining a glossary -- covers how the language evolves and feeds back into code.

### 2. Bounded Contexts and Context Mapping

**Core concept:** 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.

**Why it works:** Large systems that try to maintain a single unified model inevitably collapse into inconsistency. Bounded contexts accept that different parts of the business need different models; context maps manage the integration between them.

**Key insights:** - A bounded context is not a microservice -- it is a linguistic and model boundary that may contain multiple services - Context boundaries often align with team boundaries (Conway's Law) - The nine context mapping patterns describe political and technical relationships between teams - Anti-Corruption Layer 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 explicitly governed - Start by mapping what exists (Big Ball of Mud), then define target boundaries

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Service integration | Anti-Corruption Layer | Translate external API responses into your domain objects at the boundary | | Legacy migration | Conformist / ACL | Wrap the legacy system behind an adapter that speaks your domain language | | API design | Open Host Service + Published Language | Expose a well-documented REST API with a canonical schema |

See: [references/bounded-contexts.md](references/bounded-contexts.md) for the nine mapping patterns and integration strategies.

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

**Core concept:** Entities have identity that persists across state changes. Value Objects are defined entirely by their attributes and are immutable. Aggregates are clusters of entities and value objects with a single root that enforces consistency boundaries.

**Why it works:** Without these distinctions, everything becomes a mutable, identity-bearing object -- tangled state, inconsistent updates, fragile concurrency. Aggregates draw the line: everything inside is guaranteed consistent; everything outside is eventually consistent.

**Key insights:** - Entity test: "Am I the same thing even if all my attributes change?" (a person changes name and address -- still the same person) - Value Object test: "Am I defined only by my attributes?" (any $10 bill is interchangeable with another) - Most things should be Value Objects, not Entities -- prefer immutability - Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference - Immediate consistency only within an aggregate; design for eventual consistency between aggregates

**Code applications:**

| 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 |

See: [references/building-blocks.md](references/building-blocks.md) for aggregate design rules and consistency boundaries.

### 4. Domain Events

**Core concept:** A domain event captures something that happened in the domain that experts care about, named in past tense (`OrderPlaced`, `PaymentReceived`) -- a fact that has already occurred.

**Why it works:** Domain events decouple cause from effect. When `OrderPlaced` is published, shipping, billing, and notifications each react independently without the ordering context knowing about them -- less coupling, eventual consistency, a natural audit trail.

**Key insights:** - Events are immutable facts -- once published, they cannot be changed or retracted - Domain events are internal to a bounded context; integration events cross boundaries - Events enable temporal decoupling: the producer does not wait for the consumer - 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

**Code applications:**

| 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 context | | Eventual consistency | Async event handlers | Inventory handler updates stock asynchronously after `OrderPlaced` |

See: [references/domain-events.md](references/domain-events.md) for event naming, event sourcing, and integration events.

### 5. Repositories and Factories

**Core concept:** Repositories provide the illusion of an in-memory collection of domain objects, hiding persistence. Factories encapsulate complex creation logic so aggregates are always born in a valid state.

**Why it works:** When persistence and assembly details leak into domain code, every storage change ripples through business rules and aggregates can be constructed in half-valid states. Repositories confine SQL/ORM concerns to infrastructure so the domain stays testable in memory; factories make the only path to an aggregate one that enforces its invariants, so an invalid instance is unrepresentable.

**Key insights:** - The Repository interface belongs in the domain layer; its implementation belongs in infrastructure - Repository methods speak the ubiquitous language: `findPendingOrders()`, not `getByStatusCode(3)` - Collection-oriented repositories mimic `add`/`remove`; persistence-oriented ones use `save` - Factories are warranted for complex rules or multi-part assembly; a two-field Value Object just needs a constructor - The Specification pattern encapsulates query criteria as domain objects: `OverdueInvoiceSpecification`

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Data access abstraction | Repository interface | `OrderRepository.findByCustomer(customerId)` 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)` |

See: [references/repositories-factories.md](references/repositories-factories.md) for Repository, Factory, and Specification patterns.

### 6. Strategic Design and Distillation

**Core concept:** 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).

**Why it works:** Applying the same rigor everywhere spreads your best talent thin and over-engineers commodity functionality. Identifying the Core Domain concentrates the best developers and deepest modeling where they matter most.

**Key insights:** - Core Domain: invest your best people and deepest modeling; Supporting: build, but don't over-engineer; Generic (auth, email, payments): buy or use open-source - Distillation extracts and highlights the Core Domain from surrounding complexity - A Domain Vision Statement is a one-page description of the Core Domain's value proposition - Revisit what is "core" as the business evolves -- today's differentiator may become tomorrow's commodity

**Code applications:**

| 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 the email service | | Code organization | Separate core from generic | `domain/pricing/` (deep model) vs. `infrastructure/email/` (thin a

--- name: domain-driven-design description: 'Model software around the business domain using bounded contexts, aggregates, and ubiquitous language. Use when the user mentions "domain modeling", "bounded context", "aggregate root", "ubiquitous language", "anti-corruption layer", "context mapping", "domain events", "strategic design", "the code doesnt match the business", or "how do we split this big system". Also trigger when breaking a monolith into services, defining service boundaries, or aligning code structure with business processes. Covers entities vs value objects, domain events, and context mapping strategies. For architecture layers, see clean-architecture. For complexity, see software-design-philosophy.' license: MIT metadata: author: wondelai version: "1.4.0" ---

# 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 specific diagnostic rows failing.

## Framework

### 1. Ubiquitous Language

**Core concept:** A shared, rigorous language between developers and domain experts, used consistently in conversation, documentation, and code. When the language changes, the code changes -- and awkward naming in code feeds back into refining the language.

**Why it works:** Ambiguity is the root cause of most modeling failures. When a developer says "order" and an expert means "purchase request," bugs are inevitable; a ubiquitous language forces every name in code to map to a concept the business recognizes and validates.

**Key insights:** - The language emerges from deep collaboration, not a glossary bolted on after the fact - If a concept is hard to name, the model is likely wrong -- naming difficulty is a design signal - 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 -- and that is fine

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Class/method naming | Name after domain concepts and verbs | `LoanApplication`, `policy.underwrite()` -- not `RequestHandler`, `process()` | | Module structure | Organize by domain concept | `shipping/`, `billing/` -- not `controllers/`, `services/` | | Code review | Reject technical-only names | Flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells |

See: [references/ubiquitous-language.md](references/ubiquitous-language.md) when running modeling sessions or maintaining a glossary -- covers how the language evolves and feeds back into code.

### 2. Bounded Contexts and Context Mapping

**Core concept:** 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.

**Why it works:** Large systems that try to maintain a single unified model inevitably collapse into inconsistency. Bounded contexts accept that different parts of the business need different models; context maps manage the integration between them.

**Key insights:** - A bounded context is not a microservice -- it is a linguistic and model boundary that may contain multiple services - Context boundaries often align with team boundaries (Conway's Law) - The nine context mapping patterns describe political and technical relationships between teams - Anti-Corruption Layer 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 explicitly governed - Start by mapping what exists (Big Ball of Mud), then define target boundaries

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Service integration | Anti-Corruption Layer | Translate external API responses into your domain objects at the boundary | | Legacy migration | Conformist / ACL | Wrap the legacy system behind an adapter that speaks your domain language | | API design | Open Host Service + Published Language | Expose a well-documented REST API with a canonical schema |

See: [references/bounded-contexts.md](references/bounded-contexts.md) for the nine mapping patterns and integration strategies.

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

**Core concept:** Entities have identity that persists across state changes. Value Objects are defined entirely by their attributes and are immutable. Aggregates are clusters of entities and value objects with a single root that enforces consistency boundaries.

**Why it works:** Without these distinctions, everything becomes a mutable, identity-bearing object -- tangled state, inconsistent updates, fragile concurrency. Aggregates draw the line: everything inside is guaranteed consistent; everything outside is eventually consistent.

**Key insights:** - Entity test: "Am I the same thing even if all my attributes change?" (a person changes name and address -- still the same person) - Value Object test: "Am I defined only by my attributes?" (any $10 bill is interchangeable with another) - Most things should be Value Objects, not Entities -- prefer immutability - Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference - Immediate consistency only within an aggregate; design for eventual consistency between aggregates

**Code applications:**

| 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 |

See: [references/building-blocks.md](references/building-blocks.md) for aggregate design rules and consistency boundaries.

### 4. Domain Events

**Core concept:** A domain event captures something that happened in the domain that experts care about, named in past tense (`OrderPlaced`, `PaymentReceived`) -- a fact that has already occurred.

**Why it works:** Domain events decouple cause from effect. When `OrderPlaced` is published, shipping, billing, and notifications each react independently without the ordering context knowing about them -- less coupling, eventual consistency, a natural audit trail.

**Key insights:** - Events are immutable facts -- once published, they cannot be changed or retracted - Domain events are internal to a bounded context; integration events cross boundaries - Events enable temporal decoupling: the producer does not wait for the consumer - 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

**Code applications:**

| 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 context | | Eventual consistency | Async event handlers | Inventory handler updates stock asynchronously after `OrderPlaced` |

See: [references/domain-events.md](references/domain-events.md) for event naming, event sourcing, and integration events.

### 5. Repositories and Factories

**Core concept:** Repositories provide the illusion of an in-memory collection of domain objects, hiding persistence. Factories encapsulate complex creation logic so aggregates are always born in a valid state.

**Why it works:** When persistence and assembly details leak into domain code, every storage change ripples through business rules and aggregates can be constructed in half-valid states. Repositories confine SQL/ORM concerns to infrastructure so the domain stays testable in memory; factories make the only path to an aggregate one that enforces its invariants, so an invalid instance is unrepresentable.

**Key insights:** - The Repository interface belongs in the domain layer; its implementation belongs in infrastructure - Repository methods speak the ubiquitous language: `findPendingOrders()`, not `getByStatusCode(3)` - Collection-oriented repositories mimic `add`/`remove`; persistence-oriented ones use `save` - Factories are warranted for complex rules or multi-part assembly; a two-field Value Object just needs a constructor - The Specification pattern encapsulates query criteria as domain objects: `OverdueInvoiceSpecification`

**Code applications:**

| Context | Pattern | Example | |---------|---------|---------| | Data access abstraction | Repository interface | `OrderRepository.findByCustomer(customerId)` 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)` |

See: [references/repositories-factories.md](references/repositories-factories.md) for Repository, Factory, and Specification patterns.

### 6. Strategic Design and Distillation

**Core concept:** 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).

**Why it works:** Applying the same rigor everywhere spreads your best talent thin and over-engineers commodity functionality. Identifying the Core Domain concentrates the best developers and deepest modeling where they matter most.

**Key insights:** - Core Domain: invest your best people and deepest modeling; Supporting: build, but don't over-engineer; Generic (auth, email, payments): buy or use open-source - Distillation extracts and highlights the Core Domain from surrounding complexity - A Domain Vision Statement is a one-page description of the Core Domain's value proposition - Revisit what is "core" as the business evolves -- today's differentiator may become tomorrow's commodity

**Code applications:**

| 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 the email service | | Code organization | Separate core from generic | `domain/pricing/` (deep model) vs. `infrastructure/email/` (thin a