In practice, how do teams actually produce a context map for a real system — as opposed to a greenfield whiteboard exercise — and what keeps it from going stale once it's created?

## Why an existing system is a different exercise Producing a context map for a system that already exists is a different exercise from sketching one for a greenfield project, and the difference matters because existing systems accumulate integrations that nobody remembers documenting. ## Phase one — ground-truth discovery The mechanism starts with ground-truth discovery rather than intention: instead of asking *'what did we design?'*, the team asks *'what is actually talking to what, right now?'* Concretely, this means walking through real evidence: - API gateway logs - service-mesh traffic graphs - message-broker topic subscriptions - shared database access grants - cron or batch job configurations that read another context's tables That evidence matters because relying only on architecture diagrams or team-provided descriptions reliably misses informal or legacy integrations added under deadline pressure that never got written down. A common outcome of this discovery phase is finding integrations nobody currently on the team remembers building, especially in systems with multiple years of history and turnover. ## Phase two — the cross-team session Once the actual integration points are inventoried, the next mechanical step is a shared session — a workshop, in person or on a virtual whiteboard — with a representative from every team whose context appears on the map. This is not optional scaffolding; it's structural to getting an accurate map, because direction is often as much a matter of organizational reality as of technical design, and only the people actually doing the day-to-day adapting on each side reliably know which way that really runs. A single architect building the map alone from documentation will produce a technically plausible but frequently wrong picture, especially around edges that are contentious or where teams have quietly worked around an official contract with an unofficial one. The session's job is to: 1. walk each discovered integration; 2. agree on which context is upstream; 3. name the team that owns each context; 4. flag genuinely disputed edges as open questions rather than force a false consensus. ## Why both phases exist The reason this two-phase approach exists is that a context map's entire value depends on it matching reality closely enough that people can safely make decisions from it. A map built purely top-down from an idealized architecture, without checking it against what code and traffic actually do, produces a document that looks authoritative but silently misleads anyone who trusts it — which is arguably worse than having no map, because a wrong map creates false confidence that leads to unpleasant surprises. ## The trade-off The trade-off here is time and organizational effort against staying honest. Chasing down real traffic evidence and getting a room with every relevant team is expensive, especially in a large organization, and it's tempting to shortcut it by having one team write the map from what they believe is true. That shortcut is cheap up front and expensive later, when the map turns out to disagree with reality at exactly the edges that matter most — which are, not coincidentally, also the edges most likely to cause an incident. ## What keeps it from going stale What keeps a map from going stale is treating it as a living artifact with an accountable owner and a defined trigger for revisiting it, rather than a one-time deliverable filed away after a kickoff workshop. In practice this looks like: - **assigning ownership** per major area; - **tying updates to concrete events** rather than a vague 'keep it current' aspiration — a new service launching, a team reorg that changes who owns what, or a production incident that reveals an undocumented dependency should each trigger a map update; - **reviewing it on a regular cadence** even absent a specific trigger, since drift accumulates from many small, individually unremarkable changes. Some organizations wire this into their engineering process by requiring a context-map diff as part of the review for any change that adds a new cross-context integration, which catches drift at the moment it's introduced. ## A concrete scenario A concrete scenario: a mid-size company doing its first mapping exercise on a five-year-old system discovers, by grepping for outbound HTTP calls and reviewing message-broker subscriptions, three integrations that don't appear in any architecture document — including one where a Reporting context reads directly from Order Management's production database because a report needed a field the API didn't expose. The mapping session doesn't just note this as U/D; it flags it as a risk to be addressed, and going forward, that discovery becomes the trigger that gets the team to add 'new integration = map update' as an explicit step in their pull-request checklist.