Strategic domain-driven design: bounded contexts and context maps

Why domain-driven design belongs in a chapter about structure

Every style in this chapter needs boundaries. A modular monolith needs module boundaries; the microservices of Chapter 6 need service boundaries; even a hexagonal application needs to know what belongs inside the hexagon. Domain-driven design (DDD) is the most widely used method for finding those boundaries in the business domain itself, rather than in technical layers.

Eric Evans introduced it in Domain-Driven Design: Tackling Complexity in the Heart of Software (Addison-Wesley, 2003). His argument is that in most business software the hardest problems are not technical but in understanding the domain: what a policy, a claim, a delivery or a refund really is, and which rules govern it. Software should therefore be built around a deliberately designed model of the domain, developed jointly by developers and domain experts, and that model should be protected from confusion with other models. In 2015 Evans published a short DDD Reference that summarises the patterns and adds a few, such as partnership and big ball of mud as context-map patterns, and domain events as a building block.

DDD has two halves. Strategic design divides a large domain into subdomains and bounded contexts and maps the relationships between them; it is architecture, and it is the main subject here. Tactical design provides building blocks (entities, value objects, aggregates and others) for writing the model inside one context; it is design, and it is covered briefly.

Ubiquitous language

A ubiquitous language is a shared vocabulary, built by developers and domain experts together, that is used consistently in conversation, documents, tests and code. If dispatchers say a courier is "stacked" when carrying two orders from the same restaurant, then the code says stack, not multiOrderAssignment. When a term turns out to be ambiguous or awkward, the team changes the language and the code together.

This sounds like a matter of naming, but it has architectural consequences. Translation between the words of the business and the words of the code is where misunderstandings, and therefore defects, are born. And the moment two groups use the same word with different meanings, you have found evidence of two different models, which is the starting point for bounded contexts.

Subdomains: core, supporting and generic

The business domain as a whole divides into subdomains: areas of activity such as menus, ordering, payments and dispatch. Practitioners classify them into three kinds, building on Evans's distinction between the core domain and generic subdomains; the three-way split with supporting subdomains was popularised by later writers, notably Vaughn Vernon in Implementing Domain-Driven Design (2013).

The core domain is what makes the business different from its competitors and is the reason the software is worth building. For a food-delivery company it is probably dispatch: matching orders to couriers and predicting arrival times. A supporting subdomain is specific to the business and necessary, but not a source of advantage: menu management, courier onboarding. A generic subdomain is a problem many businesses share, with good existing solutions: payments, identity, email and SMS.

The classification is an investment decision. The core deserves the most experienced people, the richest modelling and code you own completely, because that is where better software turns directly into business advantage. Supporting subdomains deserve sound but simpler designs, often a straightforward layered module. Generic subdomains should usually be bought, used as a service or built as thin adapters over open-source components: building your own identity provider is effort spent where you cannot win. The classification also changes over time; a supporting capability can become core when the business strategy changes.

Bounded contexts

A bounded context is an explicit boundary within which one model, and one ubiquitous language, applies consistently. Inside it, "order" has exactly one meaning. Outside it, the same word may mean something else, and that is acceptable, because each model is designed for one purpose. Evans observed that trying to unify the model of a large system into one is neither feasible nor cost-effective; the attempt produces enormous shared classes that serve every purpose badly and that every team must change.

Subdomains and bounded contexts are different things, though often aligned. A subdomain is part of the problem: it exists in the business whether or not software does. A bounded context is part of the solution: a boundary you choose for a model and, usually, for code and data owned by one team. The ideal is one bounded context per subdomain, but legacy systems often have one context spanning several subdomains, and a large subdomain may need several contexts.

Context maps

A context map shows the bounded contexts of a system and the relationships between them. The relationships describe both the technical integration and the power and communication between the teams, which is why context mapping is as much about organisations as about code. It is a direct application of Conway's law: the map shows where the organisation's communication paths and the system's integration paths must line up.

Many relationships are upstream/downstream: the upstream context's decisions affect the downstream one, but not the reverse. The downstream team then has a choice about how to cope, and that choice is what most of the patterns name.

Two of these patterns deserve special attention. An anticorruption layer (ACL) is a set of adapters and translators that a downstream context builds so that a foreign model, often a legacy system or an external provider, cannot leak into its own model. It is the same idea as the driven adapter of Section 5.6, applied between contexts, and it is the default choice for integrating with anything you do not control. An open host service together with a published language is the upstream's way of serving many consumers well: one documented, versioned protocol instead of a custom integration for each. A shared kernel should stay small; a large one turns two contexts back into one with two teams arguing over it, and Evans's 2015 reference adds big ball of mud as the honest label for an area with no clear boundaries at all, to be contained rather than extended.

