Nw Domain Driven DesignSAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nw-domain-driven-design
description: Strategic and tactical DDD patterns, bounded context discovery, context mapping, aggregate design rules, and decision frameworks for when to apply DDD
user-invocable: false
disable-model-invocation: true
---

# Domain-Driven Design

## When to Apply DDD

DDD addresses domain complexity (business rules, language, boundaries), not technical complexity (scaling, performance). Apply selectively.

| Domain Type (Cynefin) | DDD Investment | Approach |
|------------------------|----------------|----------|
| Clear/Simple | None -- use CRUD | Standard patterns, no modeling overhead |
| Complicated | Tactical only | Expert analysis, pragmatic patterns suffice |
| Complex | Full strategic + tactical | Iterative modeling, bounded contexts, continuous refinement |
| Chaotic | Stabilize first | Emergency patches, then apply DDD incrementally |

### Signs You Need DDD
- Domain experts and developers frequently misunderstand each other
- Business rules are complex, interconnected, frequently changing
- Multiple teams work on the same codebase with conflicting models
- System has grown into a "big ball of mud"
- Business logic scattered across services, controllers, database procedures

### Signs DDD Is Overkill
- Simple CRUD without complex business rules
- Technical complexity outweighs domain complexity
- Small team, small codebase, single bounded context
- For simple microservices, anemic domain model is acceptable (not an anti-pattern)

## Strategic DDD

### Subdomain Classification

| Criterion | Core | Supporting | Generic |
|-----------|------|------------|---------|
| Competitive advantage | Yes | No | No |
| Unique to organization | Yes | Partially | No |
| Build or buy | Build | Build (simplified) | Buy/integrate |
| DDD investment | Full strategic + tactical | Pragmatic tactical | Minimal/none |
| Developer allocation | Senior/best talent | Mid-level | Junior/integration |

### Bounded Contexts

A bounded context is the boundary within which a particular domain model is defined and applicable. Different from subdomains: a bounded context is a software boundary; a subdomain is a problem-space concept. They should align but are not the same.

**Discovery techniques**:
- **Language divergence**: same term means different things to different groups -- you have crossed a boundary
- **Organizational structure**: different departments often correspond to different contexts
- **Consistency requirements**: where true invariants must be maintained transactionally
- **EventStorming**: Big Picture workshops surface boundaries through hotspots and swimlane divergences
- **Domain Storytelling**: actors, work objects, activity arrows reveal natural boundaries

**Common mistakes**:
1. Confusing contexts with subdomains (software boundary vs. problem-space concept)
2. Assuming one microservice = one bounded context (Evans calls this an "oversimplification")
3. Making contexts too large (big ball of mud with conflicting models)
4. Making contexts too small (excessive cross-context communication overhead)

### Context Mapping Patterns

Nine patterns organized by team relationship type.

| Pattern | Relationship | When to Use |
|---------|-------------|-------------|
| Partnership | Mutually dependent | Teams must deliver together; true reciprocal dependency |
| Shared Kernel | Shared model subset | Close coordination around common concepts. Keep small |
| Customer-Supplier | Upstream-downstream | Asymmetric dependencies requiring structured negotiation |
| Conformist | Downstream adopts upstream | Integration simplicity outweighs design freedom |
| Anti-Corruption Layer | Isolating translation | Protecting domain from poor upstream models; legacy integration |
| Open Host Service | Standardized API | Supporting multiple downstream teams |
| Published Language | Shared schema/format | Standardized formats for inter-context translation (iCalendar, vCard) |
| Separate Ways | No connection | Contexts have no meaningful interdependencies |
| Big Ball of Mud | Recognition only | Demarcate and quarantine legacy/poorly-structured systems |

**Relationship categories**: Mutually Dependent (Partnership) | Upstream/Downstream (Customer-Supplier, Conformist, ACL) | Free (Separate Ways)

**Evolution**: context maps evolve during refactoring. A Conformist relationship can be refactored to Customer-Supplier with an ACL. Draw context maps before writing code.

### Ubiquitous Language

A common, rigorous vocabulary shared between developers and domain experts, scoped per bounded context.

**Rules**:
1. Never use generic technical terms when a domain term exists
2. If developers and domain experts use different words for the same concept, resolve the conflict
3. When the model becomes hard to express in code, the language needs refinement
4. The same word may mean different things in different contexts -- this is expected

Code must reflect the language: class names, method names, variable names use domain terms. When the language changes, the code changes.

## Tactical DDD

### Aggregates -- Four Design Rules (Vernon)

1. **Model true invariants in consistency boundaries**: only include elements that must be consistent within the same transaction
2. **Design small aggregates**: ~70% of aggregates contain only a root entity with value-typed properties. Large aggregates create concurrency contention and scalability failures
3. **Reference other aggregates by identity**: use `ProductId` not `Product`. Prevents accidental cross-aggregate transactions
4. **Use eventual consistency outside the boundary**: domain events are the vehicle. One transaction = one aggregate

**Common mistakes**: including objects for compositional convenience | "god aggregates" | direct object references | requiring immediate consistency where eventual suffices

### Entities vs. Value Objects

| Criterion | Entity | Value Object |
|-----------|--------|--------------|
| Identity matters | Yes (tracked over tim

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.