DDD Aggregate Boundaries and Persistence in TypeScript

What Is an Aggregate Root in DDD?#

An entity has continuity through identity. An aggregate is a cluster of domain objects that must be kept consistent in one transaction. The aggregate root is the entity through which external code reaches that cluster.

OrderLine can have an ID and still not be an aggregate root. If its quantity, price, and lifecycle are governed by Order, then external code should not load a line and mutate it independently.

The useful questions are practical rather than taxonomic:

These are heuristics, not a scoring system. For immediate consistency within an aggregate, ask: which invariant must be true when this transaction commits? Cross-aggregate processes can instead reconcile their state asynchronously.

For the running example, the maximum order total spans an order and its lines. Order is therefore the root that adds, removes, and prices lines. A Product or Customer has an independent lifecycle and is a separate aggregate.

class Order {
	private constructor(
		private readonly id: OrderId,
		private readonly customerId: CustomerId,
		private lines: OrderLine[],
		private status: OrderStatus
	) {}

	addLine(
		product: ProductId,
		quantity: number,
		unitPriceCents: number
	): Result<void, OrderError> {
		const nextTotal = this.getTotalCents() + quantity * unitPriceCents;
		if (nextTotal > 100_000) return err({ type: "maximum-total-exceeded" });

		const line = OrderLine.create(product, quantity, unitPriceCents);
		if (!line.ok) return line;

		this.lines.push(line.value);
		return ok(undefined);
	}
}

The real boundary is the rule that no application service loads an OrderLine directly, changes it, and persists it around the Order.

A Repository Represents a Root, Not a Table#

Per Eric Evans and Vaughn Vernon, a repository works with aggregate roots — collection-like abstractions over the domain’s consistency boundaries. Martin Fowler’s Repository pattern makes the same separation between domain access and storage mechanics.

That gives a useful default:

interface OrderRepository {
	getById(id: OrderId): Promise<Result<Order, OrderError>>;
	add(order: Order): Promise<Result<void, OrderError>>;
	update(id: OrderId, change: UpdateOrder): Promise<Result<Order, OrderError>>;
}

There is no OrderLineRepository because OrderLine is not independently loaded or changed. The repository rehydrates Order, the callback invokes its behavior methods, and the adapter persists the changed root. A repository for lines would create a path around the root’s total-price and status invariants.

This is a conceptual rule, not a requirement to put every method in one enormous TypeScript interface. Separate read and write ports can be clearer in a larger application:

interface LoadOrder {
	getById(id: OrderId): Promise<Result<Order, OrderError>>;
}

interface UpdateOrderRepository {
	update(id: OrderId, change: UpdateOrder): Promise<Result<Order, OrderError>>;
}

The constraint remains the same: those ports operate on the Order root, not on its internal rows.

One Aggregate, Several Tables#

Domain boundaries and relational-table boundaries answer different questions. This is a normal relational mapping for one order aggregate:

CREATE TABLE orders (
    id              UUID PRIMARY KEY,
    customer_id     UUID NOT NULL REFERENCES customers(id),
    status          TEXT NOT NULL,
    total_cents     INTEGER NOT NULL,
    version         INTEGER NOT NULL DEFAULT 0,
    created_at      TIMESTAMPTZ NOT NULL,
    updated_at      TIMESTAMPTZ NOT NULL
);

CREATE TABLE order_lines (
    id               UUID PRIMARY KEY,
    order_id         UUID NOT NULL REFERENCES orders(id),
    product_id       UUID NOT NULL,
    quantity         INTEGER NOT NULL,
    unit_price_cents INTEGER NOT NULL
);

CREATE TABLE order_status_history (
    id          UUID PRIMARY KEY,
    order_id    UUID NOT NULL REFERENCES orders(id),
    from_status TEXT,
    to_status   TEXT NOT NULL,
    changed_at  TIMESTAMPTZ NOT NULL
);

The orders and order_lines rows map to the aggregate’s current state. total_cents is a denormalized cache of the lines: the adapter writes it from them and verifies it before reconstituting the aggregate. order_status_history is an append-only audit log. It is not event sourcing: in an event-sourced model, the events would be the authoritative state and the current status would be a projection.

OrderRepository may read and write all three tables in one local transaction. That does not make the repository “three repositories in one.” It is one persistence adapter for one aggregate.

