Bounding Contexts
In this pack:
sizing,
notation,
rule strictness.
Overview
A clinic's system grows past one model that one team can hold. Reception
and billing begin with different meanings for an appointment, another
part fills prescriptions, and payroll arrives as a product nobody in
the clinic wants to build. This skill draws the line between parts that
keep a model of their own, says how those parts talk and who must be
asked before a change, places a translator where a part depends on a
model it does not control, and keeps design effort on the work that
makes this clinic different.
When to use
- A model has grown past one team, and a change to it needs several
teams to agree.
- One word has a different meaning for two separately owned parts of the
system.
- Two parts with their own models must talk, and nobody can say which
one depends on the other.
- A part depends on a model that another team or an outside service
controls.
- The team is deciding which parts to model richly, which to keep plain
and which to buy.
- A new product or service must fit beside the clinic's model without
replacing it.
When not to use
- One team owns the whole code and every word has one meaning there:
there is one model, and no boundary to draw.
- Two meanings of one word share one codebase and one team: they get two
classes, as rule 4 of speaking the domain language asks.
- The question is which layer or class depends on which inside one
context.
- The question is the shape or the version of data that crosses a
boundary already drawn, such as an API's fields.
Core rules
Rule. Draw a context boundary where the model's words change
meaning. A context is a part of the system whose model has its own
words and one owner. Inside one context each word means one thing; at
the line, reception's appointment is a booked slot while billing's
billable visit is the visit it prices. Where those two meanings
meet, two contexts meet. Each context keeps its own model, even when
both read one table today. Inside shared code, two meanings become
two classes, as rule 4 of speaking the domain language asks; its
signs of two owners tell that case apart from this
one. This skill decides where whole models part.
Rule. Give each context one owning team, its own model and the data
it changes. Another context never reads that context's tables or
uses its domain classes. It asks through an interface the owning
context publishes, or reacts to an event the owning context
publishes, as
publishing domain events
describes. A table that two contexts write turns every change to that
table into a negotiation between two teams.
Rule. Write down the context map: for every pair of contexts that
talk, which one depends on the other, and how they agree. The
depending context takes the other's model as it is (conformist),
translates it at its own edge (anti-corruption layer), or shares a
small model both teams own and change together (shared kernel); or
the depended-on context publishes one stable interface and language
for every consumer (open host with a published language). A pair that
need not talk chooses separate ways. The map is where a new team
member learns who must be asked before a change.
Default. Where a context depends on a model it does not control,
put an anti-corruption layer in the depending context. One
translator at that context's edge turns the other model's terms into
its own, so no class beyond the translator names the other model. The
translator is an adapter of the kind rule 1 of
inverting dependencies
describes, and it keeps no business decision of its own; it only
translates.
The exception is a model the context is content to adopt, such as a
code set every clinic must use. Take its words as they are, and record
that choice on the map.
Judgement. Sort the clinic's work into core, supporting and
generic. The core is where this clinic differs from others, such as
how it fits urgent patients into clinicians' days; it gets the
richest model and the strongest people. A supporting part, such as
reserving meeting rooms, gets a plain model or scripts. A generic part,
such as payroll or sending mail, is bought or used as a service. What
tips the balance is whether doing the part better than others matters
to the clinic's patients or its business.
Judgement. Keep the core model to what makes the clinic
different. Write the core down in a short statement the team agrees
on, and move generic parts out of the core context into their own, so
the core stays small enough to read. Start with fewer, larger
contexts, and split one when a word's meaning splits inside it or two
teams keep blocking each other's changes. What tips the balance is
the cost of the translation a new boundary adds against the cost of
the coordination it removes.
Pattern
Before, billing's BillableVisit holds Appointment, scheduling's own
class. The fence names Appointment only as a type; its declaration
stays in scheduling's model, outside this example. Billing names
scheduling's model, so each change to Appointment reaches billing, and
billing could send it cancel.
Before:
class BillableVisit
- appointment: Appointment
- invoiceNumber: String?
+ new(appointment: Appointment)
invoiceNumber := null
+ bill(number: String): void
raises VisitAlreadyBilled
if invoiceNumber = null then
invoiceNumber := number
else
raise VisitAlreadyBilled
return
+ invoice(): String?
return invoiceNumber
The rest of BillableVisit is the domain-language reference's class;
only the type of appointment and of its constructor parameter differ.
After, BillableVisit is the domain-language reference's class exactly.
Scheduling publishes AppointmentCompleted after Appointment.complete
commits. Billing's anti-corruption layer is SchedulingTranslator: its
handle creates one billable visit from the appointment's identity and
stores it through BillableVisits.add, billing's own port. DomainEvent
and the handler form handle(id, event) are the publishing domain events
skill's; the EventId is the one its outbox gave the event.
After:
interface DomainEvent
value AppointmentCompleted implements DomainEvent
- appointment: AppointmentId
+ new(appointment: AppointmentId)
+ appointment(): AppointmentId
return appointment
class BillableVisit
- appointment: AppointmentId
- invoiceNumber: String?
+ new(appointment: AppointmentId)
invoiceNumber := null
+ bill(number: String): void
raises VisitAlreadyBilled
if invoiceNumber = null then
invoiceNumber := number
else
raise VisitAlreadyBilled
return
+ invoice(): String?
return invoiceNumber
interface BillableVisits
+ add(visit: BillableVisit): void
class SchedulingTranslator
- billableVisits: BillableVisits
+ new(billableVisits: BillableVisits)
+ handle(id: EventId, event: AppointmentCompleted): void
billableVisits.add(new BillableVisit(event.appointment()))
return
What is stored is one new billable visit, under the appointment's
identity, in billing's own store, in a transaction of its own after
scheduling's change commits; scheduling's data is not touched. The
appointment's identity is the one thing the two contexts share,
published by scheduling for others to hold. The translator's check that
it has not handled the event before (publishing domain events, rule 5)
is left out of the fence.
SchedulingTranslator.handle creates and stores one billable visit, and
no billing class in the After names the Appointment class: the
identifier is all billing holds. Every field is set in a constructor
named for it before a query or handle reads it, and no step runs twice.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- Two teams that must agree on every change to one shared class or
table.
- A class in one context that imports another context's domain classes
outside its translator.
- A word whose meaning changes from one module to the next with no
translation between them.
- A translator at a boundary that holds business decisions.
- The strongest developers working on a generic part, such as sending
mail, while the core waits.
- No written record of which context depends on which.
Common mistakes
- Drawing one context per aggregate or per screen.
- Sharing one model across contexts to avoid writing a translator.
- Letting a bought product's model become the core's model.
- Splitting contexts by technical layer instead of by meaning.
- Translating at the boundary in both contexts, so neither owns the
translation.
Related skills
Further reading
- Context maps
- Core and generic parts
- A worked example of an anti-corruption layer
1---2name: oo-bounding-contexts3description: Use when splitting a large model between teams, choosing how parts with their own models talk, or deciding which parts to build or buy.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-bounding-contexts7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Bounding Contexts1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920A clinic's system grows past one model that one team can hold. Reception21and billing begin with different meanings for an appointment, another22part fills prescriptions, and payroll arrives as a product nobody in23the clinic wants to build. This skill draws the line between parts that24keep a model of their own, says how those parts talk and who must be25asked before a change, places a translator where a part depends on a26model it does not control, and keeps design effort on the work that27makes this clinic different.2829## When to use3031- A model has grown past one team, and a change to it needs several32 teams to agree.33- One word has a different meaning for two separately owned parts of the34 system.35- Two parts with their own models must talk, and nobody can say which36 one depends on the other.37- A part depends on a model that another team or an outside service38 controls.39- The team is deciding which parts to model richly, which to keep plain40 and which to buy.41- A new product or service must fit beside the clinic's model without42 replacing it.4344## When not to use4546- One team owns the whole code and every word has one meaning there:47 there is one model, and no boundary to draw.48- Two meanings of one word share one codebase and one team: they get two49 classes, as rule 4 of speaking the domain language asks.50- The question is which layer or class depends on which inside one51 context.52- The question is the shape or the version of data that crosses a53 boundary already drawn, such as an API's fields.5455## Core rules56571. Rule. **Draw a context boundary where the model's words change58 meaning.** A context is a part of the system whose model has its own59 words and one owner. Inside one context each word means one thing; at60 the line, reception's *appointment* is a booked slot while billing's61 *billable visit* is the visit it prices. Where those two meanings62 meet, two contexts meet. Each context keeps its own model, even when63 both read one table today. Inside shared code, two meanings become64 two classes, as rule 4 of speaking the domain language asks; its65 [signs of two owners][two-meanings] tell that case apart from this66 one. This skill decides where whole models part.67682. Rule. **Give each context one owning team, its own model and the data69 it changes.** Another context never reads that context's tables or70 uses its domain classes. It asks through an interface the owning71 context publishes, or reacts to an event the owning context72 publishes, as73 [publishing domain events](../oo-publishing-domain-events/SKILL.md)74 describes. A table that two contexts write turns every change to that75 table into a negotiation between two teams.76773. Rule. **Write down the context map: for every pair of contexts that78 talk, which one depends on the other, and how they agree.** The79 depending context takes the other's model as it is (conformist),80 translates it at its own edge (anti-corruption layer), or shares a81 small model both teams own and change together (shared kernel); or82 the depended-on context publishes one stable interface and language83 for every consumer (open host with a published language). A pair that84 need not talk chooses separate ways. The map is where a new team85 member learns who must be asked before a change.86874. Default. **Where a context depends on a model it does not control,88 put an anti-corruption layer in the depending context.** One89 translator at that context's edge turns the other model's terms into90 its own, so no class beyond the translator names the other model. The91 translator is an adapter of the kind rule 1 of92 [inverting dependencies](../oo-inverting-dependencies/SKILL.md)93 describes, and it keeps no business decision of its own; it only94 translates.9596 The exception is a model the context is content to adopt, such as a97 code set every clinic must use. Take its words as they are, and record98 that choice on the map.991005. Judgement. **Sort the clinic's work into core, supporting and101 generic.** The core is where this clinic differs from others, such as102 how it fits urgent patients into clinicians' days; it gets the103 richest model and the strongest people. A supporting part, such as104 reserving meeting rooms, gets a plain model or scripts. A generic part,105 such as payroll or sending mail, is bought or used as a service. What106 tips the balance is whether doing the part better than others matters107 to the clinic's patients or its business.1081096. Judgement. **Keep the core model to what makes the clinic110 different.** Write the core down in a short statement the team agrees111 on, and move generic parts out of the core context into their own, so112 the core stays small enough to read. Start with fewer, larger113 contexts, and split one when a word's meaning splits inside it or two114 teams keep blocking each other's changes. What tips the balance is115 the cost of the translation a new boundary adds against the cost of116 the coordination it removes.117118## Pattern119120Before, billing's `BillableVisit` holds `Appointment`, scheduling's own121class. The fence names `Appointment` only as a type; its declaration122stays in scheduling's model, outside this example. Billing names123scheduling's model, so each change to `Appointment` reaches billing, and124billing could send it `cancel`.125126Before:127128```text129class BillableVisit130 - appointment: Appointment131 - invoiceNumber: String?132 + new(appointment: Appointment)133 invoiceNumber := null134 + bill(number: String): void135 raises VisitAlreadyBilled136 if invoiceNumber = null then137 invoiceNumber := number138 else139 raise VisitAlreadyBilled140 return141 + invoice(): String?142 return invoiceNumber143```144145The rest of `BillableVisit` is the domain-language reference's class;146only the type of `appointment` and of its constructor parameter differ.147148After, `BillableVisit` is the domain-language reference's class exactly.149Scheduling publishes `AppointmentCompleted` after `Appointment.complete`150commits. Billing's anti-corruption layer is `SchedulingTranslator`: its151`handle` creates one billable visit from the appointment's identity and152stores it through `BillableVisits.add`, billing's own port. `DomainEvent`153and the handler form `handle(id, event)` are the publishing domain events154skill's; the `EventId` is the one its outbox gave the event.155156After:157158```text159interface DomainEvent160161value AppointmentCompleted implements DomainEvent162 - appointment: AppointmentId163 + new(appointment: AppointmentId)164 + appointment(): AppointmentId165 return appointment166167class BillableVisit168 - appointment: AppointmentId169 - invoiceNumber: String?170 + new(appointment: AppointmentId)171 invoiceNumber := null172 + bill(number: String): void173 raises VisitAlreadyBilled174 if invoiceNumber = null then175 invoiceNumber := number176 else177 raise VisitAlreadyBilled178 return179 + invoice(): String?180 return invoiceNumber181182interface BillableVisits183 + add(visit: BillableVisit): void184185class SchedulingTranslator186 - billableVisits: BillableVisits187 + new(billableVisits: BillableVisits)188 + handle(id: EventId, event: AppointmentCompleted): void189 billableVisits.add(new BillableVisit(event.appointment()))190 return191```192193What is stored is one new billable visit, under the appointment's194identity, in billing's own store, in a transaction of its own after195scheduling's change commits; scheduling's data is not touched. The196appointment's identity is the one thing the two contexts share,197published by scheduling for others to hold. The translator's check that198it has not handled the event before (publishing domain events, rule 5)199is left out of the fence.200201`SchedulingTranslator.handle` creates and stores one billable visit, and202no billing class in the After names the `Appointment` class: the203identifier is all billing holds. Every field is set in a constructor204named for it before a query or `handle` reads it, and no step runs twice.205206## Red flags207208Places to look, not verdicts. A red flag becomes a finding only with209evidence: a measurement, a reproducible bug, or a failing test.210211- Two teams that must agree on every change to one shared class or212 table.213- A class in one context that imports another context's domain classes214 outside its translator.215- A word whose meaning changes from one module to the next with no216 translation between them.217- A translator at a boundary that holds business decisions.218- The strongest developers working on a generic part, such as sending219 mail, while the core waits.220- No written record of which context depends on which.221222## Common mistakes223224- Drawing one context per aggregate or per screen.225- Sharing one model across contexts to avoid writing a translator.226- Letting a bought product's model become the core's model.227- Splitting contexts by technical layer instead of by meaning.228- Translating at the boundary in both contexts, so neither owns the229 translation.230231## Related skills232233- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule234 labels.235- [oo-speaking-the-domain-language](../oo-speaking-the-domain-language/SKILL.md)236 gives two meanings of one word two classes inside shared code.237- [oo-naming-classes-and-methods](../oo-naming-classes-and-methods/SKILL.md)238 keeps one word for one concept inside one model.239- [oo-publishing-domain-events](../oo-publishing-domain-events/SKILL.md)240 publishes the event a neighbouring context reacts to.241- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)242 puts the translator behind a port at the depending context's edge.243244## Further reading245246- [Context maps](references/context-maps.md)247- [Core and generic parts](references/core-and-generic-parts.md)248- [A worked example of an anti-corruption layer](references/worked-example-an-anti-corruption-layer.md)249250[two-meanings]: ../oo-speaking-the-domain-language/references/two-meanings-of-one-word.md#signs-of-two-owners