In this guide (24 items)

Domain-Driven Design

Domain-Driven Design (DDD)

MANDATORY FOR ALL AI AGENTS: Every domain entity, value object, and aggregate MUST follow the DDD building blocks described here. Domain classes MUST NOT have framework annotations (no Spring, no JPA, no Kafka). Business logic MUST reside in domain entities, NOT in use cases or adapters. Use cases orchestrate domain entities but do NOT contain business rules.

1. General Concept

Domain-Driven Design (DDD) is a software design methodology focused on the business domain. Its goal is to align the technical model with business knowledge and rules, fostering close collaboration between developers and domain experts.

DDD promotes a shared understanding of the domain through a common language (Ubiquitous Language) and structures the software around business concepts rather than technical concerns.

2. Key Components

Concept	Description
Domain	Core business knowledge and rules.
Ubiquitous Language	Shared language between business and development teams.
Model	Representation of the domain through entities, values, and services.
Bounded Context	Boundary within which a domain model is valid and consistent.
Context Map	Map of relationships between different bounded contexts.

3. Bounded Context

A Bounded Context defines the boundaries within which a domain model is valid. Inside this boundary, terms, rules, and behaviors have a consistent meaning.

Each context can have its own model, database, and API, communicating with others through explicit contracts. In a microservices architecture, each microservice typically corresponds to a bounded context.

Rules:

DO NOT share domain models across bounded contexts.
Use Anticorruption Layers (ACL) when integrating with external contexts.
Define explicit contracts (events, APIs) for inter-context communication.

4. Context Map Patterns

Pattern	Description
Shared Kernel	Two contexts share a small common submodel.
Customer-Supplier	One context depends on and may influence another.
Conformist	The consumer adopts the provider’s model as-is.
Anticorruption Layer (ACL)	Translates models to avoid semantic contamination.
Open Host Service (OHS)	Public, standard API for multiple consumers.
Published Language	Shared language for interoperability (e.g., JSON Schema, Avro).
Separate Ways	Contexts evolve independently without integration.
Partnership	Two contexts evolve together in cooperation.

5. Building Blocks

Concept	Description	Example
Entity	Object with persistent identity.	`Organization`, `User`
Value Object	Immutable object without identity.	`Money`, `Address`, `Email`
Aggregate	Cohesive cluster of an entity root plus member entities/value objects, mutated only through the root.	`Order` (root) + `OrderItem` (member entity) + `Money` (VO)
Repository	Persistence abstraction for aggregates.	`OrganizationRepositoryPort`
Service (Domain Service)	Domain logic that does not naturally belong to an entity.	`PricingService`
Domain Event	Significant occurrence within the domain.	`OrganizationCreated`, `UserEnabled`
Factory	Encapsulates aggregate creation. Prefer a factory method on the aggregate (`companion object` / `static create`); reserve a separate `Factory` class for creation that spans multiple aggregates.	`Organization.create(...)`, `OrderFactory`
Command	Immutable intention object — Kotlin `data class`, Java `record`. Lives in the application layer.	`CreateOrganizationCommand`

6. Layers in DDD

This project maps DDD onto its real hexagonal convention (four modules, not the classic UI/API split):

domain – pure logic, no framework deps, immutable. Entities, value objects, core business rules.
application – use cases + ports, depends on domain only, no annotations. Orchestrates use cases and transactions. Contains NO business logic.
infrastructure – adapters. INCLUDES ALL entry-points (REST controllers, Kafka/RabbitMQ consumers, schedulers, CLI) as inbound adapters, plus the outbound adapters (DB, queues, HTTP clients). There is NO separate “User Interface” or “API Layer”.
bootstrap – wiring Spring, deps de todos los módulos. No business logic.

Every entry-point (API/REST/messaging) is an inbound adapter inside infrastructure — NOT a separate layer.

Dependency rule: Dependencies MUST point inward. Domain depends on nothing. Application depends on Domain. Infrastructure depends on Application and Domain.

