Aggregates: The Consistency Boundary

Lesson 3 of the DDD course · Invariants, transition functions, and reference-by-identity · ~30 minutes

1 · Value objects 2 · Entities & identity 3 · Aggregates 4 · Lifecycle state machines 5 · Domain events 6 · Bounded contexts 7 · Context mapping 8 · Functional core 9 · Capstone
Why this matters for your mission The aggregate is where your startup's real rules live: “an order's total equals its lines”, “you can't add items after payment”. Today you learn to enforce every rule in exactly one place — so the codebase that's easy to change on day 500, not just day 1.

One entity plus its tightly-bound parts, guarded by functions. This is the pattern most of Meridian's business logic will live in.

1 · The problem: rules with no home

Meridian rules, straight from the business:

In a typical codebase, those rules end up scattered: one check in the HTTP handler, another in the checkout component, a third in a database trigger, none in the type. Then a new code path — the admin tool, the import job — forgets one. This is the anemic domain model: types that carry data while the rules live everywhere and nowhere.[Fowler]

2 · The aggregate: one boundary for the rules

An aggregate is a cluster of entities and value objects treated as a single unit, with one entry point — the root. Its defining promise: the rules inside the boundary are true instantly, after every change.[Evans; Fowler] Meridian's order aggregate: the Order root plus its OrderLines (Email, Cents, Quantity ride along inside lines).

The functional translation of that promise is beautifully small:

The rule Aggregate data is immutable and private-ish. All change goes through pure transition functions that validate, then return a new aggregate — or a typed rejection. The transition function is the guard. No other code path can break the invariants, because no other code path can produce an aggregate.
interface Order {
  readonly id: OrderId;
  readonly customerId: CustomerId;
  readonly status: OrderStatus;
  readonly lines: readonly OrderLine[];
  readonly total: Cents;          // invariant: always equals Σ qty × unitPrice
}

export function addLine(order: Order, line: OrderLine): Result<Order, OrderError> {
  if (order.status !== "draft")
    return { ok: false, error: "order not editable" };
  if (!Number.isInteger(line.qty) || line.qty <= 0)
    return { ok: false, error: "quantity must be a positive whole number" };
  if (order.lines.some(l => l.product === line.product))
    return { ok: false, error: "duplicate product line" };
  const lines = [...order.lines, line];
  const total = lines.reduce((s, l) => s + l.qty * l.unitPrice, 0);
  return { ok: true, value: { ...order, lines, total } };
}

Read the signature — it is the design document: “give me an order and a line; you'll get back either a valid new order or a named reason”. Every caller, current and future, inherits the rules. The total can never drift, because the only function that touches lines recomputes it.

3 · Reference other aggregates by identity

The order holds customerId — a branded id, not a Customer object. Why:

Gotchas (1) Keep aggregates small — the smallest cluster whose rules must be instantly true. “One aggregate per screen” or “per table” are anti-heuristics. (2) One aggregate instance per transaction: concurrent addLine calls to the same order — last writer wins, so the shell retries or rejects (Lesson 8). (3) If you find “handlers” reaching into order.lines directly, the transition module is leaking — fix the export list.

4 · Practice: enforce the boundary

Implement addLine with all four business rules. Tests reject every illegal path and verify the recomputed total.

5 · Retrieval check

6 · Where this goes next

The aggregate guards what's true right now. But “draft → placed → shipped” is a lifecycle, and modeling it with a status string keeps illegal stages representable. Next lesson: make illegal states unrepresentable — each stage becomes its own type, and the compiler refuses to ship a draft.

Your teacher is the agent Aggregate drawing is the most-debated skill in DDD — real teams argue for weeks about where one boundary ends. Bring me your candidate aggregate (“here's my Order, here's what I put inside”) and I'll stress-test it with you before you commit to it.
Primary source for this lesson Read Fowler's “DDD Aggregate” (~5 min, the crispest canonical statement), then Khononov's *Learning Domain-Driven Design* aggregate chapter for the design heuristics (consistency requirements, small aggregates, reference by id).
← Lesson 2: Entities Patterns cheat sheet →