Domain Driven Design

Domain-Driven Design Tactical Patterns

Model complex business domains with entities, value objects, and bounded contexts.

Overview

• Modeling complex business logic
• Separating domain from infrastructure
• Establishing clear boundaries between subdomains
• Building rich domain models with behavior
• Implementing ubiquitous language in code

Building Blocks Overview

Copy code
┌─────────────────────────────────────────────────────────────┐
│                    DDD Building Blocks                       │
├─────────────────────────────────────────────────────────────┤
│  ENTITIES           VALUE OBJECTS        AGGREGATES         │
│  Order (has ID)     Money (no ID)        [Order]→Items      │
│                                                              │
│  DOMAIN SERVICES    REPOSITORIES         DOMAIN EVENTS      │
│  PricingService     IOrderRepository     OrderSubmitted     │
│                                                              │
│  FACTORIES          SPECIFICATIONS       MODULES            │
│  OrderFactory       OverdueOrderSpec     orders/, payments/ │
└─────────────────────────────────────────────────────────────┘

Quick Reference

Entity (Has Identity)

pythonCopy code
from dataclasses import dataclass, field
from uuid import UUID
from uuid_utils import uuid7

@dataclass
class Order:
    """Entity: Has identity, mutable state, lifecycle."""
    id: UUID = field(default_factory=uuid7)
    customer_id: UUID = field(default=None)
    status: str = "draft"

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Order):
            return NotImplemented
        return self.id == other.id  # Identity equality

    def __hash__(self) -> int:
        return hash(self.id)

ID generation is a house rule, not a taste call: Read("references/ork-delta.md").

Value Object (Immutable)

pythonCopy code
from dataclasses import dataclass
from decimal import Decimal

@dataclass(frozen=True)  # MUST be frozen!
class Money:
    """Value Object: Defined by attributes, not identity."""
    amount: Decimal
    currency: str

    def __add__(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("Cannot add different currencies")
        return Money(self.amount + other.amount, self.currency)

Canonical Address / DateRange boilerplate is not restated here. See the upstream coverage table below.

Key Decisions

Rules Quick Reference

When NOT to Use

Under 5 entities? Skip DDD entirely. The ceremony costs more than the benefit.

Rule of thumb: DDD adds ~40% code overhead. Only worth it when domain complexity genuinely demands it (5+ entities with invariants spanning multiple objects). A CRUD app with DDD is a red flag.

Anti-Patterns (FORBIDDEN)

pythonCopy code
# NEVER have anemic domain models (data-only classes)
@dataclass
class Order:
    id: UUID
    items: list  # WRONG - no behavior!

# NEVER leak infrastructure into domain
class Order:
    def save(self, session: Session):  # WRONG - knows about DB!

# NEVER use mutable value objects
@dataclass  # WRONG - missing frozen=True
class Money:
    amount: Decimal

# NEVER have repositories return ORM models
async def get(self, id: UUID) -> OrderModel:  # WRONG - return domain!

Upstream coverage (do not restate)

These topics are documented first-party. Read the source instead of re-deriving them here; only the house consequences are kept, in references/ork-delta.md.

Two subjects deliberately stay in this skill rather than routing upstream: the repository and Unit of Work implementation, which lives in full in references/repositories.md, and aggregate boundaries, invariants, and sizing, which live in full in rules/.

Related Skills

• rules/aggregate-boundaries.md, rules/aggregate-invariants.md, rules/aggregate-sizing.md - aggregate design, in this skill
• ork:architecture-patterns - Layer boundaries and project structure validation
• ork:distributed-systems - Cross-aggregate coordination
• ork:database-patterns - Schema design for DDD

References

Load on demand with Read("references/<file>"):

Capability Details

entities

Keywords: entity, identity, lifecycle, mutable, domain object Solves: Identity equality by ID, and the house UUIDv7 ID rule in references/ork-delta.md. Dataclass mechanics route upstream.

value-objects

Keywords: value object, immutable, frozen, dataclass, structural equality Solves: When to use VO vs entity. frozen=True semantics and inherited field ordering route upstream.

domain-services

Keywords: domain service, business logic, cross-aggregate, stateless Solves: When to use domain service, logic spanning aggregates

repositories

Keywords: repository, persistence, collection, IRepository, protocol Solves: Implement repository pattern, abstract DB access, ORM mapping

bounded-contexts

Keywords: bounded context, context map, ACL, subdomain, ubiquitous language Solves: The house ACL boundary and context-first source layout in references/ork-delta.md. Context mapping and integration patterns route upstream.