Aggregate Design — Deep Dive

graph TD
    subgraph Order Aggregate
        AR[Order - Aggregate Root]
        E1[OrderLine - Entity]
        E2[OrderLine - Entity]
        VO1[ShippingAddress - Value Object]
        VO2[OrderStatus - Value Object]
    end
    AR --> E1
    AR --> E2
    AR --> VO1
    AR --> VO2
    EXT[External Code] --> AR
    EXT -.->|NOT ALLOWED| E1

// WRONG: Direct access to internal entity
OrderLine line = orderLineRepository.findById(lineId);
line.setQuantity(5);

// RIGHT: Access through aggregate root
Order order = orderRepository.findById(orderId);
order.updateLineQuantity(lineId, 5);  // Root enforces invariants

// WRONG: Modify two aggregates in one transaction
@Transactional
public void placeOrder(Order order, Inventory inventory) {
    order.place();
    inventory.reserve(order.getItems());  // Two aggregates
    // If inventory fails, order is rolled back — tight coupling
}

// RIGHT: Single aggregate per transaction; use events
@Transactional
public void placeOrder(Order order) {
    order.place();  // Raises OrderPlaced event
    orderRepository.save(order);
}

// Another service handles InventoryReserved via event
@EventListener
public void onOrderPlaced(OrderPlaced event) {
    Inventory inventory = inventoryRepository.findByWarehouse(warehouseId);
    inventory.reserve(event.getItems());
    inventoryRepository.save(inventory);
}

// WRONG: Object reference to another aggregate
public class Order {
    private Customer customer;  // Object reference
}

// RIGHT: ID reference
public class Order {
    private CustomerId customerId;  // ID only
}

graph TD
    subgraph Too Large
        A[Order Root]
        A --> B[Lines]
        A --> C[Payments]
        A --> D[Shipments]
        A --> E[Returns]
        A --> F[Customer]
        A --> G[Reviews]
    end

graph TD
    subgraph Right Size
        O[Order] --> OL[OrderLines]
        P[Payment] --> PI[PaymentItems]
        S[Shipment] --> SI[ShipmentItems]
    end
    O -->|ID| P
    O -->|ID| S

sequenceDiagram
    participant OA as Order Aggregate
    participant EB as Event Bus
    participant IA as Inventory Aggregate
    participant PA as Payment Aggregate

    OA->>OA: order.place()
    OA->>EB: OrderPlaced event
    EB->>IA: Handle OrderPlaced
    IA->>IA: inventory.reserve()
    IA->>EB: InventoryReserved event
    EB->>PA: Handle InventoryReserved
    PA->>PA: payment.charge()

public interface OrderRepository {
    Optional<Order> findById(OrderId id);
    void save(Order order);
}

// NOT one repository per entity
// OrderLineRepository — WRONG

// Load complete
Order order = orderRepository.findById(id);  // Includes all OrderLines

// NOT piecemeal
Order order = orderRepository.findById(id);
order.getLines();  // Lazy load — can cause consistency issues

graph TD
    subgraph Order Aggregate v1
        O[Order]
        O --> L[OrderLines]
        O --> P[Payment]
        O --> S[Shipment]
        O --> R[Returns]
        O --> I[Invoice]
    end

graph TD
    subgraph Order Aggregate
        O[Order]
        O --> L[OrderLines]
        O --> SA[ShippingAddress]
    end
    subgraph Payment Aggregate
        P[Payment]
        P --> PI[PaymentAttempts]
    end
    subgraph Shipment Aggregate
        S[Shipment]
        S --> SI[ShipmentItems]
        S --> T[TrackingInfo]
    end
    O -->|orderId| P
    O -->|orderId| S