Event storming: discovering the contexts

Boundaries are discovered with domain experts, not designed alone. Event storming, created by Alberto Brandolini and first described on his blog in 2013, is the most popular workshop format for this. The people who know the business and the people who build the software stand at a long wall of paper and write domain events (things that happened, in the past tense: Order placed, Courier assigned, Food collected) on orange sticky notes, placing them on a timeline.

The group then adds the commands that cause events, the people and external systems involved, the policies that react to events ("whenever an order is placed, find a courier") and, crucially, the hot spots where people disagree or nobody knows. Clusters of events that share a language and a purpose suggest bounded contexts; places where the same word is used differently suggest boundaries; places where a hand-over happens suggest integration points. A big-picture session for a whole business takes a day or two and needs almost no preparation beyond the right people and a lot of wall space.

Tactical patterns in brief

Inside one bounded context, DDD offers building blocks for the model. An entity has an identity that persists while its attributes change: an order is the same order after its status changes. A value object has no identity and is defined only by its values: two Money(12.50, "GBP") objects are interchangeable, and value objects are usually immutable. A domain event records something meaningful that happened in the domain.

An aggregate is a cluster of entities and value objects treated as one unit for changes, with one entity as its root. Outside code may hold references only to the root and must change the aggregate only through it, so the root can enforce the aggregate's invariants (rules that must always hold, such as "no items can be added after an order is placed"). One transaction should change one aggregate; other aggregates are referenced by ID and updated through domain events, which makes aggregates the natural unit of consistency and later of distribution. A repository loads and saves whole aggregates and looks to the domain like a collection; its interface is a driven port in hexagonal terms.

from dataclasses import dataclass, field
from decimal import Decimal

@dataclass(frozen=True)
class Money:                               # value object: equal if values equal
    amount: Decimal
    currency: str
    def __add__(self, other):
        if other.currency != self.currency:
            raise ValueError("currency mismatch")
        return Money(self.amount + other.amount, self.currency)
    def times(self, n: int):
        return Money(self.amount * n, self.currency)

@dataclass
class OrderLine:                           # entity inside the aggregate
    dish_id: str
    qty: int
    price: Money

@dataclass
class Order:                               # aggregate root
    id: str
    restaurant_id: str                     # other aggregates referenced by ID only
    lines: list[OrderLine] = field(default_factory=list)
    status: str = "draft"
    events: list = field(default_factory=list)

    def add(self, dish_id, qty, price):
        if self.status != "draft":
            raise ValueError("order already placed")    # invariant
        self.lines.append(OrderLine(dish_id, qty, price))

    def place(self, minimum: Money):
        total = Money(Decimal(0), minimum.currency)
        for line in self.lines:
            total = total + line.price.times(line.qty)
        if total.amount < minimum.amount:
            raise ValueError("below restaurant minimum")  # invariant
        self.status = "placed"
        self.events.append({"type": "OrderPlaced", "order_id": self.id, "total": str(total.amount)})

The example keeps the aggregate small, references the restaurant by ID rather than holding a restaurant object, and enforces its rules in methods rather than leaving them to callers. A common mistake is the opposite: aggregates so large that every user's change locks the same rows, or domain objects that are only bags of getters and setters while the rules live in service classes (Martin Fowler calls this the anaemic domain model).

Bounded contexts as module and service boundaries

Bounded contexts are the best available guide to where to draw module boundaries in a monolith and service boundaries in a distributed system. A context has its own model, its own language, its own data and ideally one owning team, which are exactly the properties that make a module cohesive and loosely coupled. In a modular monolith each context becomes a module with its own schema; inside it, the hexagonal structure of Section 5.6 keeps the model independent of infrastructure.

If a context later needs to be deployed separately, its boundary is already the right shape for a service, and its relationships on the context map tell you what the integration must look like. This is why many practitioners recommend finding contexts first and deciding deployment second. The reverse also holds: services cut across bounded contexts (an "order service" that every context writes to) produce the tightly coupled distributed monolith discussed in Section 6.3. Note also that a bounded context is not automatically one microservice; a context can be deployed as several services, and several small contexts can share one deployment.