Architecture & Technical Design · master area
Bounded Context Mapping
The same word means different things in different parts of the system. A "submission" in Grading is not a "submission" in Billing. Bounded contexts name where the language changes — and put the translation at the boundary, not throughout the codebase.
Owners: Tech Lead Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: The code speaks the brief — each brief, in its own context.
Where it lives in the chain
How to do this
For every service or subsystem, name the bounded context. Inside the context, the language is consistent — "submission" means the same thing everywhere. At the boundary, the language translates — the event published as ExamGraded in Grading arrives in Billing as a GradingFeeDue.
The translation lives in one place — the boundary adapter, the consumer's mapping layer, the event handler. Never in business logic deep inside a service. Code that translates as it goes accumulates two vocabularies pretending to be one, and the bugs all live in the gap.
What good practice looks like
A context map names:
- Contexts — Grading, Billing, Auth, Notifications.
- Relationships —
Customer-Supplier(one team's API is another team's input),Conformist(we accept their model),Anti-Corruption Layer(we translate at the edge). - Shared kernel — the small set of types both contexts know identically (often just IDs).
When a feature crosses contexts, the brief names which contexts. The ADRs in both contexts reference each other. The integration test exercises the boundary. The "submission" in Grading doesn't leak into Billing's vocabulary, and Billing's "invoice" doesn't leak into Grading's.
A team that doesn't name contexts ends up with a big-ball-of-mud monolith where every change touches every other concept, or a distributed monolith where every change requires three teams to coordinate. Bounded contexts are what make a multi-service architecture an architecture, not just multiple services.
Related crafts
- Domain Modelling — the inside of one context
- Integration Design — the translation at the boundary
- Cross-Team Coordination — the human side of context boundaries