Aggregate Design Patterns
Design aggregates with clear boundaries, invariants, and consistency guarantees.
Overview
- Defining transactional consistency boundaries
- Enforcing business invariants across related entities
- Designing aggregate roots and their children
- Handling references between aggregates
- Optimizing aggregate size for performance
Core Concepts
┌─────────────────────────────────────────────────────────┐
│ ORDER AGGREGATE │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Order (Aggregate Root) │ │
│ │ • id: UUID (UUIDv7) │ │
│ │ • customer_id: UUID (reference by ID!) │ │
│ │ • status: OrderStatus │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ OrderItem │ │ OrderItem │ │
│ │ (child) │ │ (child) │ │
│ └────────────────┘ └────────────────┘ │
│ │
│ INVARIANTS enforced by root: │
│ • Total = sum of items │
│ • Max 100 items per order │
│ • Cannot modify after shipped │
└─────────────────────────────────────────────────────────┘Four Rules
- Root controls access - External code only references aggregate root
- Transactional boundary - One aggregate per transaction
- Reference by ID - Never hold references to other aggregates
- Invariants enforced - Root ensures all business rules
Quick Reference
from dataclasses import dataclass, field
from uuid import UUID
from uuid_utils import uuid7
@dataclass
class OrderAggregate:
"""Aggregate root with invariant enforcement."""
id: UUID = field(default_factory=uuid7)
customer_id: UUID # Reference by ID, not Customer object!
_items: list["OrderItem"] = field(default_factory=list)
status: str = "draft"
MAX_ITEMS = 100
def add_item(self, product_id: UUID, quantity: int, price: Money) -> None:
"""Add item with invariant checks."""
self._ensure_modifiable()
if len(self._items) >= self.MAX_ITEMS:
raise DomainError("Max items exceeded")
self._items.append(OrderItem(product_id, quantity, price))
def _ensure_modifiable(self) -> None:
if self.status != "draft":
raise DomainError(f"Cannot modify {self.status} order")See aggregate-root-template.py for complete implementation.
Key Decisions
| Decision | Recommendation |
|---|---|
| Aggregate size | Small (< 20 children), split if larger |
| Cross-aggregate refs | Always by ID, never by object |
| Consistency | Immediate within, eventual across |
| Events | Collect in root, publish after persist |
See aggregate-sizing.md for sizing guidelines.
Anti-Patterns (FORBIDDEN)
# NEVER reference aggregates by object
customer: Customer # WRONG → customer_id: UUID
# NEVER modify multiple aggregates in one transaction
order.submit()
inventory.reserve(items) # WRONG - use domain events
# NEVER expose mutable collections
def items(self) -> list:
return self._items # WRONG → return tuple(self._items)
# NEVER have unbounded collections
orders: list[Order] # WRONG - grows unboundedRelated Skills
domain-driven-design- DDD building blocks (entities, VOs)distributed-locks- Cross-aggregate coordinationidempotency-patterns- Safe retries
References
- Aggregate Sizing - When to split
- Invariant Enforcement - Business rules
- Eventual Consistency - Cross-aggregate
Capability Details
aggregate-root
Keywords: aggregate root, consistency boundary, transactional Solves: Design aggregate roots, control child access, enforce boundaries
invariants
Keywords: invariant, business rule, validation, specification Solves: Enforce business rules, validate state, specification pattern
aggregate-sizing
Keywords: aggregate size, small aggregate, performance Solves: Right-size aggregates, when to split, performance trade-offs
cross-aggregate
Keywords: reference by ID, eventual consistency, domain events Solves: Reference other aggregates, coordinate changes, eventual consistency