Context Diagrams

Definition

One box for the system, surrounded by the people who use it and the external systems it exchanges data with. No internals.

Why it is the highest-value diagram

• It almost never goes stale. External dependencies change far more slowly than internals.
• It defines scope, which is what most disagreements are actually about — "is that in our system?" is settled in one look.
• It reveals dependency count, which is the best quick proxy for integration risk.
• Any audience can read it, including executives, auditors and new joiners.
• It takes fifteen minutes.

What to include that most people omit

• The direction of each dependency, and who initiates.
• What flows, in one phrase per arrow.
• What happens when each external dependency is unavailable — one line each. This turns a scope diagram into a resilience artefact, and it is where most of the value is.
• The nature of each relationship: synchronous call, batch file, event stream, human process.
• Anything outside your control, including third parties and other teams' systems — those are the boundaries where the interesting failures live.

The use it is best at

Onboarding and incident response. A newcomer needs to know what the system talks to before anything else. An incident responder needs to know which external dependency could be causing this.

Both audiences are poorly served by a detailed internal diagram and well served by this one.

Failure scenarios

• Internals leaking in, so it becomes a container diagram and loses its stability.
• Dependencies omitted because they are "just" a shared library, a scheduled job, or an identity provider. Those omissions are exactly what causes surprise during a migration or an outage.
• No failure behaviour recorded, halving its value.
• Undated and unowned.

Interview question

"What belongs on a context diagram that most people leave off?"