Mapping to this project’s hexagonal modules: UI/API + Infrastructure → infrastructure/ (adapters); Application → application/ (use cases and ports — the repository port is here, the adapter is in infrastructure/); Domain → domain/. Spring wiring lives in bootstrap/, which depends on all modules but contains no business logic. See hexagonal-architecture.md.

7. Benefits

Aligns software with business needs.
Improves communication between teams via Ubiquitous Language.
Enables easier evolution and maintenance.
Encourages autonomy per bounded context.
Reduces coupling between domains.

8. Example Diagram (Mermaid)

1
graph TD
2
    A[Catalog Context] -->|Published Language| B[Shopping Cart Context]
3
    B -->|Customer-Supplier| C[Billing Context]
4
    C -->|Anticorruption Layer| D[CRM Context]
5
    D -->|Partnership| E[Customer Support]
6
    E -->|Shared Kernel| C
7
    F[Reporting Context] -->|Conformist| C
8
    G[Inventory Context] -->|Separate Ways| A

9. Practical Example: Order and Payment Aggregates

Java:

1
// Domain: Orders (Aggregate Root) — immutable. All fields final, ctor private,
2
// transitions return new instances. The total invariant (sum of subtotals)
3
// is enforced in the constructor; addItem rebuilds the aggregate consistently.
4
public final class Order {
5
    private final UUID id;
6
    private final List<OrderItem> items;
7
    private final Money total;
8
    private final long version;
9

10
    private Order(UUID id, List<OrderItem> items, Money total, long version) {
11
        Money recomputed = items.stream()
12
                .map(OrderItem::getSubtotal)
13
                .reduce(Money.ZERO, Money::add);
14
        if (!total.equals(recomputed)) {
15
            throw new IllegalArgumentException("Order.total must equal sum of item subtotals");
16
        }
17
        if (version < 0) throw new IllegalArgumentException("version must be non-negative");
18
        this.id = id;
19
        this.items = List.copyOf(items);
20
        this.total = total;
21
        this.version = version;
22
    }
23

24
    public static Order create(UUID id) {
25
        return new Order(id, List.of(), Money.ZERO, 0L);
26
    }
27

28
    public static Order rehydrate(UUID id, List<OrderItem> items, Money total, long version) {
29
        return new Order(id, items, total, version);
30
    }
31

32
    public Order addItem(OrderItem item) {
33
        List<OrderItem> updated = new ArrayList<>(items.size() + 1);
34
        updated.addAll(items);
35
        updated.add(item);
36
        Money newTotal = updated.stream()
37
                .map(OrderItem::getSubtotal)
38
                .reduce(Money.ZERO, Money::add);
39
        return new Order(id, updated, newTotal, version + 1);
40
    }
41

42
    public UUID getId()              { return id; }
43
    public List<OrderItem> getItems(){ return items; }  // already unmodifiable
44
    public Money getTotal()          { return total; }
45
    public long getVersion()         { return version; }
46
}
47

48
// Domain: Payments (Aggregate Root) — immutable, intention-revealing transitions.
49
public final class Payment {
50
    private final UUID id;
51
    private final UUID orderId;
52
    private final Money amount;
53
    private final PaymentStatus status;
54
    private final long version;
55

56
    private Payment(UUID id, UUID orderId, Money amount, PaymentStatus status, long version) {
57
        this.id = id;
58
        this.orderId = orderId;
59
        this.amount = amount;
60
        this.status = status;
61
        this.version = version;
62
    }
63

64
    public static Payment request(UUID id, UUID orderId, Money amount) {
65
        return new Payment(id, orderId, amount, PaymentStatus.PENDING, 0L);
66
    }
67

68
    public static Payment rehydrate(UUID id, UUID orderId, Money amount,
69
                                    PaymentStatus status, long version) {
70
        return new Payment(id, orderId, amount, status, version);
71
    }
72

73
    public Payment approve() {
74
        if (this.status != PaymentStatus.PENDING) {
75
            throw new IllegalStateException("Only pending payments can be approved");
76
        }
77
        return new Payment(id, orderId, amount, PaymentStatus.APPROVED, version + 1);
78
    }
79
}

