Domain Driven Design

1. Why DDD exists

Most software fails not because the code is wrong, but because the code models the wrong thing. A developer reads a ticket, builds what they think it says, and ships something the business doesn't recognise. Over a few years of this, the codebase drifts away from the work it's supposed to do, and every change becomes a translation exercise between two different vocabularies.

Eric Evans named this problem in 2003 in Domain-Driven Design: Tackling Complexity in the Heart of Software. The proposal was simple to state and unreasonably hard to do: stop treating the domain (the actual business) as something to be summarised on a napkin and then translated into "real" technical artefacts. Instead, make the domain model the heart of the system. Speak about it in plain language with the people who run the business. Write the code in that same language. When the model changes, both move together.

DDD isn't a framework or a library. It's a set of practices and a shared vocabulary for doing what good engineers were always trying to do anyway: keep the software honest about the world it represents.

2. Ubiquitous language

The first move in DDD is linguistic, not technical. The team (developers and the people who understand the business) agrees on a precise vocabulary for the domain. Every important concept gets one name, used everywhere: in conversation, on whiteboards, in tickets, in class names, in database tables, in API payloads.

This sounds banal until you've worked in a codebase where the same thing is called User, Account, Member, Subscriber and Customer in five different places. Each name carries slightly different assumptions, and every time data crosses one of those boundaries, somebody has to translate. The translations leak.

The ubiquitous language is the discipline of refusing to do that. If the salespeople call them "accounts", the code calls them accounts. If the model needs a distinction the language doesn't have, you invent the word together and then use it everywhere. A new developer reading the code should be able to walk into a meeting with the business and follow along.

3. Bounded contexts

Here's the catch: a single ubiquitous language across a whole company is impossible. The word "order" means one thing to sales, another to fulfilment, another to accounting. Trying to force one canonical Order class to serve all three teams produces a monstrosity with sixty fields, half of which are null at any given time.

DDD's answer is the bounded context: an explicit boundary inside which one model and one language are consistent. Outside the boundary, the same word may mean something different, and that's fine. The boundary is real: separate codebase or module, separate database schema, separate deployment if needed, and crucially, separate vocabulary.

Bounded contexts are the strategic core of DDD. They line up naturally with team boundaries, with microservice splits (when those make sense), and with the actual seams in the business. The hard work isn't drawing the boxes; it's deciding where the edges go, and then defending them.

4. Context maps

Contexts have to talk to each other. The context map documents how. It's a high-level picture of which contexts exist, who owns each one, and what kind of relationship sits on every line between them. The relationship type matters because it tells you what to expect when the other side changes.

5. The tactical toolbox

Inside a single bounded context, DDD offers a kit of building blocks for the model itself. They're not novel in isolation, but they have specific names and specific jobs, which is the point: the language is part of the design.

Entities vs value objects, concretely

A Customer with id c-42 is an entity. If she changes her name and address, she's still c-42. Her identity is the point.

An Address with street, city and postcode is a value object. If you change the postcode, what you now have is a different address, not a mutated version of the old one. You replace, you don't update. Treating things that should be values as if they were entities (giving an address its own row, primary key and lifecycle) is one of the most common modelling mistakes DDD pushes back on.

// Value object: equality by value, immutable
class Money {
  constructor(readonly amount: number, readonly currency: string) {
    if (amount < 0) throw new Error("amount must be >= 0");
  }
  add(other: Money): Money {
    if (other.currency !== this.currency) throw new Error("mismatch");
    return new Money(this.amount + other.amount, this.currency);
  }
  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}

// Entity: equality by id, behaviour lives on the class
class Customer {
  constructor(readonly id: CustomerId, private name: string) {}
  rename(newName: string) {
    if (!newName.trim()) throw new Error("name required");
    this.name = newName;
  }
  equals(other: Customer): boolean {
    return this.id.equals(other.id);
  }
}

6. Aggregates in detail

Aggregates are the idea most worth taking time over, because they're where DDD's strategic and tactical sides meet. An aggregate is a cluster of objects you can only change as a unit. The aggregate root is the one entity inside it that everything else talks to; nothing outside the aggregate gets to hold references to the inner pieces.

Why this rule? Because the aggregate is the unit at which the model promises consistency. The Order root enforces "total equals the sum of lines"; if external code can grab an OrderLine and change its price without going through the root, that invariant is dead. The boundary buys you a property worth a lot in practice: when you load an aggregate, change it, and save it, the rules hold; you don't have to defend them in a hundred call sites.

