Bounded contexts, concretely

A bounded context gives one domain model and vocabulary a clear scope. To find a useful boundary, start with words that mean different things in different workflows, then check whether their lifecycles, business rules and change pressures also diverge. The boundary keeps internal models separate; it does not forbid data crossing through an explicit API or event contract.

Find the boundary by finding the word#

Run the test on customer in this illustrative sales-and-dispatch example. The two parts of this system do not define it the same way.

A customer in sales has a pipeline stage, a lead source, and a rep who owns the relationship. It has no address anyone would post a letter to, because at that stage nobody has one. A customer in dispatch has a delivery name that must match the signed receipt, a postal address, access notes and a service level; it has no pipeline stage, because by the time you are invoicing someone the pipeline is over. A customer in support has a contract tier, a ticket history and an escalation path, and cares about none of the above.

Three sets of attributes, three lifecycles, three teams each of whom will tell you theirs is the real customer. All three are right. The word is doing three jobs, and the jobs are genuinely different.

The word is a first clue, not a complete boundary test. Check three more signals. Lifecycle: a sales prospect can be lost without ever becoming a delivery recipient, while a dispatch recipient may persist through returns; split when the same record would need incompatible state transitions. Rules and consistency: dispatch must validate a delivery address before scheduling, while sales may work without one; split when one model would make a rule optional for most callers. Change cadence: sales may change lead scoring frequently while dispatch’s proof-of-delivery contract changes rarely; split when shared releases repeatedly force unrelated teams to coordinate. These signals matter most when a noun alone is ambiguous.

# sales/models.py
@dataclass
class Customer:
    id: CustomerId
    company_name: str
    stage: PipelineStage       # prospect, qualified, won, lost
    source: LeadSource
    owner: SalesRepId

# dispatch/models.py
@dataclass
class Customer:
    id: CustomerId
    delivery_name: str         # must match the signed receipt
    address: PostalAddress
    access_notes: str | None
    service_level: ServiceLevel

The argument is how short each one is. Neither class is missing anything: each holds exactly what its own side of the system needs to do its work, and nothing it would have to leave empty.

You can see the symptom when a codebase refuses this. One class tries to be all three, and it grows fields that most callers ignore — a table with nullable columns nobody can explain, a constructor with eight optional arguments, a validation rule that is only correct when called from one place. The comment # only set for dispatch customers is the boundary, written down as an apology instead of as a decision.

Two things are worth being precise about. The first is that the boundary goes where the meaning changes, not where the org chart happens to split. Those often coincide, and when they do not, the meaning wins — a team that owns two meanings owns two contexts, and pretending otherwise just moves the confusion inside the team. The second is what the boundary buys you, which is smaller than people expect and more useful: inside it, one word means one thing, so a rule about customers can be written without a qualifier. That is the whole benefit. Everything else follows from being able to say something true in one sentence.

This is what the pattern language calls a ubiquitous language, and the part most often misquoted is its scope. The shared vocabulary lives inside one boundary, not across the system. There is no goal of getting the whole company to agree on what a customer is. The goal is that within each context, everyone — including the code — uses the same word the same way.

What crosses, and what stays#

The internal model does not cross as a shared object. A contract can carry an identifier and the facts the recipient needs, in terms both sides have agreed to exchange. For example, Sales can publish a SaleWon event containing a customer id and order id; Dispatch then collects and validates delivery details in its own model. The event is an integration contract, not the Sales Customer class serialized wholesale.

This is a context map for the example, not a proposed universal event schema. Sales owns prospect state, Dispatch owns delivery state, and Support owns case state. Contract fields are chosen for the receiving task; none of those contexts imports another’s complete Customer model.

Somewhere a piece of code turns one contract into the receiving model. Make that translation and its owner explicit. An anti-corruption layer is a translation seam at the edge of a context whose job is to stop the other side’s model leaking into yours. Without that seam, a sales stage field can appear in a delivery note, then in a report, then in a query that nobody can change because three teams read it.

Between any two contexts there is a relationship, whether or not anyone named it. Naming it is useful because each one commits you to something different.

These are relationships between two contexts, not qualities of one. The same context is usually a conformist to one neighbour and runs a translation layer against another, and that is normal rather than inconsistent.

The next published stop on this path takes one such boundary — a write API and the systems that retry against it — and works through what the contract across it has to promise: idempotency keys and safe retries. The architecture path holds the rest in the order that makes each step explain the next.

External APIs bring their own language#

A boundary does not require a second team inside your company. An API you do not control arrives with its own nouns, states and lifecycle, and those words are true inside the provider’s system rather than automatically true inside yours. In a simplified example, a messaging API reports message.created. That means the provider recorded a message; it does not establish that your domain’s idea of a meaningful interaction happened. The message might be automated, retried, inbound, or a notification your product does not count at all.

Translate that fact at the edge before core code sees it. Keep the provider identifier and enough correlation data at the integration boundary to explain which external fact produced which internal one, then emit the smallest statement your own model can defend. If the external signal is insufficient, the honest internal state is unknown or needs confirmation, not a stronger business fact invented from the provider’s vocabulary. A provider status should not become a field on every domain object merely because the webhook arrived first.

That is the anti-corruption-layer row above with an external system on the other side. If the provider renames a state, changes a payload or is replaced, the translation code changes while the rest of the model keeps talking in its own terms. When the two meanings genuinely match, conforming can still be cheaper; translation is valuable because the semantics differ, not because an adapter is fashionable. And once the translation has produced an internal event, its delivery guarantees are a separate question — the distinction worked through in events and what they promise.

The shared core library#

It arrives with impeccable reasoning: two contexts both have a Customer, somebody notices the duplication, and the common parts are extracted into a package both sides depend on. Nobody objects, because nobody argues in favour of duplication.

Then the two models start to move apart, because they were never the same model.

The uncomfortable conclusion, and the one that gets argued about: duplicating the class was the cheaper option. The two things were never the same thing, so what looked like duplication was two similar-looking definitions of different concepts — and merging those does not remove work, it converts private work into negotiated work. The fields drift apart on their own, and the shared package spends its life resisting.

That does not retire the shared kernel: it is a real pattern, and sometimes exactly right. What makes it right is not the absence of duplication. It is joint ownership by two teams who genuinely collaborate, over a surface small enough that both can hold it in their heads — a set of identifiers and a couple of value types, not an entity with a lifecycle. A shared kernel that has grown a lifecycle has stopped being a kernel and become a third context that nobody is responsible for.

A boundary drawn on a whiteboard costs nothing. It starts costing something at the point where a single unit of work has to span two of them, which is where the transaction boundary stops being an implementation detail.