domain-driven-design

Domain Driven Design

Use When

• Modeling aggregates, value objects, and domain events in Spring Boot
• Spring Boot code generation or refactor where agent defaults would be wrong

Workflow

1. Confirm the change matches this skill's domain triggers before coding.
2. Follow the domain guide conventions and gotchas below — not generic Spring Boot defaults.
3. Apply project-specific response envelopes, DTO boundaries, and dependency injection rules.
4. Validate with targeted tests (slice, integration, or contract as appropriate).
5. Capture evidence before merge: tests, migration notes, or observability proof.

Required Checks

• Constructor injection used; no @Autowired field injection on new code
• Controllers return DTOs/envelopes — never raw JPA entities
• Business logic stays in @Service layer, not controllers or repositories
• Error handling uses project-standard envelope or RFC 9457 ProblemDetail

Domain Guide

Aggregate Rules

• One repository per aggregate root
• External code only accesses aggregate through root — never child entities directly
• Aggregates reference other aggregates by ID only, not direct object reference
• Keep aggregates small — if it has more than 3-4 child entities, split it

// ✅ Aggregate root controls all access to children
order.addItem(productId, quantity); // through root
order.removeItem(itemId);           // through root

// ❌ Direct child access from outside
order.getItems().add(new OrderItem(...)); // bypasses invariants

Value Objects

Immutable, no identity, equality by value:

public record Money(BigDecimal amount, Currency currency) {
    public Money {
        if (amount.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Amount cannot be negative");
        Objects.requireNonNull(currency);
    }

    public Money add(Money other) {
        if (!currency.equals(other.currency))
            throw new CurrencyMismatchException(currency, other.currency);
        return new Money(amount.add(other.amount), currency);
    }

    public static Money of(String amount, String currency) {
        return new Money(new BigDecimal(amount), Currency.getInstance(currency));
    }
}

public record EmailAddress(String value) {
    public EmailAddress {
        if (!value.matches("^[\\w.-]+@[\\w.-]+\\.[a-z]{2,}$"))
            throw new InvalidEmailException(value);
    }
}