Context Mapping
Objectives: understand Context Mapping in Domain-Driven Design (DDD), learn how to identify Bounded Contexts, describe their strategic relationships, and choose the right integration pattern.
1. Benefits of Context Mapping
The benefits of Context Mapping are:
- Clarify boundaries between domains
- Make integration explicit (and safer)
- Align teams and communication
- Preserve model coherence
- Inform architectural decisions
- Reduce long-term complexity
It is a sociotechnical view: the code reflects the way teams talk, negotiate, and cooperate.
2. Scope: what we map, what we ignore
A Context Map is used to reason about semantic boundaries and power relationships between subsystems. It does not describe their internals or their infrastructure.
The elements taken into account are:
- Bounded contexts
- The direction of influence (Upstream / Downstream)
- Strategic patterns (ACL, OHS, Partnership…)
- Pivotal terms of the Ubiquitous Language
- Organizational boundaries between teams
Golden rule: if a technical detail changes tomorrow, the map should not change. If the map changes when the business contract between two contexts changes, it is doing its job.
3. The central concept: the Bounded Context
A Bounded Context is an area of the system within which:
- A vocabulary (the Ubiquitous Language) has a coherent and unique meaning.
- A model is valid, applicable, and authoritative.
- A team (or a small group of teams) is responsible for it.
Operational definition: "the perimeter within which a word means what it means".
3.1 How boundaries emerge
The boundaries of a Bounded Context follow human language. Where a word changes meaning, the boundary lies.
Three contexts, three different definitions of "Customer". None is wrong — each is true within its own context.
3.2 Unique concepts vs. shared concepts
- Unique concept: exists in only one context. E.g.: a Support Ticket makes no sense in Marketing.
- Shared concept: carried by multiple contexts, with a model specific to each. An explicit translation is necessary at the boundary. E.g.: Customer, Product, Order.
Rule: a shared concept is not a shared class. It is three different classes that correspond to each other at the boundary.
4. The Ubiquitous Language: the language that defines the boundary
The Ubiquitous Language (UL) is the vocabulary developed jointly by developers and business experts within a Bounded Context.
4.1 The fundamental principle
Same meaning ⟺ same context; different meaning ⟺ different context.
Language is the boundary indicator. When you hear two people use the same word with visibly incompatible meanings, you are looking at two different contexts — whether they are already separated in the code or not yet.
4.2 The UL is local, never global
Classic mistake: wanting a single "company-wide glossary". This ambition always fails, because it denies what DDD has observed: a language naturally emerges at the team scale. Trying to impose it higher up dilutes meaning and hampers autonomy.
4.3 Coherent application
The UL must appear everywhere within its context:
A term that appears only in the documentation but not in the code is a weak signal: either it is obsolete, or it lives in another context.
5. The Context Map: a map of boundaries
The Context Map is the diagram that answers three questions, and only three:
- Which Bounded Contexts exist?
- How are they connected (what pattern, what direction)?
- Where does the translation of shared concepts live?
It is a strategic map. It does not say how a context is implemented; it says where the boundaries are and how they are crossed.
5.1 Several maps are better than one
A large exhaustive map is almost always unreadable. Prefer several focused maps, each answering a precise question:
- Map of the Payment team's dependencies.
- Map of integrations with the legacy ERP.
- Map of contexts affected by GDPR.
5.2 A map is alive
Patterns evolve with team structure, trust between groups, and ownership changes. A map that is not reviewed regularly lies.
6. Direction of influence: Upstream / Downstream / Free
Before choosing a pattern, you need to qualify the nature of the relationship between two contexts. DDD distinguishes three cases.
6.1 Mutually Dependent
The two contexts need each other to succeed. A delivery of one without the other makes no sense.
→ Associated pattern: Partnership (or Shared Kernel in case of very strong coupling).
6.2 Upstream / Downstream
The Upstream (U) can succeed without the Downstream (D). Decisions of the upstream affect the downstream; the reverse is not true.
→ Associated patterns: Customer-Supplier, Conformist, ACL, OHS / Published Language.
6.3 Free
No significant organizational or technical link. Changes in one do not affect the other.
→ Associated pattern: Separate Ways.
Diagnostic tip: ask "If team X disappeared tomorrow, could team Y continue?". The answer classifies the relationship.
7. The nine Context Map patterns
They are grouped into three families of response to the direction of influence: strong cooperation, asymmetric relationship, and avoidance.
7.1 Family A — Strong cooperation
Pattern 1 — Partnership
Two mutually dependent teams coordinate planning and releases. Interdependent features are delivered together.
- Signal: a failure on one side leads to the failure of the other.
- When: shared product objectives, low communication latency, joint planning sessions possible.
- Risk: as soon as communication degrades, the pattern silently drifts toward Customer-Supplier without anyone adjusting the contracts — hence sudden integration failures.
Pattern 2 — Shared Kernel
The two contexts designate an explicit subset of the model that is common to them (a module, a library, a schema). Any modification must be negotiated.
- Signal: two contexts share code or a schema.
- Survival rules: keep the kernel tiny, integration tests with each modification, teams at Partnership level.
- Often: a temporary measure during modernization.
Warning: an undisciplined Shared Kernel becomes the most dangerous coupling in the system — each team pulls it toward itself.
7.2 Family B — Asymmetric relationship
This is the most common family: the majority of inter-team relationships are unbalanced.
Pattern 3 — Customer / Supplier
A formalized Upstream-Downstream relationship where the Customer has real negotiating power: their needs enter the Supplier's backlog.
- Signal: the Downstream can negotiate, prioritize, refuse.
- When: internal teams with SLA, or single customer of the supplier.
Pattern 4 — Conformist
The Downstream fully adopts the Upstream's model, without translation. No negotiation possible.
- Signal: non-influenceable third-party API, imposed legacy.
- When: reasonably suitable upstream model, non-core domain for you.
- Major risk: if conformity extends to a core domain, the internal model becomes "the mirror of someone else's problems".
Pattern 5 — Anticorruption Layer / ACL
The Downstream installs a translation layer that isolates its model from the Upstream's model. It is the inverse of the Conformist: you say "no" diplomatically.
- Signal: you are touching a legacy system, or a "polluted" Upstream, and you are protecting a core domain.
- Cost: implement and maintain the translator.
- Benefit: your Ubiquitous Language stays clean; only the ACL knows the external complexity.
Translation mechanics:
- Stateless: each message or request is mapped independently.
- Stateful: the translator aggregates, combines, or consolidates. It then becomes a mini Bounded Context dedicated to integration.
Pattern 6 — Open Host Service / OHS
The inverse of the ACL, seen from the Upstream side: the latter exposes a standardized protocol designed for the integration of multiple consumers.
- Signal: public API or platform with multiple clients.
- When: the Upstream has the maturity to design a stable public contract and to evolve it (versioning) without breaking the consumers.
Pattern 7 — Published Language / PL
A documented and shared domain language, which expresses what must flow between contexts. Often coupled with OHS.
- Standard examples: iCalendar, vCard, HL7, OpenBanking.
- Signal: formal exchange format, versioned contract.
OHS + PL is "the cleanest way to scale integrations around a central service".
7.3 Family C — Avoidance
Pattern 8 — Separate Ways
Two contexts explicitly choose not to integrate. Duplication is less costly than integration.
- Signal: integration cost > benefit.
- When: peripheral or generic domains, misaligned teams.
- Rare for core domains.
Pattern 9 — Big Ball of Mud
A system (or subsystem) with blurred boundaries, mixed models, and massive technical debt. This is not a pattern to adopt: it is an anti-pattern to contain.
- Action: surround the ball with an ACL to prevent its spread to neighboring contexts.
8. Choosing a pattern: decision tree
Four decision axes are enough for 90% of cases.
| Axis | Question |
|---|---|
| Strength of collaboration | Do the teams communicate frequently? Shared objectives? |
| Power balance | Who controls the contract? Who has to adapt? |
| Domain criticality | Is it a core or peripheral domain? |
| Quality of the upstream model | Is the Upstream model clean or legacy / polluted? |
8.1 Simplified decision tree
8.2 Summary table
| Pattern | Relationship | Who controls | Translation | Typical use |
|---|---|---|---|---|
| Partnership | Mutually dep. | Shared | Negotiated | Co-located teams, same goals |
| Shared Kernel | Strong coupling | Shared | Common code | Modernization, mono-repo |
| Customer-Supplier | Negotiated U / D | Upstream (influenceable) | At the boundary | Internal teams with SLA |
| Conformist | Non-negotiated U / D | Upstream (intransigent) | None | Third-party API, external legacy |
| ACL | U / D, downstream defense | Downstream | Dedicated layer | Core domain facing legacy |
| OHS + PL | U / D, exposure | Upstream | Published contract | Multi-consumer platform |
| Separate Ways | None | N/A | None | Peripheral domains |
| Big Ball of Mud | Anti-pattern | — | Contain via ACL | Chaotic legacy to isolate |
9. Evolution of patterns over time
A pattern is a snapshot. Relationships drift according to human and organizational changes.
| Observed transition | Typical trigger |
|---|---|
| Partnership → Customer-Supplier | Teams separated by time zone or organizational line |
| Customer-Supplier → Conformist | The Downstream is no longer consulted |
| Conformist → ACL | The Downstream becomes a core domain and wants to protect itself |
| Shared Kernel → Customer-Supplier | The kernel grows, becomes unmanageable, and is split |
| Anything → Separate Ways | Collaboration cost > benefits |
Good reflex: review the Context Map with each team reorganization or major change of ownership. Integration frictions are almost always the symptom of an obsolete pattern.
10. Visual notation of a Context Map
There is no rigid standard. A common convention, sufficient for 99% of cases:
- Each Bounded Context is a rounded box.
- A solid arrow indicates the flow of the model (from Upstream to Downstream).
- The labels
U,D,OHS,ACL,PL,SK,PT,CF,C,Sannotate the roles. - A special
/ACL/orOHSbox is placed at the boundary where the translation lives.
With Mermaid:
Reading: Sales undergoes the ERP's model (Conformist), exposes a public API to Support (OHS), and negotiates with Billing. Support protects its model from the ERP via an ACL.