Good aggregates are small. Beginners tend to draw the boundary too wide, hauling whole graphs into memory and serialising them through a single root. The guideline that has stood up well: one aggregate, one transaction, one consistency rule. Cross-aggregate consistency is achieved by domain events and eventual consistency, not by stuffing everything into one root.

7. Layers around the domain

The model sits in the middle. Around it, DDD codebases usually arrange a few thin layers, each with a strict job:

A useful test: can you compile and run the unit tests of the domain layer with the database, web framework, and message broker all uninstalled? If yes, the layering is doing its job.

8. A worked example

Take a small slice of an e-commerce fulfilment context: shipping an order. The use case is "mark this order as shipped, record the carrier and tracking number, and let other systems know".

The aggregate root, with the rules on the root rather than in a service:

// domain/order.ts
export class Order {
  private status: OrderStatus = "pending";
  private lines: OrderLine[] = [];
  private shipment?: Shipment;
  private events: DomainEvent[] = [];

  constructor(
    readonly id: OrderId,
    readonly customerId: CustomerId,
    readonly shipTo: Address,
  ) {}

  addLine(sku: Sku, qty: number, unitPrice: Money) {
    if (this.status !== "pending") throw new Error("order is closed");
    if (qty <= 0) throw new Error("qty must be positive");
    this.lines.push(new OrderLine(sku, qty, unitPrice));
  }

  total(): Money {
    return this.lines.reduce(
      (sum, l) => sum.add(l.unitPrice.times(l.qty)),
      Money.zero("GBP"),
    );
  }

  ship(carrier: Carrier, tracking: TrackingNumber, when: Date) {
    if (this.status !== "ready") throw new Error("not ready to ship");
    if (this.lines.length === 0) throw new Error("nothing to ship");
    this.shipment = new Shipment(carrier, tracking, when);
    this.status = "shipped";
    this.events.push(new OrderShipped(this.id, carrier, tracking, when));
  }

  pullEvents(): DomainEvent[] {
    const e = this.events;
    this.events = [];
    return e;
  }
}

Notice what the Order doesn't do: it doesn't know about databases, doesn't call APIs, doesn't write to a queue. It guards its own invariants and records that something happened.

The application service orchestrates the use case but contains no business rules:

// application/ship-order.ts
export class ShipOrderService {
  constructor(
    private orders: OrderRepository,
    private bus: DomainEventBus,
    private clock: Clock,
  ) {}

  async execute(cmd: ShipOrderCommand): Promise<void> {
    const order = await this.orders.findById(cmd.orderId);
    if (!order) throw new NotFound(cmd.orderId);

    order.ship(cmd.carrier, cmd.trackingNumber, this.clock.now());

    await this.orders.save(order);
    await this.bus.publish(order.pullEvents());
  }
}

And the repository is an interface in the domain layer; its real implementation lives in infrastructure and knows about Postgres or whatever you happen to be using. Other contexts react to the OrderShipped event without ever touching this aggregate directly. That's how cross-context consistency happens in practice: not through shared tables, but through facts crossing the boundary.

9. When it's worth the trouble

DDD is not free. The discipline costs time up front: workshops with the business, debates about names, refactors that move logic out of services and into entities, additional layers, additional indirection. On a four-week CRUD app, it's overkill. On a company's core revenue-producing system that will live for a decade and be touched by dozens of engineers, it's cheap.

The honest heuristic, after twenty years of people trying it:

• Worth it: the domain is genuinely complex (insurance, logistics, trading, healthcare, anything with real rules); multiple teams will work on the same system; the business is the differentiator and the software is the business.
• Probably overkill: a thin CRUD UI over a database; a one-team prototype; a system whose logic is "save these forms and email people".
• Take the strategic bits even on small projects: bounded contexts and a deliberate vocabulary cost almost nothing and pay off immediately. You don't need aggregates and repositories to benefit from naming things properly.

The deeper claim of DDD, the one worth sitting with, is that the limit on most software is not technical at all. It's how clearly the team understands the work the software is supposed to do, and how faithfully that understanding gets into the code. The patterns are just scaffolding for that conversation. Once you've seen a codebase where the model and the business are the same thing, settling for less feels strange.

Primary source: Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software (2003). See also the DDD Reference (Evans, 2015) and Martin Fowler's notes on bounded context. Vaughn Vernon's Implementing Domain-Driven Design (2013) is the standard follow-up for the tactical patterns.