domain-driven-design

What this skill does

# Domain-Driven Design Framework

Framework for tackling software complexity by modeling code around the business domain. Based on a fundamental truth: 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, requirements are captured precisely, and the system evolves gracefully as the business changes.

## Scoring

**Goal: 10/10.** When reviewing or creating domain models, rate them 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.

## Framework

### 1. Ubiquitous Language

**Core concept:** A shared, rigorous language between developers and domain experts that is used consistently in conversation, documentation, and code. When the language changes, the code changes. When the code reveals awkward naming, the language is refined.

**Why it works:** Ambiguity is the root cause of most modeling failures. When a developer says "order" and a domain expert means "purchase request," bugs are inevitable. A ubiquitous language forces alignment so that every class, method, and variable name maps to a concept the business recognizes and validates.

**Key insights:**
- The language is not a glossary bolted on after the fact -- it emerges from deep collaboration
- If a concept is hard to name, the model is likely wrong; naming difficulty is a design signal
- Code that uses technical jargon instead of domain terms (e.g., `DataProcessor` vs. `ClaimAdjudicator`) hides domain logic
- Language must be enforced in code: class names, method names, event names, module names
- Different bounded contexts may use the same word with different meanings -- and that is fine

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| Class naming | Name classes after domain concepts | `LoanApplication`, not `RequestHandler` |
| Method naming | Use verbs the business uses | `policy.underwrite()`, not `policy.process()` |
| Event naming | Past-tense domain actions | `ClaimSubmitted`, not `DataSaved` |
| 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)

### 2. Bounded Contexts and Context Mapping

**Core concept:** A bounded context is an explicit boundary within which a particular domain model is defined and applicable. The same word (e.g., "Customer") can mean different things in different contexts. Context maps define the relationships and translation strategies between bounded contexts.

**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 have different models and make the boundaries explicit. Context maps then manage integration so that each context preserves its internal consistency.

**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 is dangerous: it couples two teams and should be 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 |
| Team collaboration | Shared Kernel | Two teams co-own a small `Money` value object library |
| Legacy migration | Conformist / ACL | Wrap 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 |
| Module boundaries | Separate packages per context | `myapp.shipping` and `myapp.billing` packages with explicit translation |

See: [references/bounded-contexts.md](references/bounded-contexts.md)

### 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 entity that enforces consistency boundaries.

**Why it works:** Without these distinctions, systems treat everything as a mutable, identity-bearing object with database-level relationships, leading to tangled state, inconsistent updates, and fragile concurrency. Aggregates draw a consistency boundary: everything inside is guaranteed consistent; everything outside is eventually consistent.

**Key insights:**
- Entity: "Am I the same thing even if all my attributes change?" (a person changes name, address, job -- still the same person)
- Value Object: "Am I defined only by my attributes?" (a $10 bill is interchangeable with any other $10 bill)
- Most things in a domain model should be Value Objects, not Entities -- prefer immutability
- Aggregate Root is the single entry point: external objects may only hold references to the root
- Keep aggregates small -- one root entity plus a minimal cluster of closely related objects
- Reference other aggregates by ID, not by direct object reference
- Design for eventual consistency between aggregates; immediate consistency only within an aggregate

**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 |
| Cross-aggregate reference | Reference by ID | `Order` stores `customerId`, not a `Customer` object |
| Concurrency control | Optimistic locking on root | Version field on `Order`; conflict if two edits race |

See: [references/building-blocks.md](references/building-blocks.md)

### 4. Domain Events

**Core concept:** A domain event captures something that happened in the domain that domain experts care about. Events are named in past tense (`OrderPlaced`, `PaymentReceived`) and represent facts that have already occurred.

**Why it works:** Domain events decouple the cause from the effect. When `OrderPlaced` is published, the shipping context, billing context, and notification context can each react independently without the ordering context knowing about any of them. This reduces coupling, enables eventual consistency, and creates a natural audit trail.

**Key insights:**
- Name events in past tense: something that happened, not something that should happen
- Events are immutable facts -- once published, they cannot be changed or retracted
- Domain events differ from integration events: 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 history of events as the source of truth, deriving current state by replaying them
- Not every state change needs an event -- only publish events that the