domain-driven-design

Files (6)

• SKILL.md
• evals.json · evals/
• application-architecture.md · references/
• integration-patterns.md · references/
• strategic-design.md · references/
• tactical-patterns.md · references/

SKILL.md (first lines)

# Domain-Driven Design

## When This Skill Loads

If you are reading this, the user is working on a system where business complexity, language, or boundaries matter more than generic technical organization. **Model the domain first. Let the code follow the model.**

## Core Principle

**Keep domain behavior, code, tests, documents, and team language aligned inside explicit Bounded Contexts.**

Do not let persistence, UI, frameworks, integration formats, or DDD vocabulary replace an implementation-driving model.

## When DDD Is Warranted

**Any one** of these justifiers is sufficient to warrant strengthening the model:
- Business rules are complex (not just CRUD)
- Domain experts use specific terminology that differs from technical terms
- Multiple teams or systems share data but have different conceptual models
- The same word means different things in different parts of the business
- Invariants and lifecycle rules are non-trivial
- Integration with external/legacy systems requires translation

**When DDD is overkill:** Simple CRUD, generic subsystems, or mainly technical problems. Use the lightest approach that works.

## Strategic Design

### Subdomains

Classify every business capability:

| Type | What it is | Modeling effort |
|---|---|---|
| **Core Domain** | Competitive advantage, strategic differentiation | Highest — rich model, best people, most iteration |
| **Supporting** | Needed for the business, but not a differentiator | Moderate — model honestly, but don't over-invest |
| **Generic** | Commodity (auth, notifications, logging) | Lowest — buy/build simple, no custom modeling |

### Bounded Contexts

Every meaningful model gets **one explicit Bounded Context**. The context owns:
- Its **language** (Ubiquitous Language — one term per concept, one meaning per term)
- Its **rules** and **semantics**
- Its **code structure**, **tests**, and **integration contracts**

**The same word in different contexts may mean different concepts.** "Order" in billing is not "Order" in fulfillment. Translate at boundaries.

### Context Relationships

Choose deliberately:

| Relationship | Meaning | When to use |
|---|---|---|
| **Partnership** | Teams coordinate closely, models evolve together | Same team, tightly coupled contexts |
| **Shared Kernel** | Small shared model, jointly owned and tested | Stable overlap both teams agree on |
| **Customer/Supplier** | Downstream depends on upstream; upstream prioritizes downstream's needs | Clear upstream/downstream dependency |
| **Conformist** | Downstream conforms to upstream's model exactly | No leverage to influence upstream |
| **Anticorruption Layer (ACL)** | Downstream translates upstream's model into its own language | Upstream model is messy, foreign, or legacy |
| **Open Host Service (OHS)** | Upstream provides a published protocol for multiple downstreams | Many consumers need standardized access |
| **Published Language** | Shared format (schema, API contract) for integration | Cross-organization or cross-team integration |
| **Separate Ways** | No integration; contexts are independent | No real dependency exists |

## Tactical Patterns

### Entities
Use when **identity and lifecycle** matter. An Entity is defined by its ID, not its attributes.
- Make identity explicit (e.g., `OrderId`, not a raw integer).
- Protect meaningful state transitions — don't expose unrestricted setters.
- Methods should reveal domain purpose, not just change fields.

### Value Objects
Use for **immutable descriptive concepts** where identity doesn't matter.
- Validate at construction — a Value Object is always valid.
- Compare by value, not by reference.
- Replace raw primitives for meaningful concepts: `Money`, `EmailAddress`, `DateRange`.

### Aggregates
Use as **immediate consistency boundaries** for invariants.
- **Small.** One root Entity, few internal objects. If it's large, the boundary is wrong.
- **Root-protected.** All invariant-changing behavior goes through the root.
- **Identity-referenced.** Reference other Aggregates by ID, not by object reference.
- **One per transaction.** Default to modifying one Aggregate per transaction. Use events for cross-Aggregate coordination.
- **Hide internals.** Mutable internals are not exposed to callers.

### Domain Events
Use for **meaningful past-tense business facts**.
- Name in past tense: `OrderPlaced`, `PaymentReceived`, `ShipmentDelivered`.
- Payload is local to the model — don't leak foreign schemas.
- Do NOT publish for every field change. Events represent business significance.
- Consumers must tolerate lag, duplicates, and ordering limits.

### Repositories
Provide access to **Aggregate Roots**, not tables.
- Define interfaces by domain needs, not by persistence mechanics.
- Return domain objects, not ORM rows or DTOs.
- Keep business rules out of repository implementations.

### Factories
Hide **complex creation** logic.
- Use when constructing an Aggregate requires multi-step validation or assembly.
- Prevent partially formed objects from escaping.

### Domain Services
Use for **domain-significant operations** that involve multiple domain objects and don't fit naturally on any single Entity or Value Object.
- Keep technical transformation, serialization, transport, and persistence mapping OUT of the domain model.

### Application Services
Coordinate **use cases**:
1. Load Aggregates (via Repositories)
2. Invoke domain behavior (on Aggregates/Entities)
3. Persist results
4. Publish resulting Domain Events
5. Own transaction/integration coordination

**Application Services must NOT become the real domain model.** If they accumulate branching business rules, move the decisions into the domain objects.

### Refactoring Toward Deeper Insight

Refactor toward deeper domain insight, not only mechanical cleanliness. When a constraint, policy, process, or calculation carries domain meaning, make it an explicit named model concept instead of leaving it implicit in conditionals or helper code. If new behavior is hard to explain, test, or extend, a deeper model or missing implicit concept is usually waiting — find it rather than adding procedural branches.

## Ubiquitous Language Discipline

From dekoza/oh-my-slop, Unlicense.

More from dekoza/oh-my-slop