domain-driven-design

Files (9)

• SKILL.md
• anti-patterns.md · references/
• application-architecture.md · references/
• cqrs.md · references/
• event-sourcing.md · references/
• python-examples.md · references/
• strategic-design.md · references/
• tactical-patterns.md · references/
• typescript-examples.md · references/

SKILL.md (first lines)

# Domain-Driven Design

Use this skill to model a business domain *well* — so the code reads like the business,
invariants are enforced in one place, and the architecture survives change. It covers
strategic DDD (carving the problem into bounded contexts), tactical DDD (the building
blocks you write code with), CQRS (splitting reads from writes), and event sourcing
(storing facts instead of state).

**Core principle:** the domain model is the asset. Everything else — the database, the web
framework, the message bus — is a detail that plugs into the model, never the other way
around. When persistence, transport, or framework concerns leak into your domain objects,
the model stops being able to express the business and DDD has failed.

One worked domain — **e-commerce Orders & Fulfillment** — runs through every reference file
so the pieces compose instead of floating as disconnected snippets.

## Before you reach for this: do you even need it?

DDD has a real cost. It pays off when the **domain is complex and the rules are the point**
of the software. It is overkill for a CRUD app whose hard part is the UI or the
integrations, not the business logic.

| Signal | Lean toward |
| --- | --- |
| Rich invariants, workflows, state transitions, domain experts who argue about edge cases | DDD |
| "It's just forms over data" — store it, show it, edit it | Plain CRUD / active record |
| One team, one database, simple lifecycle | Tactical DDD without bounded-context ceremony |
| Multiple teams, multiple meanings of the same word ("order" means different things to sales vs. fulfillment) | Strategic DDD — draw bounded contexts first |
| Reads and writes have wildly different shapes/scale | Add CQRS |
| You need a full audit trail, temporal queries, or "why is it in this state?" | Consider event sourcing |
| You reached for CQRS/ES because they sound rigorous | Stop — read `references/anti-patterns.md` |

If the answer is "plain CRUD," say so and stop. Misapplied DDD is worse than no DDD.

## Route First

Pick the reference that matches the task. Read the most specific one first.

| Task | Read |
| --- | --- |
| Carving the problem into bounded contexts, ubiquitous language, subdomains, context mapping, integrating with other teams/systems | `references/strategic-design.md` |
| Writing the building blocks — entities, value objects, aggregates, domain events, domain services, factories, repositories | `references/tactical-patterns.md` |
| Splitting reads from writes, command handlers, read models, projections | `references/cqrs.md` |
| Storing events as the source of truth, rebuilding state from a stream, snapshots, projections | `references/event-sourcing.md` |
| Layering the codebase — hexagonal / ports & adapters / clean / onion, where each block lives, transaction boundaries | `references/application-architecture.md` |
| A complete, copy-paste-ready bounded context in TypeScript | `references/typescript-examples.md` |
| A complete, copy-paste-ready bounded context in Python | `references/python-examples.md` |
| Recognizing and fixing DDD gone wrong — anemic models, ORM leakage, god aggregates, CQRS/ES cargo-cult | `references/anti-patterns.md` |

## The universal mental model

Hold these five ideas in your head no matter which layer you're working in:

1. **Speak the ubiquitous language.** The names in the code (`Order`, `place`, `ship`,
   `LineItem`, `Money`) are the names the business uses. If a domain expert wouldn't
   recognize a class name, it's wrong. A glossary disagreement is a modeling bug, not a
   wording nitpick.

2. **Make illegal states unrepresentable.** Push rules into types and constructors so an
   invalid object can't be built. A `Quantity` that rejects zero and negatives beats
   scattering `if qty <= 0` across the codebase. Validate at the boundary; trust within.

3. **Protect invariants inside an aggregate.** An aggregate is a consistency boundary: a
   cluster of objects that must always be valid *together*, with one entry point (the
   aggregate root). Outside code never reaches in and mutates a child directly — it calls a
   method on the root, which enforces the rule. One transaction changes one aggregate.

4. **Keep the domain pure.** Entities, value objects, and aggregates have **no** import from
   your ORM, web framework, or message broker. They don't know whether they live in
   Postgres or a JSON file. Dependencies point *inward*: infrastructure depends on the
   domain, never the reverse.

5. **Tell the rest of the system what happened, don't command it.** When something
   meaningful occurs, the aggregate records a **domain event** (`OrderShipped`). Other parts
   of the system react. This decouples the core decision ("ship the order") from its
   consequences (email the customer, decrement inventory, update the read model).

## How the layers fit (end-to-end sketch)

A single write flows like this — every block has a dedicated reference:

```
HTTP / CLI / queue            ← adapter (infrastructure)
  → validate input (Zod / Pydantic at the boundary)
  → ApplicationService.placeOrder(command)        ← use case, opens a transaction
      → repository.load(orderId)                   ← port; adapter hydrates the aggregate
      → order.addItem(...) / order.place()         ← AGGREGATE enforces invariants
      → repository.save(order)                      ← one aggregate, one transaction
      → publish(order.pullEvents())                ← domain events go out
  ← returns an id / DTO, never the aggregate itself
```

Reads skip the aggregate entirely (that's CQRS): a query goes straight to a **read model**
shaped for the screen that needs it. Writes go through the domain; reads come from
projections built off the events. See `references/cqrs.md`.

## Red flags — stop and reconsider

- "I'll just add a getter/setter for every field." → anemic model; logic is leaking out of
  the domain. See `references/anti-patterns.md`.
- "The entity extends the ORM base class." → persistence is now welded to your domain.
- "This aggregate has 14 child collections." → too big; find the real consistency
  boundaries and split. Reference other aggregates by id.
- "I'll update three aggregates in one transaction to keep them consistent." → use eventual
  consistency via domain events instead.
- "Let's use CQRS and event sourcing because it's the proper way." → justify the cost
  against the table at the top, or don't.
- "The read model and the domain model are the same class." → reads and writes have
  different shapes; conflating them is why both get awkward.

## Completion criteria

Before considering domain work done:

- The model uses the ubiquitous language; a domain expert would recognize the names.
- Invariants live inside aggregates, enforced through the root — not in services or
  controllers.
- Domain objects import nothing from infrastructure (ORM, web, broker).
- Each transaction modifies exactly one aggregate; cross-aggregate consistency is eventual.

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills