In Domain-Driven Design, what is a context map, and what three things does it typically show about a system made up of multiple bounded contexts?

## What a context map is A context map is the artifact in Domain-Driven Design's strategic design toolkit that shows the complete topology of a system: - **every bounded context** that exists - **how they are connected** - **which direction of influence** runs across each connection - **which team is accountable** for each piece Where a single bounded context's internal model is described by an ubiquitous language and a domain model, the context map operates one level up — it says nothing about the classes or tables inside any one context, and everything about how the contexts relate to each other as **black boxes**. ## How one actually gets drawn Mechanically, building one starts by inventorying every bounded context that currently exists (or is planned), which typically requires talking to every team rather than relying on a single architect's mental model, since in any organization past a certain size no individual has accurate knowledge of every integration. For each pair of contexts that actually exchange information, the team draws an edge and labels it with an **upstream/downstream** (`U/D`) designation. The information exchange might be: - a REST call - a published event - a shared database table - a nightly batch export Determining direction is done by asking a single diagnostic question: **which side has to change its model to accommodate the other?** The context whose model the other side must adapt to is **upstream**; the one that adapts is **downstream**. This is often as much an organizational fact as a technical one — the team with more leverage, an earlier deadline, or ownership of a widely-consumed platform tends to become upstream by default, whether or not that's the technically ideal arrangement. ## Why the artifact exists The reason this artifact exists is that integration knowledge, left implicit, doesn't scale past a handful of teams. Each bounded context can be designed with perfect internal consistency and still produce a system that fails, because bounded-context-level design says nothing about the **seams** between contexts — and it's precisely at those seams that most large-system defects, miscommunications, and unplanned coupling occur. A context map forces those seams to be enumerated and named in one place any engineer, new hire, or manager can consult, rather than living as tribal knowledge scattered across chat threads and the memories of whoever built the original integration. ## The trade-off The main trade-off is the cost of producing and — more importantly — maintaining the map against the value of the shared understanding it buys. - Drawing a context map is **genuinely useful up front** on a system with several teams, because it lets teams negotiate contracts before any code is written, which is cheaper than renegotiating after the fact. - But **it is easy to over-invest**: spending weeks producing an exhaustive map before writing a line of code delays feedback and often documents assumptions that turn out wrong once real integration work starts. The map's value is proportional to how current it stays, not how detailed it originally was. ## Failure modes That maintenance cost is also the map's principal failure mode. 1. **Drift.** A context map drawn once during a kickoff and never revisited drifts from reality as contexts split, merge, or grow new integration points — and a stale map is arguably worse than no map, because it creates false confidence. A team that trusts an outdated map may believe an integration doesn't exist, ship a breaking change, and only discover the real coupling when production breaks. 2. **The wrong granularity.** A related failure is drawing the map at the wrong granularity: too fine (one box per microservice or table) turns it into an architecture diagram that obscures the model boundaries it's supposed to reveal; too coarse (one box for an entire department) hides exactly the seams the exercise exists to surface. 3. **The wrong room.** A third failure is drawing the map without the engineers who actually build the integrations in the room — architects sketching a map from documentation alone routinely miss the informal, undocumented channels that are often where the real coupling and the real incidents live. ## Putting it on one page A concrete example: an e-commerce platform with separate Order Management, Inventory, Shipping, and Billing contexts might have a context map showing: - **Order Management upstream of Shipping** — Shipping conforms to the schema of an `OrderPlaced` event Order Management publishes. - **Inventory upstream of Order Management** — for a synchronous stock-reservation call. Drawing that map in one place lets a new engineer, or a leader deciding where to add headcount, see the whole system's shape at a glance — something no individual context's documentation could provide on its own.