Skip to main content

Drawing a Context Map

What This Concept Is​

A context map is a single diagram that shows every bounded context in a system and every relationship between them. On a real team, it is the most valuable strategic-design artifact you can produce: one page that tells another engineer how the system is carved and who talks to whom.

A context map has four required pieces of information per edge:

  1. Upstream (U) and downstream (D) direction. Who serves whom.
  2. Relationship pattern. One of the six from concept 4 (partnership, shared kernel, customer-supplier, conformist, ACL, separate ways) often plus a translation pattern (ACL / OHS / published language).
  3. Integration style (optional but useful). sync call / async event / shared library / batch / file.
  4. What crosses. The key event or resource names.

It also has two required pieces per box:

  1. Context name.
  2. Team or owner (so the diagram doubles as organizational reality).

Why It Matters Here​

A context map is the artifact your ADRs, architecture reviews, and service-boundary decisions refer back to:

  • architecture reviews use it to spot orphaned or overloaded contexts
  • ADRs use it to show "what changes" when a decision lands
  • onboarding uses it as the first page every new engineer reads
  • during incidents, you use it to trace where corruption or delay could have entered
  • when a new feature arrives, you use it to decide which context should own it

A system without a current context map is a system whose boundaries are whatever the last commit pretended they were.

Concrete Example​

Parcel Shipping Co. -- full context map (ASCII)

                        +----------------------+
                        |      Okta (gen)      |
                        | ext identity provider|
                        +----------+-----------+
                                   |  D  (JWT)
                                   v   Conformist (all contexts consume)
  +--------+    U   CS    +------------------+   U Partnership   +---------------+
  |Pricing | -----------> |     Shipping     | <---------------> |   Tracking    |
  |(core)  | <----------- | (supporting)     |                   |   (core)      |
  +---+----+   Shared     +------+-----------+                   +------+--------+
      |   Kernel rate-lib        | U  CS (ShipmentBooked,               |
      |                          |     ShipmentLabeled events)          |
      |                          v                                      |
      |                 +---------------+   U  OHS  (AsyncAPI)          |
      |                 |    Billing    | <------------------------+    |
      |                 | (supporting)  |                          |    |
      |                 +-------+-------+                          |    |
      |                         | U CS                             |    |
      |                         v                                  |    |
      |                 +---------------+                          |    |
      |                 |   Support     |                          |    |
      |                 | (supporting)  |                          |    |
      |                 +---------------+                          |    |
      |                                                            |    |
      |                                                            |    |
      |    ACL: ContractEngineACL                                  |    |
      +--------->  [[ Legacy ContractEngine v1 ]]  (Conformist)   |    |
                                                                   |    |
                             +--------------------+                |    |
                             |  Carrier Gateway   |  (OHS)         |    |
  [[ FedEx / UPS / DHL ]] -->| (supporting)       +----------------+----+
        Conformist           +--------------------+  Published Language
                                                      carrier.scan.v1
                                                      carrier.handoff.v1

The same map as Mermaid (renders in Docusaurus):

Reading the map​

  • Core in the middle. Core subdomains (Pricing, Tracking) sit centrally. Everything else supports them.
  • External boxes have distinctive shapes. [[ ... ]] in the ASCII diagram and [[ ... ]] in Mermaid mark systems we do not own. We conform to them.
  • Edges name the pattern. Not the transport. Not the team chat channel.
  • Translation patterns are on the edge label too. ACL, OHS + Published Language tell the reader which side translates.
  • Shared Kernel is drawn as an undirected line because both sides are jointly responsible.

Versioning the map​

Context maps must be versioned like code:

  • live in the main repo or architecture repo
  • Mermaid source (not PNG) so it diffs cleanly
  • each significant change is an ADR ("ADR-2026-014: Introduce Tracking Context")
  • every quarter the map is walked in a review meeting
  • onboarding docs point to the latest map, not a screenshot

What a bad context map looks like​

  • no direction arrows (you cannot tell upstream from downstream)
  • edge labels are service names ("POST /shipments") rather than relationships
  • "microservices" drawn as separate boxes even when they share a database
  • missing external systems (Okta, Stripe) because "they are not our code"
  • one giant box labeled core with no internal structure

If someone hands you a diagram with any of these, ask the four questions in the "How To Use It" section below and watch the issues surface.

Common Confusion / Misconception​

"A context map is a system diagram." Not quite. A system diagram shows components; a context map shows model boundaries and their relationships. Two services that share the same ubiquitous language and database are one bounded context on a context map even if they are two components on an infra diagram.

"I will just generate the map from the service registry." You cannot. Relationship patterns (partnership vs conformist) are not visible in traffic logs; they are social facts about how the teams work. You have to ask.

"Every edge needs all six pieces of information." You need the direction, the relationship pattern, and what crosses. Integration style and translation patterns are nice-to-haves that sharpen the map.

"It should be drawn once by the architect." It should be drawn by the architect and then maintained jointly. The DDD convention is that each team maintains its own outgoing edges. Central authorship causes the map to rot.

"Context maps are just pretty pictures." A review-quality context map saves entire discussions. If you are about to debate "should this new feature go in Shipping or Tracking?", the map often answers it in 30 seconds.

How To Use It​

To produce a new context map:

  1. List every bounded context with owner.
  2. Draw arrows for every integration you know about.
  3. For each arrow, name the relationship pattern (partnership / shared kernel / customer-supplier / conformist / separate ways).
  4. Add translation patterns (ACL / OHS + published language) where present.
  5. Mark external and generic subdomain contexts visually different (double box, different color, [[ ]]).
  6. Ask four questions of every edge, in front of a colleague:
    • "What does the consumer break if the producer ships tomorrow?"
    • "Who decides contract changes?"
    • "Where does translation happen?"
    • "What crosses the wire -- events, calls, files?"
  7. If any answer is "I don't know," that is an edge that needs an ADR before anything else.
  8. Commit the Mermaid source. Link it from the module/service READMEs.

Check Yourself​

  1. Name two things an architecture diagram shows that a context map does not.
  2. Why does a context map need to show external systems and generic vendors even though we do not write their code?
  3. If an edge has no owner, whose job is it to name the relationship?

Mini Drill or Application​

Draw the context map for one of:

  • Parcel Shipping Co. -- extend the map above to add a new Returns context that handles return-label generation and reverse-pickup scheduling. Decide: which existing contexts does it talk to? What relationship pattern on each edge?
  • Conference Ticketing -- produce a 6-8-context map from scratch covering: Ticket Inventory, Orders, Check-in, Payments (Stripe), Organizer Analytics, Notifications (Twilio + SendGrid).
  • Your own system -- draw the real map your team is working with today. Show it to a colleague and fix whatever confuses them.

Produce:

  1. the Mermaid source
  2. a 1-page "reader's guide" pointing out the 2-3 edges you think are fragile
  3. at least one edge where you intentionally upgraded the pattern from conformist to ACL-protected or downgraded from partnership to customer-supplier, with reasoning

Read This Only If Stuck​