Kotlin:

1
// Domain: Orders (Aggregate Root) — regular class, NOT data class.
2
// `total` is a derived invariant: total == sum(items.subtotal). A data class would
3
// auto-expose copy(items=..., total=...) that lets callers break the invariant.
4
class Order private constructor(
5
    val id: UUID,
6
    val items: List<OrderItem>,
7
    val total: Money,
8
    val version: Long,
9
) {
10
    init {
11
        val recomputed = items.map { it.subtotal }.fold(Money.ZERO, Money::add)
12
        require(total == recomputed) { "Order.total must equal sum of item subtotals" }
13
        require(version >= 0)        { "version must be non-negative" }
14
    }
15

16
    fun addItem(item: OrderItem): Order {
17
        val updated = items + item
18
        val newTotal = updated.map { it.subtotal }.fold(Money.ZERO, Money::add)
19
        return Order(id, updated, newTotal, version + 1)
20
    }
21

22
    companion object {
23
        fun create(id: UUID): Order = Order(id, emptyList(), Money.ZERO, version = 0)
24
        fun rehydrate(id: UUID, items: List<OrderItem>, total: Money, version: Long): Order =
25
            Order(id, items, total, version)
26
    }
27
}
28

29
// Domain: Payments (Aggregate Root) — same reasoning. `approve()` enforces
30
// PENDING → APPROVED; data class.copy(status = APPROVED) would skip the check.
31
class Payment private constructor(
32
    val id: UUID,
33
    val orderId: UUID,
34
    val amount: Money,
35
    val status: PaymentStatus,
36
    val version: Long,
37
) {
38
    fun approve(): Payment {
39
        check(status == PaymentStatus.PENDING) { "Only pending payments can be approved" }
40
        return Payment(id, orderId, amount, PaymentStatus.APPROVED, version + 1)
41
    }
42

43
    companion object {
44
        fun request(id: UUID, orderId: UUID, amount: Money): Payment =
45
            Payment(id, orderId, amount, PaymentStatus.PENDING, version = 0)
46
        fun rehydrate(id: UUID, orderId: UUID, amount: Money, status: PaymentStatus, version: Long): Payment =
47
            Payment(id, orderId, amount, status, version)
48
    }
49
}

10. DDD in This Project

This project applies DDD principles concretely. Here are real examples from the codebase:

Organization as Aggregate Root

