Domain-Driven Design (DDD): Strategic & Tactical Patterns

❌ Without ubiquitous language:
- Domain expert says: "approved application"
- Developer writes: `request.setStatus("A")`
- Database has: `app_status_cd = 2`
 
✅ With ubiquitous language:
- Domain expert says: "approved application"
- Developer writes: `application.approve()`
- Database has: `status = 'APPROVED'`

public class Customer {
    private final CustomerId id;  // Identity
    private String name;
    private Email email;
    private CustomerStatus status;
 
    public void activate() {
        if (this.status == CustomerStatus.SUSPENDED) {
            throw new IllegalStateException("Cannot activate suspended customer");
        }
        this.status = CustomerStatus.ACTIVE;
    }
 
    public void suspend(String reason) {
        this.status = CustomerStatus.SUSPENDED;
        // Record domain event
    }
 
    // Identity-based equality
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Customer)) return false;
        return id.equals(((Customer) o).id);
    }
 
    @Override
    public int hashCode() {
        return id.hashCode();
    }
}

// Value object — defined by its attributes
public record Money(BigDecimal amount, Currency currency) {
 
    public Money {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Amount must be non-negative");
        }
        Objects.requireNonNull(currency, "Currency is required");
    }
 
    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Cannot add different currencies");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }
 
    public Money multiply(int quantity) {
        return new Money(this.amount.multiply(BigDecimal.valueOf(quantity)), this.currency);
    }
}
 
// Usage
Money price = new Money(new BigDecimal("29.99"), Currency.USD);
Money total = price.multiply(3);  // $89.97

// Another value object — Email
public record Email(String value) {
 
    public Email {
        if (value == null || !value.matches("^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$")) {
            throw new IllegalArgumentException("Invalid email: " + value);
        }
    }
}
 
// Another value object — Address
public record Address(String street, String city, String state, String zipCode, String country) {
 
    public Address {
        Objects.requireNonNull(street, "Street is required");
        Objects.requireNonNull(city, "City is required");
        Objects.requireNonNull(country, "Country is required");
    }
}

// Order is the Aggregate Root
public class Order {
    private final OrderId id;
    private final CustomerId customerId;
    private OrderStatus status;
    private final List<OrderItem> items;  // Entities inside aggregate
    private ShippingAddress shippingAddress;  // Value object
    private Money totalAmount;  // Value object
 
    // Factory method — enforces invariants at creation
    public static Order place(CustomerId customerId, List<OrderItem> items,
                               ShippingAddress address) {
        if (items == null || items.isEmpty()) {
            throw new IllegalArgumentException("Order must have at least one item");
        }
        Order order = new Order();
        order.id = OrderId.generate();
        order.customerId = customerId;
        order.status = OrderStatus.PLACED;
        order.items = new ArrayList<>(items);
        order.shippingAddress = address;
        order.totalAmount = calculateTotal(items);
        return order;
    }
 
    // Business method — encapsulates domain logic
    public void addItem(ProductId productId, String productName,
                        Money price, int quantity) {
        if (status != OrderStatus.PLACED) {
            throw new IllegalStateException("Cannot modify confirmed order");
        }
        OrderItem item = new OrderItem(productId, productName, price, quantity);
        items.add(item);
        recalculateTotal();
    }
 
    public void removeItem(ProductId productId) {
        if (status != OrderStatus.PLACED) {
            throw new IllegalStateException("Cannot modify confirmed order");
        }
        items.removeIf(item -> item.getProductId().equals(productId));
        if (items.isEmpty()) {
            throw new IllegalStateException("Order must have at least one item");
        }
        recalculateTotal();
    }
 
    public void confirm() {
        if (status != OrderStatus.PLACED) {
            throw new IllegalStateException("Can only confirm PLACED orders");
        }
        status = OrderStatus.CONFIRMED;
    }
 
    public void ship(String trackingNumber) {
        if (status != OrderStatus.CONFIRMED) {
            throw new IllegalStateException("Can only ship CONFIRMED orders");
        }
        status = OrderStatus.SHIPPED;
    }
 
    // Internal consistency — always valid
    private void recalculateTotal() {
        this.totalAmount = items.stream()
            .map(OrderItem::subtotal)
            .reduce(Money.ZERO_USD, Money::add);
    }
 
    // Read-only access to internal entities
    public List<OrderItem> getItems() {
        return Collections.unmodifiableList(items);
    }
}

