ddd-workflow

name	ddd-workflow
description	Domain-driven design discipline — bounded contexts, ubiquitous language, aggregates, domain events, context maps, and how the .planning/DOMAIN.md file drives code structure and naming. Use whenever the user is modelling a new domain, extracting domain concepts from existing code, deciding where code should live, or naming things.

DDD Workflow

Draht embeds domain-driven design into project initialization, planning, and execution. The .planning/DOMAIN.md file is the single source of truth for domain concepts.

.planning/DOMAIN.md Structure

## Bounded Contexts
- **Billing** — everything about invoices, payments, subscriptions
- **Catalog** — products, pricing, availability
- **Fulfillment** — order processing, shipping, returns

## Ubiquitous Language
- **Invoice** — a document requesting payment for delivered goods or services
- **Order** — a customer's request to purchase goods, before fulfillment
- **Line Item** — a single row on an invoice or order
- **SKU** — a unique identifier for a product variant in the catalog

## Context Map
- Billing ← Catalog (downstream — billing reads product info)
- Fulfillment ← Billing (downstream — fulfillment needs invoice status)
- Shared kernel: Money, TaxRate (used by Billing and Fulfillment)

## Aggregates
### Billing
- Invoice (root) — LineItem, Payment
- Subscription (root) — BillingCycle

### Catalog
- Product (root) — Variant, Price

## Domain Events
- `InvoiceIssued` — Billing → Fulfillment, Notification
- `PaymentReceived` — Billing → Notification
- `OrderShipped` — Fulfillment → Notification, Customer

The Five Rules

1. Bounded contexts shape the code

• File/module structure mirrors bounded contexts: src/billing/, src/catalog/, src/fulfillment/
• Each context owns its aggregates, value objects, services, and domain events
• Cross-context imports are suspicious — prefer domain events or ACL adapters

2. Code uses the ubiquitous language

• Class names, method names, variable names must match the glossary
• If you need a new term, update DOMAIN.md first, then write the code
• Never invent terms in code that aren't in the glossary

3. Aggregates enforce invariants

• Each aggregate has one root entity
• All writes go through the root — never modify child entities directly from outside
• Aggregate boundaries align with transaction boundaries
• Aggregates reference each other by ID, not by reference

4. Domain events cross context boundaries

• Upstream context publishes an event (InvoiceIssued)
• Downstream contexts subscribe and react (Notification sends email, Fulfillment releases order)
• No direct function call from Billing into Fulfillment — always via event

5. Shared kernel is explicit

• If two contexts must share a type (e.g. Money, TaxRate), put it in src/shared/ and document it in the Context Map
• Shared kernel changes are high-cost — they affect multiple contexts
• Prefer duplication over coupling when in doubt

The Post-Phase Domain Health Check

The gsd-post-phase.cjs hook checks DOMAIN.md after each phase:

• Is ## Bounded Contexts section present?
• Is ## Ubiquitous Language section present?
• Count of unique PascalCase terms (proxy for glossary size)

The gsd-quality-gate.cjs script also runs a domain validator that compares identifiers in code against the glossary and flags unknown terms.

Drift check: after each phase, run draht-tools graph-clusters and compare the map's clusters/contexts against DOMAIN.md — a new cluster or a cluster spanning two contexts means the code drifted from the model. Reconcile DOMAIN.md first, then the code.

Extracting Domain from Existing Code

When running /init-project or /map-codebase on a codebase that wasn't built with DDD:

0. Surface CANDIDATE contexts from the map: draht-tools graph-clusters for code groupings + draht-tools graph-context <dir> to orient each. Clusters are STRUCTURAL (import topology), not semantic — confirm with a human before equating a cluster with a bounded context.
1. List top-level src/ subdirectories — candidates for bounded contexts
2. Scan PascalCase class / interface / type names — seed from modules[*].symbols / GRAPH_REPORT.md instead of grepping — candidates for entities and value objects
3. Scan repeated nouns in function names — candidates for domain concepts
4. Look for cross-directory imports — candidates for context coupling to fix
5. Write DOMAIN.md with what you found + what should exist
6. Use subsequent phases to refactor toward the target model

Anti-patterns

Anemic domain model — entities that are just data bags with no behaviour. Push logic into the entities.

Scattered aggregates — one aggregate's logic spread across multiple contexts. Consolidate or introduce an ACL.

Terminology drift — the same concept called different things in different files. Fix in DOMAIN.md first, rename code second.

Shared database — multiple contexts writing to the same tables without explicit shared-kernel agreement. Break the coupling.

Direct cross-context imports — import { ... } from '../billing/...' in src/fulfillment/. Use domain events or ACL adapters.

When to Update DOMAIN.md

• Before writing code that introduces a new term → add it to the glossary first
• During /discuss-phase when gray areas reveal missing concepts
• After /verify-work when the reviewer agent flags domain language drift
• Whenever a refactor reveals that existing names don't match reality