A context diagram draws the boundary, not the insides.
One box for everything you own. The value is entirely in what surrounds it.
A system context diagram is C4 level 1. Your entire system is a single box with no internal detail at all. Around it are the people who use it and the external systems it talks to, with each relationship labelled. The whole purpose is to establish scope: what is ours, what is somebody else's, and where the boundary between them runs. It is the one architecture diagram a non-technical stakeholder can read without explanation, which is what it is for.
Resisting the urge to open the box
The instinct is always to show a little of the inside, and it always makes the diagram worse. The moment your system is three boxes rather than one, the reader starts asking about internals and stops attending to the boundary, which is the only thing this level exists to communicate. Discipline about the single box is what makes it work.
Dependencies you did not choose
Drawing every external system honestly, the payment provider, the identity provider, the legacy system nobody wants to touch, the third-party API with an unclear owner, tends to surface uncomfortable facts. Teams frequently discover during this exercise that they depend on something nobody is responsible for. That discovery is worth more than the picture.
Who it is for
Unusually for an architecture diagram, the audience includes people who do not write code: product managers, security reviewers, procurement, anyone assessing risk. That means no unexplained acronyms and no internal shorthand, and it means the labels on the arrows should say what happens in plain words rather than naming a protocol.
When it changes
Rarely, which is why it is worth maintaining. A context diagram changes when the business changes: a new integration, a retired dependency, a new class of user. That slow rate is exactly what makes it one of the two C4 levels worth keeping by hand, alongside containers.
Questions
Related
- What Is a Component Diagram?Useful for the one container that is genuinely complicated. Drawn far more often than that.
- What Is Agentic Coding?The difference is the feedback loop. An agent can find out it was wrong.
- What Is the C4 Model?Four levels of zoom on one system. Two of them get maintained; the other two usually do not.
- What Is an Architecture Decision Record?The code shows what was decided. Only the record shows what was rejected, and why.
Last updated