// ❌ Large aggregate — loads everything
public class Customer {
    private List<Order> orders;        // Could be thousands!
    private List<Address> addresses;
    private List<PaymentMethod> payments;
    private LoyaltyAccount loyalty;
}
 
// ✅ Small aggregates — reference by ID
public class Customer {
    private CustomerId id;
    private String name;
    private Email email;
    // Orders, addresses, payments are separate aggregates
}
 
public class Order {
    private OrderId id;
    private CustomerId customerId;  // Reference by ID, not by object
    private List<OrderItem> items;
}

// ❌ Updating multiple aggregates in one transaction
@Transactional
public void placeOrder(PlaceOrderCommand cmd) {
    Order order = Order.place(...);
    orderRepo.save(order);
 
    Inventory inventory = inventoryRepo.findByProductId(cmd.productId());
    inventory.reserve(cmd.quantity());  // Different aggregate!
    inventoryRepo.save(inventory);
}
 
// ✅ One aggregate per transaction + domain event
@Transactional
public void placeOrder(PlaceOrderCommand cmd) {
    Order order = Order.place(...);
    orderRepo.save(order);
    eventPublisher.publish(new OrderPlacedEvent(order.getId(), order.getItems()));
}
 
// Separate handler updates inventory
@EventHandler
public void onOrderPlaced(OrderPlacedEvent event) {
    for (OrderItemData item : event.getItems()) {
        Inventory inventory = inventoryRepo.findByProductId(item.productId());
        inventory.reserve(item.quantity());
        inventoryRepo.save(inventory);
    }
}

// Repository interface — defined in the domain layer
public interface OrderRepository {
    OrderId nextId();
    Order findById(OrderId id);
    List<Order> findByCustomerId(CustomerId customerId);
    void save(Order order);
    void delete(OrderId id);
}

// Domain event — immutable, past tense
public record OrderPlacedEvent(
    OrderId orderId,
    CustomerId customerId,
    Money totalAmount,
    List<OrderItemData> items,
    Instant occurredAt
) implements DomainEvent {
 
    public OrderPlacedEvent(OrderId orderId, CustomerId customerId,
                             Money totalAmount, List<OrderItemData> items) {
        this(orderId, customerId, totalAmount, items, Instant.now());
    }
}
 
public record OrderShippedEvent(
    OrderId orderId,
    String trackingNumber,
    Instant occurredAt
) implements DomainEvent {}
 
public record OrderCancelledEvent(
    OrderId orderId,
    String reason,
    Instant occurredAt
) implements DomainEvent {}

// Domain service — business logic that spans aggregates
public class PricingService {
 
    public Money calculateOrderTotal(List<OrderItem> items,
                                      DiscountPolicy discountPolicy,
                                      TaxPolicy taxPolicy) {
        Money subtotal = items.stream()
            .map(OrderItem::subtotal)
            .reduce(Money.ZERO_USD, Money::add);
 
        Money afterDiscount = discountPolicy.apply(subtotal);
        Money withTax = taxPolicy.apply(afterDiscount);
        return withTax;
    }
}
 
// Domain service — transfer money between accounts
public class TransferService {
 
    public void transfer(Account from, Account to, Money amount) {
        if (!from.hasBalance(amount)) {
            throw new InsufficientBalanceException(from.getId(), amount);
        }
        from.debit(amount);
        to.credit(amount);
    }
}

// Anti-corruption layer — translates legacy model to your domain model
public class LegacyCustomerAdapter implements CustomerInfoProvider {
 
    private final LegacyCustomerApiClient legacyClient;
 
    @Override
    public CustomerProfile getProfile(CustomerId customerId) {
        // Call legacy API with its own terminology
        LegacyCustRecord record = legacyClient.getCustByAcctNbr(
            customerId.value()
        );
 
        // Translate to your domain model
        return new CustomerProfile(
            new CustomerId(record.getAcctNbr()),
            record.getFirstNm() + " " + record.getLastNm(),
            new Email(record.getEmailAddr()),
            mapLegacyTier(record.getCustTierCd())  // "G" → GOLD
        );
    }
 
    private CustomerTier mapLegacyTier(String legacyCode) {
        return switch (legacyCode) {
            case "G" -> CustomerTier.GOLD;
            case "S" -> CustomerTier.SILVER;
            case "B" -> CustomerTier.BRONZE;
            default -> CustomerTier.STANDARD;
        };
    }
}

