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)

Load Read("${CLAUDE_SKILL_DIR}/references/entities-value-objects.md") for complete patterns.

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)

Load Read("${CLAUDE_SKILL_DIR}/references/entities-value-objects.md") for Address, DateRange examples.

Key Decisions

Decision Recommendation

Entity vs VO Has unique ID + lifecycle? Entity. Otherwise VO

Entity equality By ID, not attributes

Value object mutability Always immutable (frozen=True )

Repository scope One per aggregate root

Domain events Collect in entity, publish after persist

Context boundaries By business capability, not technical

Rules Quick Reference

Rule Impact What It Covers

aggregate-boundaries (load ${CLAUDE_SKILL_DIR}/rules/aggregate-boundaries.md ) HIGH Aggregate root design, reference by ID, one-per-transaction

aggregate-invariants (load ${CLAUDE_SKILL_DIR}/rules/aggregate-invariants.md ) HIGH Business rule enforcement, specification pattern

aggregate-sizing (load ${CLAUDE_SKILL_DIR}/rules/aggregate-sizing.md ) HIGH Right-sizing, when to split, eventual consistency

When NOT to Use

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

Pattern Interview Hackathon MVP Growth Enterprise Simpler Alternative

Aggregates OVERKILL OVERKILL OVERKILL SELECTIVE APPROPRIATE Plain dataclasses with validation

Bounded contexts OVERKILL OVERKILL OVERKILL BORDERLINE APPROPRIATE Python packages with clear imports

CQRS OVERKILL OVERKILL OVERKILL OVERKILL WHEN JUSTIFIED Single model for read/write

Value objects OVERKILL OVERKILL BORDERLINE APPROPRIATE REQUIRED Typed fields on the entity

Domain events OVERKILL OVERKILL OVERKILL SELECTIVE APPROPRIATE Direct method calls between services

Repository pattern OVERKILL OVERKILL BORDERLINE APPROPRIATE REQUIRED Direct ORM queries in service layer

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!

Related Skills

• aggregate-patterns

• Deep dive on aggregate design

• ork:distributed-systems

• Cross-aggregate coordination

• ork:database-patterns

• Schema design for DDD

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>") :

File Content

entities-value-objects.md

Full entity and value object patterns

repositories.md

Repository pattern implementation

domain-events.md

Event collection and publishing

bounded-contexts.md

Context mapping and ACL

Capability Details

entities

Keywords: entity, identity, lifecycle, mutable, domain object Solves: Model entities in Python, identity equality, adding behavior

value-objects

Keywords: value object, immutable, frozen, dataclass, structural equality Solves: Create immutable value objects, when to use VO vs entity

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: Define bounded contexts, integrate with ACL, context relationships