Domain-Driven Design (DDD)

How to apply DDD to model complex domains, define bounded contexts, and build software aligned with the business.

What problem it solves

In complex systems, the biggest challenge is not technical but communicational. Developers speak one language, business experts speak another, and the software ends up being a flawed translation of both. The result: data models that don’t reflect business reality, logic scattered across the wrong layers, and changes that require modifying half the system.

Domain-Driven Design attacks this problem at the root: it proposes that software should directly model the business domain, using the same language that domain experts use. It is not a framework or a library — it is a design approach that puts the domain at the center of every architectural decision.

Symptoms that you need DDD

• The technical team and the business team don’t understand each other
• Data models are database tables disguised as objects
• A change in a business rule requires modifying multiple services
• There are no clear boundaries between the responsibilities of each part of the system
• Business logic is scattered across controllers, services, and repositories
• The names in the code don’t match the terms the business uses

A concrete example of the problem

Imagine an e-commerce system where the business team talks about “orders,” “returns,” and “refunds,” but the code has classes like DataProcessor, ItemHandler, and TransactionManager. When the business says “we need to change the returns policy,” nobody knows which files to touch because there is no Return class or a Refunds module.

❌ Sin DDD — Código desconectado del negocio:
   src/
   ├── handlers/
   │   ├── DataProcessor.java
   │   ├── ItemHandler.java
   │   └── TransactionManager.java
   ├── models/
   │   ├── Record.java
   │   └── Entry.java
   └── utils/
       └── Helper.java

✅ Con DDD — Código alineado con el dominio:
   src/
   ├── pedidos/
   │   ├── Pedido.java
   │   ├── LíneaDePedido.java
   │   └── RepositorioPedidos.java
   ├── devoluciones/
   │   ├── Devolución.java
   │   ├── PolíticaDevolución.java
   │   └── ServicioReembolso.java
   └── envíos/
       ├── Envío.java
       └── TransportistaAdapter.java

How it works

DDD is divided into two major areas: strategic design (how to divide the system) and tactical design (how to model each part).

Strategic design

Ubiquitous Language

This is the shared vocabulary between developers and domain experts. If the business talks about “orders,” “shipments,” and “returns,” the code must use exactly those terms — not “orders_table,” “shipping_record,” or “return_entity.”

❌ Código sin lenguaje ubicuo:
   class DataRecord { processItem() }

✅ Código con lenguaje ubicuo:
   class Pedido { confirmarEnvío() }

The ubiquitous language is documented, maintained, and used in conversations, code, tests, and documentation. It is not just a naming convention — it is an active agreement between business and development that evolves with the domain.

How to build the ubiquitous language:

1. Run Event Storming sessions with domain experts and developers
2. Identify the key terms the business uses and document them in a shared glossary
3. Use those exact terms in the code, the tests, the documentation, and conversations
4. When ambiguity arises (the same word means different things), it’s a sign that you need separate bounded contexts

Bounded Contexts

A bounded context is an explicit boundary within which a domain model has consistent meaning. The same word can mean different things in different contexts:

• “Customer” in the Sales context: someone who buys products
• “Customer” in the Support context: someone who opens tickets
• “Customer” in the Billing context: an entity with tax data

┌─────────────────────┐  ┌─────────────────────┐
│  Contexto: Ventas   │  │  Contexto: Soporte  │
│                     │  │                     │
│  Cliente            │  │  Cliente            │
│  ├─ nombre          │  │  ├─ nombre          │
│  ├─ historialCompra │  │  ├─ ticketsAbiertos │
│  └─ descuento       │  │  └─ nivelPrioridad  │
│                     │  │                     │
│  Pedido             │  │  Ticket             │
│  ├─ líneas          │  │  ├─ descripción     │
│  └─ total           │  │  └─ estado          │
└─────────────────────┘  └─────────────────────┘

Each bounded context has its own model, its own database, and its own team (ideally). Communication between contexts happens through well-defined interfaces.

Practical rules for identifying bounded contexts:

• If two teams need different models of the same concept → separate contexts
• If a change in one area shouldn’t affect another → separate contexts
• If the ubiquitous language changes → you’re crossing a context boundary
• A bounded context isn’t necessarily a microservice, but it’s a natural candidate to become one

Context Mapping

Defines how bounded contexts relate to each other:

Tactical design

Entities

Objects with a unique identity that persists over time. Two entities with the same attributes but a different ID are different.

Pedido #1234 ≠ Pedido #5678
(aunque ambos tengan los mismos productos y el mismo total)