[Order Placed] → [Payment Received] → [Inventory Reserved] → [Order Shipped] → [Order Delivered]

{Place Order} → [Order Placed]
{Process Payment} → [Payment Received]
{Reserve Inventory} → [Inventory Reserved]
{Ship Order} → [Order Shipped]

// === Value Objects ===
 
public record OrderId(String value) {
    public static OrderId generate() {
        return new OrderId(UUID.randomUUID().toString());
    }
}
 
public record CustomerId(String value) {}
 
public record ProductId(String value) {}
 
public record Money(BigDecimal amount, String currency) {
    public static final Money ZERO_USD = new Money(BigDecimal.ZERO, "USD");
 
    public Money add(Money other) {
        return new Money(amount.add(other.amount), currency);
    }
 
    public Money multiply(int qty) {
        return new Money(amount.multiply(BigDecimal.valueOf(qty)), currency);
    }
}
 
// === Entities ===
 
public class OrderItem {
    private final ProductId productId;
    private final String productName;
    private final Money unitPrice;
    private int quantity;
 
    public Money subtotal() {
        return unitPrice.multiply(quantity);
    }
 
    public void increaseQuantity(int additional) {
        if (additional <= 0) throw new IllegalArgumentException("Must be positive");
        this.quantity += additional;
    }
}
 
// === Aggregate Root ===
 
public class Order {
    private final OrderId id;
    private final CustomerId customerId;
    private OrderStatus status;
    private List<OrderItem> items;
    private ShippingAddress shippingAddress;
    private Money totalAmount;
    private final List<DomainEvent> domainEvents = new ArrayList<>();
 
    public static Order place(CustomerId customerId, List<OrderItem> items,
                               ShippingAddress address) {
        if (items.isEmpty()) {
            throw new EmptyOrderException();
        }
 
        Order order = new Order(OrderId.generate(), customerId,
            OrderStatus.PLACED, items, address);
        order.recalculateTotal();
 
        // Register domain event
        order.domainEvents.add(new OrderPlacedEvent(
            order.id, customerId, order.totalAmount, order.getItemData()
        ));
        return order;
    }
 
    public void confirm(PaymentId paymentId) {
        if (status != OrderStatus.PLACED) {
            throw new InvalidOrderStateException(id, status, "confirm");
        }
        this.status = OrderStatus.CONFIRMED;
        domainEvents.add(new OrderConfirmedEvent(id, paymentId));
    }
 
    public void ship(String trackingNumber) {
        if (status != OrderStatus.CONFIRMED) {
            throw new InvalidOrderStateException(id, status, "ship");
        }
        this.status = OrderStatus.SHIPPED;
        domainEvents.add(new OrderShippedEvent(id, trackingNumber));
    }
 
    public void cancel(String reason) {
        if (status == OrderStatus.SHIPPED || status == OrderStatus.DELIVERED) {
            throw new InvalidOrderStateException(id, status, "cancel");
        }
        this.status = OrderStatus.CANCELLED;
        domainEvents.add(new OrderCancelledEvent(id, reason));
    }
 
    // Collect and clear domain events
    public List<DomainEvent> pullDomainEvents() {
        List<DomainEvent> events = new ArrayList<>(domainEvents);
        domainEvents.clear();
        return events;
    }
}

// Application service — orchestrates domain objects and ports
public class PlaceOrderUseCase {
 
    private final OrderRepository orderRepository;
    private final ProductCatalogPort productCatalog;
    private final EventPublisher eventPublisher;
 
    public PlaceOrderUseCase(OrderRepository orderRepository,
                              ProductCatalogPort productCatalog,
                              EventPublisher eventPublisher) {
        this.orderRepository = orderRepository;
        this.productCatalog = productCatalog;
        this.eventPublisher = eventPublisher;
    }
 
    public OrderId execute(PlaceOrderCommand command) {
        // Validate products exist and get current prices
        List<OrderItem> items = command.items().stream()
            .map(item -> {
                ProductInfo product = productCatalog.getProduct(item.productId());
                return new OrderItem(
                    product.id(), product.name(), product.price(), item.quantity()
                );
            })
            .toList();
 
        ShippingAddress address = new ShippingAddress(
            command.street(), command.city(), command.state(),
            command.zipCode(), command.country()
        );
 
        // Create aggregate — business rules enforced inside
        Order order = Order.place(
            new CustomerId(command.customerId()), items, address
        );
 
        // Persist
        orderRepository.save(order);
 
        // Publish domain events
        order.pullDomainEvents().forEach(eventPublisher::publish);
 
        return order.getId();
    }
}

