6a:T6cb,graph TB subgraph OrderAggregate["Order Aggregate"] Order["Order (Root)"] OrderItem1["OrderItem 1"] OrderItem2["OrderItem 2"] OrderItem3["OrderItem 3"] ShippingAddress["Shipping Address"] Order --> OrderItem1 Order --> OrderItem2 Order --> OrderItem3 Order --> ShippingAddress end subgraph ProductAggregate["Product Aggregate"] Product["Product (Root)"] end subgraph CustomerAggregate["Customer Aggregate"] Customer["Customer (Root)"] end Order -.->|"References by ID"| Product Order -.->|"References by ID"| Customer style Order fill:#4f46e5,color:#fff style Product fill:#4f46e5,color:#fff style Customer fill:#4f46e5,color:#fff style OrderAggregate fill:#e0e7ff,stroke:#4f46e5 style ProductAggregate fill:#e0e7ff,stroke:#4f46e5 style CustomerAggregate fill:#e0e7ff,stroke:#4f46e56b:T45a,// ❌ Without aggregates: Direct manipulation of internal objects class OrderItem { constructor( public productId: string, public quantity: number, public unitPrice: number ) {} // Anyone can change quantity directly setQuantity(quantity: number) { this.quantity = quantity; // But who updates the order total? // Who checks if we exceeded 10 items? // Who verifies the credit limit? } } class Order { public items: OrderItem[] = []; // Exposed for direct modification! public total: number = 0; // Total can become stale if items are modified externally recalculateTotal() { this.total = this.items.reduce( (sum, item) => sum + item.quantity * item.unitPrice, 0 ); } } // Problem: External code can modify items directly function dangerousOperation(order: Order) { // Nothing stops us from doing this: order.items.push(new OrderItem("prod-1", 100, 99.99)); // Order total is now stale // Item limit invariant is bypassed // Credit limit check is skipped }6c:T567,// ❌ Without aggregates: Direct manipulation of internal objects public class OrderItem { private String productId; private int quantity; private BigDecimal unitPrice; // Anyone can change quantity directly public void setQuantity(int quantity) { this.quantity = quantity; // But who updates the order total? // Who checks if we exceeded 10 items? // Who verifies the credit limit? } // Getters and setters exposed... } public class Order { private List items = new ArrayList<>(); // Exposed! private BigDecimal total = BigDecimal.ZERO; // Total can become stale if items are modified externally public List getItems() { return items; // Leaking internal collection! } public void recalculateTotal() { this.total = items.stream() .map(item -> item.getUnitPrice() .multiply(BigDecimal.valueOf(item.getQuantity()))) .reduce(BigDecimal.ZERO, BigDecimal::add); } } // Problem: External code can modify items directly public void dangerousOperation(Order order) { // Nothing stops us from doing this: order.getItems().add(new OrderItem("prod-1", 100, new BigDecimal("99.99"))); // Order total is now stale // Item limit invariant is bypassed // Credit limit check is skipped }6d:Te48,// ✅ With aggregates: All modifications through the root class OrderItem { private constructor( private readonly _productId: string, private _quantity: number, private readonly _unitPrice: number ) {} static create(productId: string, quantity: number, unitPrice: number): OrderItem { if (quantity <= 0) throw new Error("Quantity must be positive"); if (unitPrice < 0) throw new Error("Price cannot be negative"); return new OrderItem(productId, quantity, unitPrice); } get productId(): string { return this._productId; } get quantity(): number { return this._quantity; } get unitPrice(): number { return this._unitPrice; } get total(): number { return this._quantity * this._unitPrice; } // Package-private: Only Order can call this _updateQuantity(quantity: number): void { if (quantity <= 0) throw new Error("Quantity must be positive"); this._quantity = quantity; } } class Order { private readonly _items: Map = new Map(); private readonly MAX_ITEMS = 10; private constructor( private readonly _id: string, private readonly _customerId: string, private readonly _creditLimit: number ) {} static create(id: string, customerId: string, creditLimit: number): Order { return new Order(id, customerId, creditLimit); } // All invariants enforced through this single entry point addItem(productId: string, quantity: number, unitPrice: number): void { // Invariant: Max 10 items if (this._items.size >= this.MAX_ITEMS) { throw new Error(`Order cannot have more than ${this.MAX_ITEMS} items`); } // Invariant: No duplicate products (combine instead) if (this._items.has(productId)) { throw new Error("Product already in order. Use updateItemQuantity instead."); } const item = OrderItem.create(productId, quantity, unitPrice); // Invariant: Total cannot exceed credit limit const newTotal = this.total + item.total; if (newTotal > this._creditLimit) { throw new Error(`Order total ${newTotal} exceeds credit limit ${this._creditLimit}`); } this._items.set(productId, item); } updateItemQuantity(productId: string, newQuantity: number): void { const item = this._items.get(productId); if (!item) throw new Error(`Product ${productId} not in order`); const oldTotal = item.total; const newItemTotal = newQuantity * item.unitPrice; const projectedTotal = this.total - oldTotal + newItemTotal; // Invariant: Total cannot exceed credit limit if (projectedTotal > this._creditLimit) { throw new Error(`Updated total ${projectedTotal} exceeds credit limit`); } item._updateQuantity(newQuantity); } removeItem(productId: string): void { if (!this._items.has(productId)) { throw new Error(`Product ${productId} not in order`); } this._items.delete(productId); } // Invariant: Total always equals sum of items (computed property) get total(): number { let sum = 0; for (const item of this._items.values()) { sum += item.total; } return sum; } get itemCount(): number { return this._items.size; } // Read-only view of items get items(): ReadonlyArray { return Array.from(this._items.values()); } }6e:T1041,// ✅ With aggregates: All modifications through the root public class OrderItem { private final String productId; private int quantity; private final BigDecimal unitPrice; // Package-private constructor - only Order can create items OrderItem(String productId, int quantity, BigDecimal unitPrice) { if (quantity <= 0) throw new IllegalArgumentException("Quantity must be positive"); if (unitPrice.compareTo(BigDecimal.ZERO) < 0) { throw new IllegalArgumentException("Price cannot be negative"); } this.productId = productId; this.quantity = quantity; this.unitPrice = unitPrice; } public String getProductId() { return productId; } public int getQuantity() { return quantity; } public BigDecimal getUnitPrice() { return unitPrice; } public BigDecimal getTotal() { return unitPrice.multiply(BigDecimal.valueOf(quantity)); } // Package-private: Only Order can call this void updateQuantity(int quantity) { if (quantity <= 0) throw new IllegalArgumentException("Quantity must be positive"); this.quantity = quantity; } } public class Order { private static final int MAX_ITEMS = 10; private final String id; private final String customerId; private final BigDecimal creditLimit; private final Map items = new HashMap<>(); public Order(String id, String customerId, BigDecimal creditLimit) { this.id = id; this.customerId = customerId; this.creditLimit = creditLimit; } // All invariants enforced through this single entry point public void addItem(String productId, int quantity, BigDecimal unitPrice) { // Invariant: Max 10 items if (items.size() >= MAX_ITEMS) { throw new IllegalStateException( "Order cannot have more than " + MAX_ITEMS + " items"); } // Invariant: No duplicate products if (items.containsKey(productId)) { throw new IllegalStateException( "Product already in order. Use updateItemQuantity instead."); } OrderItem item = new OrderItem(productId, quantity, unitPrice); // Invariant: Total cannot exceed credit limit BigDecimal newTotal = getTotal().add(item.getTotal()); if (newTotal.compareTo(creditLimit) > 0) { throw new IllegalStateException( "Order total " + newTotal + " exceeds credit limit " + creditLimit); } items.put(productId, item); } public void updateItemQuantity(String productId, int newQuantity) { OrderItem item = items.get(productId); if (item == null) { throw new IllegalArgumentException("Product " + productId + " not in order"); } BigDecimal oldTotal = item.getTotal(); BigDecimal newItemTotal = item.getUnitPrice() .multiply(BigDecimal.valueOf(newQuantity)); BigDecimal projectedTotal = getTotal().subtract(oldTotal).add(newItemTotal); // Invariant: Total cannot exceed credit limit if (projectedTotal.compareTo(creditLimit) > 0) { throw new IllegalStateException( "Updated total " + projectedTotal + " exceeds credit limit"); } item.updateQuantity(newQuantity); } public void removeItem(String productId) { if (!items.containsKey(productId)) { throw new IllegalArgumentException("Product " + productId + " not in order"); } items.remove(productId); } // Invariant: Total always equals sum of items (computed property) public BigDecimal getTotal() { return items.values().stream() .map(OrderItem::getTotal) .reduce(BigDecimal.ZERO, BigDecimal::add); } public int getItemCount() { return items.size(); } // Read-only view of items public List getItems() { return Collections.unmodifiableList(new ArrayList<>(items.values())); } }6f:T221c,// ============================================ // VALUE OBJECTS - Immutable, no identity // ============================================ class Money { private constructor( private readonly _amount: number, private readonly _currency: string ) {} static create(amount: number, currency: string): Money { if (amount < 0) throw new Error("Money cannot be negative"); return new Money(amount, currency); } get amount(): number { return this._amount; } get currency(): string { return this._currency; } add(other: Money): Money { if (this._currency !== other._currency) { throw new Error("Cannot add different currencies"); } return new Money(this._amount + other._amount, this._currency); } multiply(factor: number): Money { return new Money(this._amount * factor, this._currency); } equals(other: Money): boolean { return this._amount === other._amount && this._currency === other._currency; } } class Address { private constructor( private readonly _street: string, private readonly _city: string, private readonly _postalCode: string, private readonly _country: string ) {} static create(street: string, city: string, postalCode: string, country: string): Address { if (!street || !city || !postalCode || !country) { throw new Error("All address fields are required"); } return new Address(street, city, postalCode, country); } // Getters... get street(): string { return this._street; } get city(): string { return this._city; } get postalCode(): string { return this._postalCode; } get country(): string { return this._country; } equals(other: Address): boolean { return this._street === other._street && this._city === other._city && this._postalCode === other._postalCode && this._country === other._country; } } // ============================================ // INTERNAL ENTITY - Local identity only // ============================================ class OrderLine { private _quantity: number; private constructor( private readonly _lineId: string, // Local identity private readonly _productId: string, private readonly _productName: string, private readonly _unitPrice: Money, quantity: number ) { this._quantity = quantity; } static create( lineId: string, productId: string, productName: string, unitPrice: Money, quantity: number ): OrderLine { if (quantity <= 0) throw new Error("Quantity must be positive"); return new OrderLine(lineId, productId, productName, unitPrice, quantity); } get lineId(): string { return this._lineId; } get productId(): string { return this._productId; } get productName(): string { return this._productName; } get quantity(): number { return this._quantity; } get unitPrice(): Money { return this._unitPrice; } get lineTotal(): Money { return this._unitPrice.multiply(this._quantity); } // Package-private for root to call _adjustQuantity(newQuantity: number): void { if (newQuantity <= 0) throw new Error("Quantity must be positive"); this._quantity = newQuantity; } } // ============================================ // AGGREGATE ROOT - Global identity, controls access // ============================================ type OrderStatus = 'draft' | 'confirmed' | 'shipped' | 'delivered' | 'cancelled'; class Order { private readonly _lines: Map = new Map(); private _shippingAddress: Address | null = null; private _status: OrderStatus = 'draft'; private _lineIdCounter = 0; private static readonly MAX_LINES = 20; private static readonly MAX_ORDER_TOTAL = Money.create(10000, 'USD'); private constructor( private readonly _orderId: string, // Global identity private readonly _customerId: string, // Reference to another aggregate private readonly _createdAt: Date ) {} static create(orderId: string, customerId: string): Order { return new Order(orderId, customerId, new Date()); } // ============================================ // INVARIANT-PROTECTING OPERATIONS // ============================================ addLine(productId: string, productName: string, unitPrice: Money, quantity: number): string { this.ensureModifiable(); // Invariant: Max 20 lines if (this._lines.size >= Order.MAX_LINES) { throw new Error(`Order cannot have more than ${Order.MAX_LINES} lines`); } // Create line const lineId = `line-${++this._lineIdCounter}`; const line = OrderLine.create(lineId, productId, productName, unitPrice, quantity); // Invariant: Total cannot exceed maximum const projectedTotal = this.calculateTotal().add(line.lineTotal); if (projectedTotal.amount > Order.MAX_ORDER_TOTAL.amount) { throw new Error(`Order total cannot exceed ${Order.MAX_ORDER_TOTAL.amount}`); } this._lines.set(lineId, line); return lineId; } updateLineQuantity(lineId: string, newQuantity: number): void { this.ensureModifiable(); const line = this._lines.get(lineId); if (!line) throw new Error(`Line ${lineId} not found`); // Calculate projected total const currentLineTotal = line.lineTotal; const newLineTotal = line.unitPrice.multiply(newQuantity); const projectedTotal = this.calculateTotal() .add(newLineTotal) .add(Money.create(-currentLineTotal.amount, currentLineTotal.currency)); // Invariant: Total cannot exceed maximum if (projectedTotal.amount > Order.MAX_ORDER_TOTAL.amount) { throw new Error(`Order total cannot exceed ${Order.MAX_ORDER_TOTAL.amount}`); } line._adjustQuantity(newQuantity); } removeLine(lineId: string): void { this.ensureModifiable(); if (!this._lines.has(lineId)) { throw new Error(`Line ${lineId} not found`); } this._lines.delete(lineId); } setShippingAddress(address: Address): void { this.ensureModifiable(); this._shippingAddress = address; } confirm(): void { // Invariant: Must have at least one line if (this._lines.size === 0) { throw new Error("Cannot confirm order with no items"); } // Invariant: Must have shipping address if (!this._shippingAddress) { throw new Error("Cannot confirm order without shipping address"); } // Invariant: Can only confirm from draft if (this._status !== 'draft') { throw new Error(`Cannot confirm order in ${this._status} status`); } this._status = 'confirmed'; } cancel(): void { // Invariant: Can only cancel draft or confirmed orders if (this._status === 'shipped' || this._status === 'delivered') { throw new Error(`Cannot cancel order in ${this._status} status`); } this._status = 'cancelled'; } // ============================================ // QUERY METHODS (read-only) // ============================================ get orderId(): string { return this._orderId; } get customerId(): string { return this._customerId; } get status(): OrderStatus { return this._status; } get shippingAddress(): Address | null { return this._shippingAddress; } get createdAt(): Date { return new Date(this._createdAt.getTime()); } get lines(): ReadonlyArray { return Array.from(this._lines.values()); } get lineCount(): number { return this._lines.size; } calculateTotal(): Money { let total = Money.create(0, 'USD'); for (const line of this._lines.values()) { total = total.add(line.lineTotal); } return total; } // ============================================ // PRIVATE HELPERS // ============================================ private ensureModifiable(): void { if (this._status !== 'draft') { throw new Error(`Cannot modify order in ${this._status} status`); } } }70:T7be,// ❌ WRONG: Direct object references between aggregates class Order { private customer: Customer; // Direct reference - BAD! private items: OrderItem[]; getCustomerAddress(): Address { // This creates coupling and loading issues return this.customer.getShippingAddress(); } confirmOrder(): void { // What happens if we accidentally modify customer? // Should this save the customer too? this.customer.updateLastOrderDate(new Date()); // Inappropriate! } } // ✅ CORRECT: Reference by identity class Order { private readonly _customerId: string; // ID reference only - GOOD! private readonly _lines: Map = new Map(); // To get customer details, we go through a service or query // This is explicit, not hidden behind object navigation get customerId(): string { return this._customerId; } confirmOrder(): void { // Order only updates its own state // If customer needs updating, that's a separate operation // handled by an application service this._status = 'confirmed'; } } // Application service coordinates across aggregates class OrderConfirmationService { constructor( private orderRepository: OrderRepository, private customerRepository: CustomerRepository, private eventPublisher: EventPublisher ) {} async confirmOrder(orderId: string): Promise { const order = await this.orderRepository.findById(orderId); // Order only manages its own state order.confirm(); await this.orderRepository.save(order); // Customer update is a separate concern, if needed // Could be eventually consistent via events this.eventPublisher.publish(new OrderConfirmedEvent( order.orderId, order.customerId, order.calculateTotal() )); } }71:T940,// ✅ CORRECT: Repository for aggregate root only interface OrderRepository { findById(orderId: string): Promise; save(order: Order): Promise; delete(orderId: string): Promise; // Query methods return aggregate roots findByCustomerId(customerId: string): Promise; findPendingOrders(): Promise; } // ❌ WRONG: No repository for internal entities // This would bypass the aggregate root! interface OrderItemRepository { // DON'T DO THIS findById(itemId: string): Promise; save(item: OrderItem): Promise; } // ✅ Implementation loads/saves entire aggregate atomically class SqlOrderRepository implements OrderRepository { async findById(orderId: string): Promise { // Single query or optimized joins to load entire aggregate const orderData = await this.db.query(` SELECT o.*, ol.* FROM orders o LEFT JOIN order_lines ol ON o.id = ol.order_id WHERE o.id = $1 `, [orderId]); if (!orderData.length) return null; // Reconstitute the complete aggregate return this.mapToAggregate(orderData); } async save(order: Order): Promise { await this.db.transaction(async (tx) => { // Save order root await tx.query(` INSERT INTO orders (id, customer_id, status, shipping_address, created_at) VALUES ($1, $2, $3, $4, $5) ON CONFLICT (id) DO UPDATE SET status = $3, shipping_address = $4 `, [order.orderId, order.customerId, order.status, order.shippingAddress, order.createdAt]); // Delete existing lines and re-insert (simple approach) await tx.query('DELETE FROM order_lines WHERE order_id = $1', [order.orderId]); for (const line of order.lines) { await tx.query(` INSERT INTO order_lines (id, order_id, product_id, product_name, unit_price, quantity) VALUES ($1, $2, $3, $4, $5, $6) `, [line.lineId, order.orderId, line.productId, line.productName, line.unitPrice.amount, line.quantity]); } }); } }62:{"json":{"id":"seed_e1dcbef17c608af8e57d570e02fc9790","slug":"ddd/aggregates","category":"System Design (LLD)","topic":"Domain-Driven Design","title":"Aggregates: Modeling Consistency Boundaries","description":"Master the aggregate pattern in Domain-Driven Design. Learn how to identify aggregate roots, define consistency boundaries, and design aggregates that protect invariants while enabling scalable, maintainable domain models.","difficulty":"ADVANCED","estimatedMinutes":60,"pages":[{"id":"seed_3148e709667fd40fb2ea5d2fedefbf4f","title":"What is an Aggregate","order":0,"content":[{"id":"opening-hook","title":"The Complexity Crisis in Domain Modeling","content":[{"data":{"content":"Picture a real e-commerce system: a customer places an order containing multiple items, each item references a product, the order requires a shipping address, payment information, possibly discount codes, and needs to calculate totals correctly. Now imagine this order is being modified by the customer, processed by a payment gateway, and updated by inventory management—all potentially at the same time.\n\n**How do you ensure the order remains valid throughout all these operations?** How do you prevent partial updates that leave data in an inconsistent state? How do you decide what should be saved together as a unit?\n\nThis is the fundamental challenge that **Aggregates** solve in Domain-Driven Design."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"By the end of this page, you will understand what aggregates are, why they exist, and how they serve as the fundamental unit of consistency and persistence in DDD. You'll learn to see aggregates not as arbitrary groupings, but as carefully designed boundaries that protect the integrity of your domain model.","variant":"info"},"type":"callout"}]},{"id":"from-objects-to-clusters","title":"From Objects to Clusters","content":[{"data":{"content":"In any sufficiently complex domain, objects don't exist in isolation. They form **webs of relationships**—an `Order` contains multiple `OrderItems`, each `OrderItem` references a `Product`, a `Customer` may have multiple `Addresses`, a `ShoppingCart` holds items pending checkout.\n\nWithout careful design, these relationships become a tangled mess where:\n- Everything is connected to everything else\n- Changes ripple unpredictably through the object graph\n- Concurrent modifications cause data corruption\n- It's unclear what to save when persisting changes\n\n**Aggregates are the solution to this chaos.** An aggregate is a cluster of domain objects that are treated as a single unit for the purpose of data changes."},"type":"text"},{"data":{"icon":"Info","title":"The Aggregate Definition","content":"An **Aggregate** is a cluster of associated objects that we treat as a unit for data changes. Each aggregate has a root entity (the Aggregate Root) and a boundary. External objects may only hold references to the root, never to internal entities. All changes to the aggregate pass through the root, which enforces invariants and ensures consistency.","variant":"note"},"type":"callout"},{"data":{"content":"Consider the distinction between objects that **belong together** versus objects that merely **relate to each other**:\n\n- An `Order` and its `OrderItems` belong together—you cannot have an order item without its order, and the order's total depends on its items.\n- An `Order` and a `Product` relate to each other—but products exist independently of any particular order, and many orders can reference the same product.\n\nThe first relationship forms an aggregate; the second is a reference between aggregates."},"type":"text"},{"data":{"height":"450px","mermaidSyntax":"$6a"},"type":"mermaid-excalidraw"}],"titleType":"number","titleNumber":1},{"id":"problem-aggregates-solve","title":"The Problem Aggregates Solve","content":[{"data":{"content":"To appreciate aggregates fully, let's examine the problems they solve. Without aggregates, domain models face three critical challenges:"},"type":"text"},{"data":{"items":["**Invariant Violations** — Business rules that span multiple objects cannot be reliably enforced. For example, 'an order's total must equal the sum of its items' is violated when items are modified without updating the total.","**Concurrency Conflicts** — When multiple processes can modify any object independently, updates conflict unpredictably. Two processes might update different parts of an order, leaving it in an inconsistent state.","**Persistence Ambiguity** — Without clear boundaries, it's unclear what to save. Should saving an order also save the customer? The products? Where does one 'transaction' end and another begin?"],"title":{"icon":"AlertCircle","text":"Problems in Aggregate-less Designs","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"content":"**A concrete example: The Order Total Problem**\n\nConsider an e-commerce order with these invariants:\n- The order total must equal the sum of all item totals\n- Each item total must equal quantity × unit price\n- An order cannot have more than 10 items\n- The order total cannot exceed the customer's credit limit\n\nWithout aggregates, any code can modify an `OrderItem` directly:"},"type":"text"},{"data":{"fileName":"Without Aggregates - Broken Design","languages":[{"code":"$6b","label":"TypeScript","value":"typescript"},{"code":"$6c","label":"Java","value":"java"}],"showLineNumbers":true},"type":"code"},{"data":{"content":"The fundamental issue is **lack of encapsulation at the aggregate level**. When internal objects are directly accessible, invariants cannot be reliably enforced because enforcement logic is bypassed."},"type":"text"}],"titleType":"number","titleNumber":2},{"id":"aggregates-as-gatekeepers","title":"Aggregates as Consistency Gatekeepers","content":[{"data":{"content":"Aggregates solve these problems by establishing a **single point of control** for all modifications. The aggregate root acts as a gatekeeper, ensuring that all changes pass through methods that enforce business rules."},"type":"text"},{"data":{"fileName":"With Aggregates - Protected Design","languages":[{"code":"$6d","label":"TypeScript","value":"typescript"},{"code":"$6e","label":"Java","value":"java"}],"showLineNumbers":true},"type":"code"},{"data":{"icon":"CheckCircle","title":"The Aggregate Guarantee","content":"With proper aggregate design, invariants are enforced by construction. There is no way to violate business rules because violations are structurally impossible—all modifications pass through methods that validate constraints before making changes.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"anatomy-of-aggregate","title":"Anatomy of an Aggregate","content":[{"data":{"content":"Every aggregate consists of three essential parts:\n\n**1. The Aggregate Root (Root Entity)**\n- The only entity that external objects can reference\n- Controls all access to entities within the aggregate\n- Enforces invariants that span multiple entities\n- Has a globally unique identity\n\n**2. Internal Entities**\n- Have identity that is unique only within the aggregate\n- Cannot be accessed directly from outside\n- Their lifecycle is managed by the root\n- May enforce their own local invariants\n\n**3. Value Objects**\n- Immutable objects without identity\n- Describe attributes of entities\n- Can be freely shared and copied"},"type":"text"},{"data":{"rows":[["Aggregate Root","Global (across system)","Publicly referenceable","Independent","Aggregate-wide + local"],["Internal Entity","Local (within aggregate)","Only via root","Tied to root","Local to entity"],["Value Object","None (by value)","Freely sharable","Transient","Self-contained"]],"caption":"Aggregate Component Characteristics","headers":["Component","Identity Scope","Accessibility","Lifecycle","Invariant Scope"]},"type":"table"},{"data":{"content":"Let's examine a more complex aggregate to see these parts in action:"},"type":"text"},{"data":{"fileName":"Complex Aggregate Example","languages":[{"code":"$6f","label":"TypeScript","value":"typescript"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":4},{"id":"boundaries-and-references","title":"Aggregate Boundaries and References","content":[{"data":{"content":"A critical aspect of aggregate design is understanding **what belongs inside versus outside** the aggregate boundary. This determines:\n\n- What is loaded together\n- What is saved together\n- What is protected by the same invariants\n- What can be modified in a single transaction"},"type":"text"},{"data":{"left":[{"data":{"items":["Objects that **cannot exist independently**","Objects with **shared invariants**","Objects that **change together frequently**","Objects with **co-dependent lifecycle**","Example: Order → OrderLines, Car → Wheels"],"title":{"icon":"CheckCircle","text":"Inside the Aggregate","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}],"right":[{"data":{"items":["Objects with **independent lifecycle**","Objects that are **shared across aggregates**","Objects that are **large and expensive to load**","Objects managed by **different teams/contexts**","Example: Order → Product (ref), Order → Customer (ref)"],"title":{"icon":"XCircle","text":"Outside the Aggregate","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"accent"},"type":"list"}]},"type":"two-column"},{"data":{"icon":"AlertCircle","title":"The Reference Rule","content":"Aggregates reference other aggregates **by identity only** (typically the root's ID), never by direct object reference. This prevents one aggregate from modifying another's internals and enables independent loading, saving, and scaling of different aggregates.","variant":"warning"},"type":"callout"},{"data":{"content":"Consider why `Order` references `Customer` by ID rather than embedding:\n\n1. **Independent lifecycle**: A customer exists before, during, and after any particular order\n2. **Sharing**: Multiple orders reference the same customer; embedding would duplicate\n3. **Size**: Loading an order shouldn't load the customer's entire history\n4. **Consistency**: Customer data can change (address, phone) without affecting past orders\n5. **Transactions**: Modifying an order shouldn't lock the customer record"},"type":"text"},{"data":{"fileName":"References Between Aggregates","languages":[{"code":"$70","label":"TypeScript","value":"typescript"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":5},{"id":"persistence-boundary","title":"The Persistence Boundary","content":[{"data":{"content":"One of the most practical benefits of aggregates is that they define the **unit of persistence**. When you save an aggregate, you save the entire cluster atomically; when you load it, you load everything needed to enforce invariants.\n\nThis has profound implications:"},"type":"text"},{"data":{"items":["**One aggregate, one transaction** — A single database transaction should only modify one aggregate. This prevents locking conflicts and enables horizontal scaling.","**Complete loading** — The entire aggregate is loaded when needed, ensuring all invariant checks have the data they need.","**Atomic saving** — All changes to the aggregate are saved together or not at all—no partial updates.","**Clear ownership** — Each aggregate has a single repository responsible for its persistence."],"title":"Aggregates as Transaction Boundaries","variant":"glass"},"type":"list"},{"data":{"icon":"Lightbulb","title":"Smaller is Better","content":"Prefer smaller aggregates over larger ones. A smaller aggregate means less data to load, fewer locking conflicts under concurrency, and faster transactions. If you find yourself with an aggregate that loads 100 objects, reconsider the boundaries. Often what looks like one aggregate should be several smaller ones communicating via references and events.","variant":"tip"},"type":"callout"},{"data":{"content":"**The Repository Pattern and Aggregates**\n\nRepositories should only provide access to aggregate roots, never to internal entities. This enforces the aggregate boundary at the persistence layer:"},"type":"text"},{"data":{"fileName":"Repository Design with Aggregates","languages":[{"code":"$71","label":"TypeScript","value":"typescript"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":6},{"id":"key-takeaways","title":"Key Takeaways","content":[{"data":{"content":"We've covered the fundamental concept of aggregates in Domain-Driven Design. Let's consolidate the essential points:"},"type":"text"},{"data":{"type":"ordered","items":["**Aggregates are clusters of objects** treated as a unit for data changes, defining both consistency and persistence boundaries.","**The Aggregate Root** is the only entry point—all modifications go through it, ensuring invariants are enforced.","**Internal entities** have local identity and are managed entirely by the root; they're invisible to the outside world.","**Value objects** provide immutable, identity-less attributes that can be freely shared.","**Cross-aggregate references** use IDs only, never direct object references, enabling independence and scalability.","**One transaction, one aggregate** is the goal—keep aggregates small to minimize locking and maximize concurrency."],"title":{"icon":"CheckCircle","text":"Core Concepts","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's Next:**\n\nIn the next page, we'll dive deeper into the **Aggregate Root** pattern—understanding how to identify the right root, what responsibilities it should carry, and how to design root interfaces that are both expressive and protective of invariants."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now understand what aggregates are and why they're essential to DDD. Aggregates solve the fundamental problem of maintaining consistency in complex domain models by establishing clear boundaries, single points of control, and well-defined units of persistence. Next, we'll explore the Aggregate Root pattern in detail.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":7}],"isLocked":false},{"id":"seed_726524a7d3c9fd7da64b8268dd7a3e72","title":"Aggregate Root","order":1,"content":null,"isLocked":true},{"id":"seed_ab5718a0914db62bb0b8a99dc07142b0","title":"Consistency Boundaries","order":2,"content":null,"isLocked":true},{"id":"seed_67fabcb0b7542b07a84fa5fbabf40bc5","title":"Aggregate Design Rules","order":3,"content":null,"isLocked":true}]}}