Entities encapsulate behavior, not just data. An Order is not a DTO with getters and setters — it has methods that reflect domain operations:

// ❌ Modelo anémico (anti-patrón)
pedido.setEstado("confirmado");
pedido.setFechaConfirmacion(new Date());

// ✅ Modelo rico con comportamiento
pedido.confirmar();  // internamente valida reglas y cambia estado

Value Objects

Objects defined by their attributes, with no identity of their own. Two value objects with the same attributes are equal. They are immutable.

Dirección("Calle 1", "Ciudad A") == Dirección("Calle 1", "Ciudad A")
Dinero(100, "USD") == Dinero(100, "USD")

Value objects are more common than they seem. Many concepts we model as strings or primitive numbers should be value objects:

// ❌ Tipos primitivos
String email = "user@example.com";
double precio = 99.99;

// ✅ Value objects con validación
Email email = new Email("user@example.com");  // valida formato
Dinero precio = new Dinero(99.99, "USD");      // evita mezclar monedas

Aggregates

A cluster of entities and value objects that are treated as a unit of consistency. Each aggregate has a root (Aggregate Root) that is the only external point of access.

┌─────────────────────────────┐
│  Aggregate: Pedido          │
│  ┌───────────────────────┐  │
│  │ Pedido (Aggregate Root)│  │
│  │  ├─ id                │  │
│  │  ├─ estado            │  │
│  │  └─ fechaCreación     │  │
│  └───────────────────────┘  │
│  ┌──────────┐ ┌──────────┐  │
│  │ LíneaPed │ │ LíneaPed │  │
│  │ producto │ │ producto │  │
│  │ cantidad │ │ cantidad │  │
│  │ precio   │ │ precio   │  │
│  └──────────┘ └──────────┘  │
│  ┌──────────────────────┐   │
│  │ DirecciónEnvío (VO)  │   │
│  └──────────────────────┘   │
└─────────────────────────────┘

Key rules for aggregates:

• Transactions should only modify one aggregate at a time
• References between aggregates are made by ID, not by direct reference
• If you need to modify several aggregates, use Domain Events
• Keep aggregates small — a large aggregate is a sign of incorrect boundaries

Domain Events

They represent something that happened in the domain. They are expressed in the past tense and in business language.

PedidoConfirmado { pedidoId, fecha, total }
PagoRecibido { pagoId, pedidoId, monto }
EnvíoDespachado { envíoId, pedidoId, transportista }

Events allow bounded contexts to communicate in a decoupled way. They are the foundation of Event-Driven Architecture and of the Saga Pattern for coordinating distributed transactions.

Example of an event-driven flow:

Contexto Ventas:
  pedido.confirmar()
  → publica PedidoConfirmado

Contexto Inventario:
  escucha PedidoConfirmado
  → reserva stock
  → publica StockReservado

Contexto Envíos:
  escucha StockReservado
  → programa envío
  → publica EnvíoProgramado

Repositories

Abstractions that encapsulate data access. The domain doesn’t know whether the data comes from a database, an API, or a file. The repository speaks the language of the domain.

❌ pedidoDAO.selectByStatusAndDate(status, date)
✅ repositorioPedidos.buscarPendientesDesde(fecha)

Domain Services

Operations that don’t naturally belong to any entity or value object. They contain business logic that involves multiple aggregates.

ServicioDePrecios.calcularDescuento(cliente, pedido, promoción)
ServicioDeEnvío.seleccionarTransportista(pedido, destino)

Practical example: E-commerce with DDD

Let’s see how DDD is applied to a real e-commerce system:

Step 1: Identify bounded contexts

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│    Catálogo      │  │    Pedidos       │  │    Pagos         │
│                  │  │                  │  │                  │
│  Producto        │  │  Pedido          │  │  Transacción     │
│  Categoría       │  │  LíneaDePedido   │  │  MétodoDePago    │
│  Precio          │  │  DirecciónEnvío  │  │  Reembolso       │
│  Inventario      │  │  EstadoPedido    │  │  EstadoPago      │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
         │    Eventos         │    Eventos         │
         └────────────────────┴────────────────────┘

Step 2: Define aggregates in the Orders context

Aggregate Root: Pedido
├── id: PedidoId (Value Object)
├── cliente: ClienteId (referencia por ID, no por objeto)
├── líneas: List<LíneaDePedido>
│   ├── productoId: ProductoId
│   ├── cantidad: Cantidad (Value Object, > 0)
│   └── precioUnitario: Dinero (Value Object)
├── dirección: DirecciónEnvío (Value Object)
├── estado: EstadoPedido (enum)
└── total(): Dinero (calculado)