src/main/java/com/example/ordering/
├── domain/                              # Domain Layer
│   ├── model/
│   │   ├── Order.java                   # Aggregate root
│   │   ├── OrderItem.java               # Entity
│   │   ├── OrderStatus.java             # Enum
│   │   ├── OrderId.java                 # Value object
│   │   ├── CustomerId.java              # Value object
│   │   ├── Money.java                   # Value object
│   │   ├── ShippingAddress.java         # Value object
│   │   └── ProductId.java               # Value object
│   ├── event/
│   │   ├── DomainEvent.java             # Base interface
│   │   ├── OrderPlacedEvent.java
│   │   ├── OrderConfirmedEvent.java
│   │   ├── OrderShippedEvent.java
│   │   └── OrderCancelledEvent.java
│   ├── exception/
│   │   ├── EmptyOrderException.java
│   │   └── InvalidOrderStateException.java
│   ├── port/
│   │   ├── OrderRepository.java         # Driven port
│   │   ├── ProductCatalogPort.java      # Driven port
│   │   └── EventPublisher.java          # Driven port
│   └── service/
│       └── PricingService.java          # Domain service
│
├── application/                         # Application Layer
│   ├── PlaceOrderUseCase.java
│   ├── ConfirmOrderUseCase.java
│   ├── CancelOrderUseCase.java
│   └── command/
│       ├── PlaceOrderCommand.java
│       └── CancelOrderCommand.java
│
├── infrastructure/                      # Infrastructure Layer
│   ├── persistence/
│   │   ├── OrderJpaEntity.java
│   │   ├── OrderJpaRepository.java
│   │   └── OrderRepositoryImpl.java
│   ├── messaging/
│   │   └── KafkaEventPublisher.java
│   ├── rest/
│   │   ├── OrderController.java
│   │   └── dto/
│   │       ├── PlaceOrderRequest.java
│   │       └── OrderResponse.java
│   └── external/
│       └── CatalogServiceClient.java    # ACL for catalog context

// ❌ Anemic — entity is just a data bag
public class Order {
    private String status;
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
}
 
// Service does all the work
public class OrderService {
    public void confirmOrder(Order order) {
        if (!order.getStatus().equals("PLACED")) {
            throw new RuntimeException("Invalid state");
        }
        order.setStatus("CONFIRMED");
    }
}

// ✅ Rich domain model — entity owns its behavior
public class Order {
    private OrderStatus status;
 
    public void confirm() {
        if (status != OrderStatus.PLACED) {
            throw new InvalidOrderStateException(id, status, "confirm");
        }
        this.status = OrderStatus.CONFIRMED;
    }
}

// ❌ Too large — loads everything, locks too much
public class Customer {
    private List<Order> orders;         // Could be 10,000+
    private List<Review> reviews;       // Unnecessary coupling
    private ShoppingCart cart;
    private WishList wishList;
    private LoyaltyAccount loyalty;
}

// ✅ Small, focused aggregates connected by ID
public class Customer {
    private CustomerId id;
    private String name;
    private Email email;
}
 
public class Order {
    private OrderId id;
    private CustomerId customerId;  // Reference by ID
}
 
public class ShoppingCart {
    private CartId id;
    private CustomerId customerId;  // Reference by ID
}

// ❌ Shared "Product" used in catalog, pricing, and inventory
public class Product {
    private String name;
    private String description;     // Catalog
    private BigDecimal price;       // Pricing
    private List<Discount> discounts; // Pricing
    private int stockQuantity;      // Inventory
    private String warehouseLocation; // Inventory
    // God class — everyone changes it
}

// ✅ Each context has its own model
// Catalog context
public class CatalogProduct {
    private ProductId id;
    private String name;
    private String description;
    private List<String> images;
}
 
// Pricing context
public class PricedItem {
    private ProductId productId;
    private Money basePrice;
    private List<DiscountRule> applicableDiscounts;
}
 
// Inventory context
public class StockItem {
    private ProductId productId;
    private int quantity;
    private String warehouseId;
    private int reorderLevel;
}