domain-driven-design

What this skill does

# Domain-Driven Design

## Overview

This skill provides guidance for domain modeling based on Rich Hickey's data-oriented design principles and Scott Wlaschin's type-driven design approach. Focus on building systems that make illegal states unrepresentable, prioritize data and transformations over objects and methods, and establish a ubiquitous language that bridges technical implementation and business domain.

## Core Principles

### Rich Hickey's Data-Oriented Design

**Simplicity over Ease**
- Favor simple constructs that can be understood independently
- Avoid complecting (intertwining) unrelated concerns
- Separate policy from mechanism, data from behavior

**Data is King**
- Model the domain using pure data structures, not objects with behavior
- Prefer generic data structures (maps, sets, vectors) over custom classes when appropriate
- Data should be self-describing and inspectable
- Functions transform data; data does not execute behavior

**Value of Values**
- Use immutable values to represent facts
- Values enable local reasoning and simple equality
- Values can be freely shared without coordination
- Consider: what are the immutable facts in this domain?

**Decomplecting**
- Identify what is truly essential to the domain vs. incidental complexity
- Separate when-it-happens from what-happens
- Separate mechanism from policy
- Question: are these concerns actually separate, or have we tangled them?

### Scott Wlaschin's Type-Driven Design

**Make Illegal States Unrepresentable**
- Use the type system to eliminate invalid states at compile time
- Model optional values explicitly (Option/Maybe types)
- Use sum types (discriminated unions) for states that are mutually exclusive
- Avoid primitive obsession; create domain-specific types

**Domain Modeling Made Functional**
- Model workflows as data transformations: Input → Process → Output
- Explicitly model business rules as functions
- Separate validation from business logic
- Think in terms of: What can happen? What are the valid transitions?

**Railway-Oriented Programming**
- Model success and failure paths explicitly (Result types)
- Chain operations that can fail using bind/flatMap
- Keep the happy path clear and linear
- Handle errors at appropriate boundaries

**Types as Documentation**
- Type signatures should communicate intent
- Use newtype wrappers for semantic clarity (UserId, EmailAddress, Timestamp)
- Constrain inputs to valid ranges using types
- Let the type system guide API design

## DDD Building Blocks

### Entities vs Value Objects

**Entities** are defined by identity, not attributes:
- Have a unique identifier (ID, account number, etc.)
- Can change over time while maintaining identity
- Two entities with same attributes but different IDs are distinct
- Used when domain experts refer to things by name/ID

**Value Objects** are defined entirely by attributes:
- No unique identifier
- Immutable
- Two value objects with same attributes are interchangeable
- Used when only the value matters, not identity

**Decision Guide:**
- Ask: Do domain experts refer to this by ID/name? → Entity
- Ask: Can I replace it with an equivalent copy? → If yes: Value Object

### Aggregates and Aggregate Roots

**Aggregate**: A cluster of entities and value objects treated as a single unit for data changes.

**Aggregate Root**: The single entity through which all external access to the aggregate must pass.

**Purpose:**
- Define transactional consistency boundaries
- Enforce invariants that span multiple objects
- Simplify the model by grouping related concepts

**Rules:**
- External references go only to the aggregate root (use ID references)
- Root enforces all invariants for the entire aggregate
- Transactions don't cross aggregate boundaries (use eventual consistency)
- Keep aggregates small for better performance and scalability

**When NOT to create an aggregate:**
- Objects can be modified independently
- No shared invariants requiring transactional consistency
- Different objects have different lifecycles

### Bounded Contexts

**Definition**: An explicit boundary within which a domain model applies.

**Purpose:**
- Divide large domains into manageable pieces
- Allow same term to have different meanings in different contexts
- Prevent model corruption from mixing incompatible concepts

**Key Insight**: Ubiquitous language is only ubiquitous within a context. "Customer" in Sales context may be different from "Customer" in Shipping context.

**When modeling:**
- Identify which bounded context you're in
- Make context boundaries explicit in code structure (separate modules/namespaces)
- Use anti-corruption layers when integrating across contexts
- Document relationships between contexts (context map)

### Domain Events

**Definition**: Something important that happened in the domain.

**Characteristics:**
- Named in past tense (OrderPlaced, PaymentProcessed, UserRegistered)
- Immutable facts
- Domain experts care about them
- Can trigger reactions within or across bounded contexts

**Uses:**
- Decouple domain logic
- Enable eventual consistency between aggregates
- Integration between bounded contexts
- Event sourcing (store events as source of truth)

### Repositories

**Purpose**: Provide illusion of an in-memory collection of aggregates, abstracting persistence.

**Characteristics:**
- Operate at aggregate boundaries (load/save whole aggregates)
- Provide lookup by ID
- Hide database implementation details
- Return domain entities, not database rows

**Pattern**: Application layer uses repository to get/save aggregates; domain layer remains pure.

## Domain Modeling Workflow

### 1. Discover the Ubiquitous Language

Start by identifying the domain concepts, using terminology from domain experts:

**Action Items:**
- List nouns (entities, value objects) and verbs (operations, events) from the domain
- Document domain terms with precise definitions
- Identify synonyms and resolve ambiguity
- Ask: What does the business call this? What are the boundaries of this concept?

**Output Format:**
Create a glossary section documenting each term:
```markdown
**Term** (Type: Entity/ValueObject/Event/Command)
- Definition: [Clear, domain-expert-approved definition]
- Examples: [Concrete examples]
- Invariants: [Rules that must always hold]
```

### 2. Analyze the Existing Domain Model

Before making changes, understand the current state:

**Exploration Steps:**
- Identify where domain concepts are currently modeled (types, schemas, tables)
- Map out relationships between domain entities
- Find where business logic lives (services, functions, stored procedures)
- Document implicit rules and constraints
- Note inconsistencies in naming or modeling

**Questions to Answer:**
- What types/classes represent domain concepts?
- What are the invariants? Where are they enforced?
- Which concepts are tangled together that should be separate?
- Are there phantom types or states that shouldn't exist?

### 3. Identify Inconsistencies and Smells

Common problems to surface:

**Naming Inconsistencies**
- Same concept with different names (User vs Account vs Customer)
- Different concepts with same name (Order as entity vs Order as command)
- Technical names bleeding into domain language (DTO, DAO suffixes)

**Structural Problems**
- Illegal states being representable (e.g., `status: "approved" | "rejected"` with separate `approved_at` and `rejected_at` fields that can both be set)
- Primitive obsession (strings for email, numbers for money)
- Optional fields that are actually required in certain states
- Null/undefined used to represent multiple distinct states

**Complected Concerns**
- Domain logic mixed with infrastructure (DB access in business logic)
- Multiple responsibilities in one type/module
- Temporal coupling (must call A before B or system breaks)

**Missing Concepts**
- Domain concepts that exist in conversations but not in code
- Implicit states that should be explicit
- Business rules enforced thr