Stackbook Logo
architecture-descriptionestablished · low operational burden

Context Mapping

Also known as: context-map, ddd-context-map

Intent

Document and choose the relationships between bounded contexts so that integration and team dependencies are explicit.

Problem

Bounded contexts are defined but their relationships remain implicit, so integration happens ad hoc through shared databases, copied models, and unspoken dependencies. Teams are surprised when upstream changes break them.

Forces

  • •Contexts must integrate despite different models
  • •Power and dependency between teams are unequal
  • •Integration style determines coupling and cost
  • •The map must stay current to be useful

Solution

Overview

A context map is a high-level view of how bounded contexts relate. It records both technical integration and the organizational relationship behind it, such as who can demand changes from whom.

How it works

Identify each context, then label each link. In an upstream-downstream link, the upstream decides what is published and the downstream consumes it.

[Catalog] --OHS/PL--> [Ordering] --customer/supplier--> [Billing]
                           |
                      ACL  v
                    [Legacy ERP]
[Ordering] <==partnership==> [Inventory]

Relationship types in short:

  • Partnership: two teams succeed or fail together and coordinate releases.
  • Shared kernel: a small shared model both teams own and change jointly.
  • Customer-supplier: downstream needs influence upstream planning.
  • Conformist: downstream adopts upstream's model without influence.
  • Anti-corruption layer: downstream translates upstream's model.
  • Open host service with published language: upstream offers a stable, documented protocol to many consumers.
  • Separate ways: no integration at all.

Pitfalls

  • Treating the map as a diagram exercise instead of a decision tool.
  • Defaulting to shared databases because they are easy.
  • Choosing a shared kernel that grows until contexts are effectively one.
  • Ignoring conformist relationships with dominant vendors, which is often realistic but should be a conscious choice.
  • Not recording which team owns each relationship.

Key takeaways

  • Label every integration with an explicit relationship type.
  • Show upstream and downstream direction.
  • Protect downstream contexts with an ACL where the upstream model is poor.
  • Revisit the map whenever teams or contracts change.

✓ When to Use

  • •Multiple bounded contexts or teams must integrate
  • •Planning a monolith decomposition
  • •Diagnosing recurring cross-team integration pain

✗ When Not to Use

  • •A single context with one team
  • •As a one-time diagram never revisited
  • •When contexts are not yet identified

Pros

  • +Makes dependencies and power dynamics visible
  • +Guides integration style choices
  • +Shared vocabulary for architecture discussions

Cons

  • −Needs upkeep or it becomes stale
  • −Organizational realities can be uncomfortable to document
  • −Does not by itself fix integration problems

Cost Profile

Infrastructure

None — documentation and design

Operational

Low

Cognitive

Medium — requires DDD vocabulary

Failure Modes

  • Map drawn aspirationally rather than reflecting reality

  • Conformist relationships adopted unknowingly, importing foreign models

  • Map never updated after reorganizations

Real-World Examples

Alternatives

    Related Patterns

      Competency Domains

      requirements constraintsdistribution communication