newspaper_wedding/.aidlc/knowledge/aidlc-architect-agent/ddd-patterns.md

Domain-Driven Design Patterns

Purpose

DDD aligns software design with business reality. It provides patterns for modeling complex domains so that the code structure mirrors how the business thinks and operates.

Strategic Design

Bounded Contexts

A bounded context is an explicit boundary within which a domain model exists. The same real-world concept (e.g., "Customer") can have different meanings in different contexts.

Example:

• Sales context: Customer has leads, deals, revenue potential
• Support context: Customer has tickets, SLAs, satisfaction score
• Billing context: Customer has invoices, payment methods, credit limit

Rules:

• Each bounded context owns its data and logic — no shared database between contexts
• Communication between contexts uses well-defined interfaces (APIs, events)
• Each context can use different technology stacks and deployment strategies

Context Mapping Patterns

Pattern	Relationship	Use When
Shared Kernel	Two teams share a small common model	Teams are closely aligned and can coordinate changes
Customer-Supplier	Upstream supplies data, downstream consumes	Clear provider/consumer relationship between teams
Conformist	Downstream adopts upstream's model as-is	Upstream has no incentive to accommodate downstream needs
Anti-Corruption Layer	Downstream translates upstream's model	Integrating with legacy systems or external services
Open Host Service	Upstream publishes a well-defined protocol	Multiple consumers need access to a context's capabilities
Published Language	Shared interchange format (e.g., JSON schema)	Cross-context communication needs a stable contract
Separate Ways	No integration	The cost of integration exceeds the benefit

Anti-Corruption Layer (ACL)

When integrating with an external or legacy system whose model does not match yours:

Your Domain Model <-> ACL (translates) <-> External System Model

The ACL isolates your clean model from the external system's concepts. If the external system changes, only the ACL needs updating.

Tactical Design

Entities

Objects defined by their identity, not their attributes. Two customers with the same name are different customers if they have different IDs.

• Have a unique identifier that persists across state changes
• Mutable — their state changes over time
• Example: User, Order, Account

Value Objects

Objects defined by their attributes, not their identity. Two Money objects with the same amount and currency are interchangeable.

• Immutable — create a new instance instead of modifying
• No identity — equality is based on all attributes
• Example: EmailAddress, Money, DateRange, Address
• Prefer value objects over primitives (an email is not just a string)

Aggregates

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

Rules:

• Each aggregate has exactly one aggregate root — the only entity external code can reference
• All changes to the aggregate go through the root (enforces invariants)
• Transactions should not span multiple aggregates
• Reference other aggregates by ID, not by object reference
• Keep aggregates small — large aggregates cause contention and performance issues

Example:

Order (Aggregate Root)
  ├── OrderLine (Entity, only accessible through Order)
  ├── ShippingAddress (Value Object)
  └── OrderStatus (Value Object)

External code calls order.addItem(product, quantity) — never modifies OrderLine directly.

Domain Events

Record something meaningful that happened in the domain. Events are past-tense facts.

Naming: [Entity][PastTenseVerb] — OrderPlaced, PaymentReceived, InventoryDepleted

Structure:

• Event ID (unique)
• Timestamp (when it occurred)
• Aggregate ID (which aggregate produced it)
• Payload (relevant data at the time of the event)

Uses:

• Trigger side effects in other bounded contexts (eventual consistency)
• Build audit trails and event sourcing
• Enable loose coupling — publishers do not know about subscribers

Repository Pattern

Provides a collection-like interface for accessing aggregates, hiding persistence details from the domain layer.

Interface (defined in the domain layer):

interface OrderRepository {
  findById(id: OrderId): Order | null
  save(order: Order): void
  findByCustomer(customerId: CustomerId): Order[]
}

Rules:

• One repository per aggregate root (not per entity or table)
• Repository interface lives in the domain layer; implementation lives in infrastructure
• Repositories return fully constituted aggregates, not partial data
• Do not put query logic in repositories — use separate read models for complex queries

Event Storming

A collaborative workshop technique for discovering domain events, commands, and aggregates.

Process

1. Gather: Domain experts + developers in a room with unlimited sticky notes
2. Domain Events (orange): Brainstorm everything that happens in the domain (past tense)
3. Commands (blue): What triggers each event? (imperative: "Place Order")
4. Actors (yellow): Who or what issues the command? (User, System, Scheduler)
5. Aggregates (pale yellow): Group events around the entity they affect
6. Bounded Contexts: Draw boundaries around related aggregate clusters
7. Policies (purple): Automated reactions ("When OrderPlaced, then ReserveInventory")

Output

A visual map of the domain that reveals:

• Core business processes and their interactions
• Natural bounded context boundaries
• Integration points between contexts
• Hot spots (areas of complexity, contention, or confusion)

Design Heuristics

• If two concepts change for different reasons, they belong in different bounded contexts
• If you need a transaction across two aggregates, reconsider the aggregate boundaries
• Start with larger aggregates and split when you encounter contention or performance issues
• Domain events are the primary integration mechanism between bounded contexts
• Ubiquitous language: use the same terms in code, documentation, and conversation with domain experts