class Order {
	// The domain has an ID, not a navigation property to Customer.
	private readonly customerId: CustomerId;
}

Mapping Is an Adapter Responsibility#

The repository interface speaks domain language. The adapter translates relational shapes to domain shapes and back.

Keep the mapper boring and fail fast when stored data cannot produce a valid aggregate. It reads the orders row and its order_lines, reconstitutes each line, then reconstitutes the Order. On a write, it does the reverse.

Do not filter invalid rows and continue. A partial aggregate can pass a business check while silently losing data. Return a persistence error, alert on it, and repair the stored record.

References Across Aggregates#

An order can refer to a customer by ID without loading a customer object:

class Order {
	constructor(private readonly customerId: CustomerId) {}
}

If a use case requires the customer’s credit status, the application service decides whether to load Customer, query a read model, or ask an external service. That keeps the Order model from carrying a stale object graph and makes the cross-aggregate dependency visible where the use case lives.

Reference by ID is a default. A small immutable value copied into an aggregate, such as a shipping address captured at checkout, is often exactly the right model. The question is whether it has an independent lifecycle and invariant set.

Bounded Contexts Change the Model#

A bounded context is a model and language boundary. An aggregate is a transactional boundary inside that context. They solve different problems.

Sales and Support may both speak about a customer, but their models can legitimately differ:

SalesCustomer owns credit, purchases, and pricing rules. SupportCustomer owns SLA, escalation, and ticket routing. The duplication cost is mapping, tests, and the risk that the two copies drift. The sharing cost is coupling, coordinated releases, and irrelevant fields leaking into each context. Pick the cost that matches the relationship between the teams and the language.

An Anti-Corruption Layer prevents the supplier’s domain model from leaking into the local context when one context consumes another context’s API or events.

Cross-Aggregate Workflows#

The previous article showed a repository update for one aggregate. Placing an order can also reserve inventory and authorize payment. The correct coordination model depends on the consistency requirement and deployment boundary.

For the third case, use the word saga precisely. A saga is a sequence of local transactions with recovery behavior. It needs durable state, correlation IDs, idempotent handlers, and a policy for compensation failure.

For example, submitting an order can request inventory without loading Inventory inside Order. This is an orchestrated saga because the process manager keeps durable state and drives recovery:

1. SubmitOrder commits the Order and an OrderSubmitted outbox record together.
2. An outbox publisher delivers OrderSubmitted after that commit.
3. ReserveInventory deduplicates the message and handles it in Inventory's own transaction.
4. It commits inventory and an InventoryReserved or InventoryRejected outbox record with the same correlation ID.
5. The process manager deduplicates that result, then retries, cancels the order, or requests payment.

OrderSubmitted is an integration event: a deliberately stable message contract for another aggregate or service. A domain event expresses a fact within its bounded context; it can be delivered synchronously or asynchronously, but it is not automatically an external contract. Do not make the order wait for inventory unless the business rule requires one database transaction.

Two coordination styles are common:

• Orchestration: a process manager records its state and sends commands. It is easier to observe and test because the workflow is central.
• Choreography: each service reacts to events. It reduces central coordination but makes the overall flow harder to trace.

Do not call a synchronous in-memory event dispatcher a production saga. It can test routing and domain reactions. It cannot prove durable delivery, broker retries, ordering, or recovery after a process crash.

A Decision Checklist#

Before adding an entity, repository, table, or event, ask:

1. Which invariant must hold at commit time?
2. Which object is responsible for enforcing it?
3. Does this object need an independent lifecycle?
4. Is this a command-side aggregate operation or a read-side query?
5. Do the participating models share a database, a service boundary, or only an event contract?
6. What happens when the process is retried, duplicated, delayed, or partially fails?

The answers will not remove every design debate. They make the actual trade-off visible before a table layout or framework convention makes the decision by accident.

Sources#

• Eric Evans, Domain-Driven Design, especially the chapters on entities, aggregates, and bounded contexts.
• Vaughn Vernon, Implementing Domain-Driven Design, for aggregate design and context mapping.
• Martin Fowler on Repository and Anti-Corruption Layer.
• SAP’s curated repository guidance as a secondary synthesis of the Evans and Vernon position.
• Three Dots Labs on repository updates for the transactional closure pattern referenced in the previous article.