Aggregate and Aggregate Root in DDD

The problem aggregates solve

Domain models without explicit consistency boundaries develop two pathologies:

1. 1
   Inconsistent state — two requests both read an order, both add a line, both save; one overwrites; total no longer matches items
2. 2
   Lock contention — a Customer god-object containing all orders/addresses/payments becomes contention hotspot; every order-placement locks the whole customer

Aggregates fix both:

• Aggregate is a small cluster (entities + value objects) that change together
• Aggregate root is the entrance — external code holds reference only to the root
• One transaction modifies one aggregate; multi-aggregate consistency is eventual
• Invariants spanning the aggregate enforced inside the root

Anatomy

Order aggregate: Order (root), OrderItems, ShippingInfo, PaymentMethod (VO). External code only allowed to touch Order. Internal entities reachable only through root. References to other aggregates (Customer, Product) by ID, not by object.

Code example

Order class with OrderId, CustomerId (by ID), List, status, total, version. Constructor validates 'order needs items'. addItem(productId, qty, unitPrice) checks status, adds item, recomputes total — invariant 'total = sum of items' structurally impossible to violate. items() returns List.copyOf(items) — callers can't mutate internal list.

OrderItem created only through Order.addItem(); no external new OrderItem reachable.

The four rules

Rule 1: Reference other aggregates by ID, not object. private CustomerId, not private Customer. Object reference triggers lazy load, hidden joins, hidden contention.

Rule 2: One transaction, one aggregate. Multi-aggregate updates across transactions, coordinated via domain events and eventual consistency. Don't change customer.recordOrder(order) and orderRepo.save(order) in same transaction — publish OrderPlacedEvent; customer updates in a separate transaction.

Rule 3: Aggregates should be small. Customer with 5000 orders inside = contention, heavy loads, memory pressure. If thousands of internal entities, too big.

Rule 4: All invariants that must hold transactionally live inside one aggregate. 'Order total = sum of items' must always be true → items inside order aggregate. 'Customer max 3 active orders' → either model inside customer or relax to eventually consistent (preferable).

Optimistic locking on the root

@Version on root. JPA increments version on UPDATE, adds WHERE version = ?. Concurrent updates: second sees 0 rows updated → OptimisticLockException. Use case retries or returns 409 Conflict.

Works at aggregate level: root carries version; updating any internal entity bumps root's version. Concurrency detected at consistency-boundary level, not per-row — matches design intent.

Aggregates and repositories

One repository per aggregate. Deals with root only. OrderRepository.save(order), findById(orderId), findActiveByCustomerId(customerId).

Anti-pattern: OrderRepository + OrderItemRepository + ShippingInfoRepository. Fragments the aggregate, leaks persistence model upward, makes use case orchestrate four saves for one logical change.

Right: orderRepo.save(order) persists root + internal entities atomically. Persistence adapter handles multi-table mapping internally.

Cross-aggregate consistency — domain events

Order.submit() raises OrderSubmittedEvent. Use case publishes events after persistence. Other aggregate consumes in its own transaction (Customer.recordOrder).

Eventually consistent. Brief window where Order submitted but Customer hasn't recorded. For reliable delivery: transactional outbox — events written to outbox table in same transaction; background process publishes from outbox to Kafka.

Common mistakes

• Object references to other aggregates — hidden joins/lazy loads/contention
• Multiple aggregates in one transaction — breaks boundary
• Huge aggregates — contention and load explode
• Externally constructing internal entities — breaks invariant enforcement
• No optimistic lock — last-write-wins corruption
• Returning mutable internal collections — callers bypass Order.addItem; use defensive copies
• Repository per JPA entity — fragments aggregate
• Trying to enforce all invariants transactionally — some are inherently cross-aggregate (uniqueness across all customers); model as eventual

Recommendation

Design aggregates as small consistency boundaries: the root is the only external entry point, internal entities are reachable only through the root, references to other aggregates are by ID, and one transaction modifies one aggregate. Use optimistic locking (@Version) on the root, one repository per aggregate that persists root and internals atomically, and domain events plus transactional outbox for cross-aggregate consistency. Keep aggregates small — if you find yourself loading thousands of internal entities or contending on a single root, the aggregate is too big and needs splitting.