domain-driven-design

name: domain-driven-design license: MIT compatibility: "Claude Code 2.1.277+." description: "DDD tactical patterns for complex business modeling including entities, value objects, aggregates, domain services, repositories, specifications, and bounded contexts. Python dataclass implementations with TypeScript alternatives. Use when building rich domain models, enforcing invariants, or separating domain logic from infrastructure." context: fork agent: backend-system-architect user-invocable: false disable-model-invocation: true metadata: category: document-asset-creation version: "1.0.0" author: "OrchestKit" complexity: "medium" tags: "ddd, domain-modeling, entities, value-objects, bounded-contexts, python" allowed-tools:

• Read
• Glob
• Grep
• WebFetch
• WebSearch

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

┌─────────────────────────────────────────────────────────────┐
│                    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)

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)

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)

# 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.