Rule (DDD + clean-code). An aggregate root OWNS its invariants and state transitions. NEVER expose a setter. NEVER use a Kotlin data class for an aggregate root — copy(...) lets callers bypass the guards and rebuild illegal states. Use a regular class with a private constructor, a companion object factory for creation, and one method per state transition. The constructor / init block enforces structural invariants; each transition method enforces dynamic invariants (legality of state → state').

Kotlin (canonical shape):

1
class Organization private constructor(
2
    val id: UUID,
3
    val name: OrganizationName,
4
    val contactName: String,
5
    val contactLastName: String,
6
    val contactEmail: Email,
7
    val contactPhone: String,
8
    val status: OrganizationStatus,
9
    val logoUrl: String?,
10
    val websiteUrl: String?,
11
    val createdAt: Instant,
12
    val createdBy: String,
13
    val updatedAt: Instant,
14
    val updatedBy: String,
15
    val version: Long,
16
) {
17
    init {
18
        require(contactName.isNotBlank())     { "contactName required" }
19
        require(contactLastName.isNotBlank()) { "contactLastName required" }
20
        require(version >= 0)                 { "version must be non-negative" }
21
    }
22

23
    fun transitionTo(target: OrganizationStatus, by: String, clock: Clock): Organization {
24
        require(status.canTransitionTo(target)) {
25
            "Illegal Organization transition: $status → $target"
26
        }
27
        return Organization(
28
            id, name, contactName, contactLastName, contactEmail, contactPhone,
29
            target, logoUrl, websiteUrl,
30
            createdAt, createdBy, clock.instant(), by, version + 1,
31
        )
32
    }
33

34
    fun rename(newName: OrganizationName, by: String, clock: Clock): Organization =
35
        Organization(
36
            id, newName, contactName, contactLastName, contactEmail, contactPhone,
37
            status, logoUrl, websiteUrl,
38
            createdAt, createdBy, clock.instant(), by, version + 1,
39
        )
40

41
    fun isActive(): Boolean = status == OrganizationStatus.ACTIVE
42

43
    companion object {
44
        fun create(
45
            id: UUID, name: OrganizationName, contactName: String, contactLastName: String,
46
            contactEmail: Email, contactPhone: String, createdBy: String, clock: Clock,
47
        ): Organization {
48
            val now = clock.instant()
49
            return Organization(
50
                id, name, contactName, contactLastName, contactEmail, contactPhone,
51
                OrganizationStatus.PENDING_APPROVAL,
52
                logoUrl = null, websiteUrl = null,
53
                createdAt = now, createdBy = createdBy,
54
                updatedAt = now, updatedBy = createdBy,
55
                version = 0,
56
            )
57
        }
58
    }
59
}

Java equivalent:

1
public final class Organization {
2
    private final UUID id;
3
    private final OrganizationName name;
4
    private final String contactName;
5
    private final String contactLastName;
6
    private final Email contactEmail;
7
    private final String contactPhone;
8
    private final OrganizationStatus status;
9
    private final String logoUrl;
10
    private final String websiteUrl;
11
    private final Instant createdAt;
12
    private final String createdBy;
13
    private final Instant updatedAt;
14
    private final String updatedBy;
15
    private final long version;
16

17
    private Organization(/* all fields */) { /* assign + validate */ }
18

19
    public static Organization create(UUID id, OrganizationName name,
20
                                      String contactName, String contactLastName,
21
                                      Email contactEmail, String contactPhone,
22
                                      String createdBy, Clock clock) {
23
        Instant now = clock.instant();
24
        return new Organization(id, name, contactName, contactLastName,
25
            contactEmail, contactPhone, OrganizationStatus.PENDING_APPROVAL,
26
            null, null, now, createdBy, now, createdBy, 0L);
27
    }
28

29
    public Organization transitionTo(OrganizationStatus target, String by, Clock clock) {
30
        if (!status.canTransitionTo(target)) {
31
            throw new IllegalStateException(
32
                "Illegal Organization transition: " + status + " → " + target);
33
        }
34
        return new Organization(id, name, contactName, contactLastName,
35
            contactEmail, contactPhone, target, logoUrl, websiteUrl,
36
            createdAt, createdBy, clock.instant(), by, version + 1);
37
    }
38

39
    public boolean isActive() { return status == OrganizationStatus.ACTIVE; }
40

41
    // Getters only — no setters.
42
}

Why not data class here. data class auto-generates copy(...), which would let any caller do org.copy(status = OrganizationStatus.ACTIVE) skipping transitionTo’s canTransitionTo guard. The aggregate root loses control of its own state machine, and the “behavior on the entity” rule is enforced only by convention. A regular class with private constructor closes that hole at the compiler.

Value Objects referenced above (OrganizationName, Email) are immutable self-validating types in domain/.../vo/. Unlike aggregate roots, value objects MAY be Kotlin data class / Java record — they have no identity and no state machine, so structural copy is safe. They validate in their constructor (e.g. Email rejects malformed input), pushing primitive-obsession validation out of the aggregate.

OrganizationStatus as Value Object (Enum)

The enum OWNS its transition matrix. Organization.transitionTo delegates legality to status.canTransitionTo(target), so the state machine lives in one place and the aggregate never hardcodes a when/switch over states. PENDING_APPROVAL is the creation state (see Organization.create); it is terminal-inbound — nothing transitions back to it.

1
enum class OrganizationStatus {
2
    PENDING_APPROVAL,
3
    ACTIVE,
4
    INACTIVE,
5
    SUSPENDED;
6

7
    fun canTransitionTo(target: OrganizationStatus): Boolean =
8
        target in allowedTransitions
9

10
    private val allowedTransitions: Set<OrganizationStatus>
11
        get() = when (this) {
12
            PENDING_APPROVAL -> setOf(ACTIVE, INACTIVE)
13
            ACTIVE           -> setOf(INACTIVE, SUSPENDED)
14
            INACTIVE         -> setOf(ACTIVE)
15
            SUSPENDED        -> setOf(ACTIVE, INACTIVE)
16
        }
17
}

1
public enum OrganizationStatus {
2
    PENDING_APPROVAL,
3
    ACTIVE,
4
    INACTIVE,
5
    SUSPENDED;
6

7
    private static final Map<OrganizationStatus, Set<OrganizationStatus>> ALLOWED = Map.of(
8
        PENDING_APPROVAL, Set.of(ACTIVE, INACTIVE),
9
        ACTIVE,           Set.of(INACTIVE, SUSPENDED),
10
        INACTIVE,         Set.of(ACTIVE),
11
        SUSPENDED,        Set.of(ACTIVE, INACTIVE)
12
    );
13

14
    public boolean canTransitionTo(OrganizationStatus target) {
15
        return ALLOWED.get(this).contains(target);
16
    }
17
}

Command Pattern

1
data class CreateOrganizationCommand(
2
    val name: String,
3
    val contactName: String,
4
    val contactLastName: String,
5
    val contactEmail: String,
6
    val contactPhone: String,
7
)

1
public record CreateOrganizationCommand(
2
    String name,
3
    String contactName,
4
    String contactLastName,
5
    String contactEmail,
6
    String contactPhone
7
) {}

Repository Port (Abstraction)

1
interface OrganizationRepositoryPort {
2
    fun save(organization: Organization): Organization
3
    fun update(organization: Organization): Organization
4
    fun findById(id: UUID): Organization?
5
}

1
public interface OrganizationRepositoryPort {
2
    Organization save(Organization organization);
3
    Organization update(Organization organization);
4
    Optional<Organization> findById(UUID id);
5
}

Domain Events (produced by the aggregate, dispatched via Outbox)

A state transition is also a business fact. The aggregate is the only thing that knows a transition was legal, so it is the only thing entitled to declare the event. Keep events as immutable value objects in the domain layer (no framework, no broker types). The use case writes the business row AND the outbox row inside ONE local transaction — it NEVER calls a broker directly (outbox-first; see messaging.md).

1
// domain — immutable fact, framework-free
2
sealed interface OrganizationEvent {
3
    val organizationId: UUID
4
    val occurredAt: Instant
5
}
6
data class OrganizationCreated(
7
    override val organizationId: UUID,
8
    val name: String,
9
    override val occurredAt: Instant,
10
) : OrganizationEvent
11

12
// application — thin orchestration: create → save → outbox, all in one TX
13
class CreateOrganizationUseCase(
14
    private val organizations: OrganizationRepositoryPort,
15
    private val outbox: OutboxRepositoryPort,
16
    private val events: OutboxEventFactory,
17
    private val transaction: TransactionPort,
18
    private val clock: Clock,
19
) : CreateOrganizationPort {
20
    override fun execute(cmd: CreateOrganizationCommand): Organization = transaction.run {
21
        val org = Organization.create(/* mapped from cmd */, clock = clock)
22
        val saved = organizations.save(org)
23
        outbox.save(events.create(OrganizationCreated(saved.id, saved.name.value, clock.instant())))
24
        saved
25
    }
26
}

Why the event is built in the use case, not inside Organization.create: the domain declares the fact type (OrganizationCreated); the application decides when/whether to persist it to the outbox. This keeps the domain free of OutboxRepositoryPort and matches the ArchUnit rule useCasesShouldNotInjectMessagePublisherPort (publish is the dispatcher’s job, not the use case’s). See messaging.md and hexagonal-architecture.md §Messaging.

11. Recommendations

Model with domain experts. Use Event Storming to discover domain events and aggregates.
Keep the model context limited. Each bounded context should be small and focused.
Avoid forcing DDD on simple CRUD domains. Use DDD where there is genuine business complexity.
Design integrations with explicit contracts. Use ACL to isolate external models.
Apply Ubiquitous Language consistently in code, documentation, and conversations.
Domain entities MUST be immutable or use controlled mutation (return new instances).
Domain entities MUST NOT depend on frameworks, databases, or infrastructure.

11.1 Anti-pattern: Anemic Domain Model

Fowler — “Anemic Domain Model”: an object model where domain objects contain little or no behavior; logic lives in transaction-scripts (services / use cases) that fetch the entity, mutate its fields, and save it. It is a procedural design wearing OO clothes.

How to spot it

The “entity” is a data class / record / POJO with only fields + accessors.
Status changes happen via setStatus(...) or entity.copy(status = NEW) in a service.
Business rules (“ACTIVE cannot move to PENDING_APPROVAL”) live in the use case, not the entity.
Multiple unrelated services know how to mutate the same entity — no single owner of its invariants.
Tests for “the rule” import the service, not the entity.

Why it’s wrong

The aggregate has no way to refuse an illegal state — every new caller is a fresh chance to skip the rule.
Invariants drift: the rule lives in N services, gets out of sync as features land.
Use cases bloat into transaction scripts; nothing in the domain layer captures the model.
Refactoring becomes risky because the “model” is just shape — there’s no behavior to preserve.

How to fix

Move every state-changing operation onto the entity, named in domain language and carrying the same audit/time context as the canonical shape (activate(by, clock), transitionTo(target, by, clock), cancel(reason, by, clock)).
Replace public setters with intention-revealing methods that return a new instance.
In Kotlin: convert aggregate roots from data class → regular class with private constructor + companion object factory. Reserve data class for DTOs, payloads, and pure value objects.
In Java: make the constructor private, expose static create(...) factories, drop setters.
Enforce structural invariants in the constructor / init block; enforce dynamic invariants (legality of transitions) inside each transition method.
Push value-object validation (Email, OrganizationName, Money) into dedicated types — primitive obsession is anemia’s pre-stage.
Run ArchUnit / code review: any class under ..domain.. with public set* is suspect.

Quick comparison

1
// ❌ Anemic — service holds the rule, entity is a data bag
2
data class Organization(val id: UUID, val name: String, val status: OrganizationStatus)
3

4
class OrganizationService(private val repo: OrganizationRepositoryPort) {
5
    fun activate(id: UUID) {
6
        val org = repo.findById(id) ?: throw NotFound()
7
        if (org.status != OrganizationStatus.INACTIVE) throw IllegalState()
8
        repo.save(org.copy(status = OrganizationStatus.ACTIVE))   // rule lives here, fragile
9
    }
10
}
11

12
// ✅ Rich — entity owns the rule; the use case orchestrates only
13
class Organization private constructor(/* ... */) {
14
    fun activate(by: String, clock: Clock): Organization {
15
        require(status == OrganizationStatus.INACTIVE) { "only INACTIVE can activate" }
16
        return Organization(/* ..., status = ACTIVE, version + 1 */)
17
    }
18
    companion object { fun create(/* ... */): Organization = /* ... */ }
19
}
20

21
class ActivateOrganizationUseCase(/* ... */) : ActivateOrganizationPort {
22
    override fun execute(cmd: ActivateOrganizationCommand): Organization = transaction.run {
23
        val org = organizations.findById(cmd.id) ?: throw OrganizationNotFoundException(cmd.id)
24
        val activated = organizations.save(org.activate(by = cmd.actor, clock = clock))
25
        outbox.save(events.create(activated))   // + outbox.save(...) in the same TX
26
        activated
27
    }
28
}

The use case becomes a thin orchestration shell: load → call behavior on entity → save (+ outbox). All business rules sit in Organization, where they belong.

12. References

Eric Evans – Domain-Driven Design: Tackling Complexity in the Heart of Software
Vaughn Vernon – Implementing Domain-Driven Design
Alberto Brandolini – Introducing Event Storming