Invariantes del agregado:
- Un pedido debe tener al menos una línea
- El total nunca puede ser negativo
- Solo se puede confirmar un pedido en estado "borrador"
- Solo se puede cancelar un pedido que no ha sido enviado

Step 3: Implement behavior in the aggregate

class Pedido {
  confirmar() {
    if (this.estado !== 'borrador')
      throw new Error('Solo se puede confirmar un pedido en borrador');
    if (this.líneas.length === 0)
      throw new Error('El pedido debe tener al menos una línea');

    this.estado = 'confirmado';
    this.fechaConfirmación = new Date();
    this.registrarEvento(new PedidoConfirmado(this.id, this.total()));
  }

  cancelar(motivo) {
    if (this.estado === 'enviado' || this.estado === 'entregado')
      throw new Error('No se puede cancelar un pedido ya enviado');

    this.estado = 'cancelado';
    this.motivoCancelación = motivo;
    this.registrarEvento(new PedidoCancelado(this.id, motivo));
  }
}

Advantages

• Business-technology alignment: The code directly reflects the domain, reducing the communication gap
• Clear boundaries: Bounded contexts define explicit boundaries that make independent evolution easier
• Rich model: Entities contain behavior, not just data, avoiding anemic models
• Organizational scalability: Each bounded context can be developed by an independent team
• Controlled evolution: Changes in one context don’t affect others as long as the interfaces are maintained
• Foundation for microservices: Bounded contexts are natural candidates to become microservices
• Clearer testing: Tests reflect real business rules, not technical implementations

Trade-offs / Disadvantages

• Steep learning curve: DDD introduces many concepts that take time to master
• Overhead in simple domains: For basic CRUDs, DDD adds unnecessary complexity
• Requires access to domain experts: Without constant collaboration with the business, the model drifts
• More initial code: Entities, value objects, repositories, and events require more code than a direct approach
• Risk of over-engineering: It’s easy to apply all the tactical patterns when you only need a few
• Intentional duplication: Each bounded context may have its own representation of similar concepts
• Investment in discovery: Event Storming and modeling sessions require time and active participation from the business

When to use

• Complex domains with many business rules
• Systems that evolve frequently due to business changes
• Large teams that need to work in parallel with clear boundaries
• Projects where communication between business and development is critical
• Systems being migrated from a monolith to microservices
• When the cost of an incorrect model is high (finance, healthcare, logistics)

When to avoid

• Simple CRUD applications with no significant business logic
• Prototypes or MVPs where speed matters more than structure
• Small teams without access to domain experts
• Systems with well-understood, stable domains that don’t change
• Projects with a very limited budget or time for the design phase

Common technologies and implementations

Relationship with other patterns

DDD is the conceptual foundation on which many other distributed architecture patterns are built:

┌─────────────────────────────────────────────────┐
│              Domain-Driven Design                │
│         (Bounded Contexts + Ubiquitous Language) │
└──────────┬──────────┬──────────┬────────────────┘
           │          │          │
           ▼          ▼          ▼
    ┌──────────┐ ┌──────────┐ ┌──────────────┐
    │Microserv.│ │  Event   │ │    Shared    │
    │ Pattern  │ │  Driven  │ │    Kernel    │
    └──────────┘ └──────────┘ └──────────────┘
           │          │
           ▼          ▼
    ┌──────────┐ ┌──────────┐
    │   Saga   │ │  Outbox  │
    │ Pattern  │ │ Pattern  │
    └──────────┘ └──────────┘

• Microservices Pattern: DDD’s bounded contexts are the guide for defining the boundaries of each microservice
• Event-Driven Architecture: DDD’s Domain Events are the foundation of asynchronous communication between services
• Saga Pattern: Coordinates transactions that cross multiple bounded contexts using events and compensations
• Outbox Pattern: Guarantees that Domain Events are published reliably together with data changes
• Anti-Corruption Layer (ACL): Implements the Context Mapping relationship that protects your domain from external models
• Shared Kernel: Implements the Context Mapping relationship where two contexts share a subset of the model
• API Gateway / BFF: Provide entry points that can map external requests to the internal bounded contexts

Common mistakes when applying DDD

Next steps

With DDD as the foundation for modeling complex domains, the natural next step is to understand how to handle transactions that cross multiple bounded contexts. That’s what the Saga Pattern is for, coordinating distributed operations with compensations. Also explore the Microservices Pattern to understand how bounded contexts turn into independent services.