Reviews
When is a diagram a liability?
The architecture diagram is the only document everyone believes. A short briefing on the specific ways that belief goes wrong.
By TIS Partners · · 2 min
We begin every review by collecting the diagrams, and we have learned to hold them the way an auditor holds a brochure. The diagram is the estate's most persuasive document precisely because it is the least verified one, and persuasion without verification has a name in our trade: risk.
When does the picture turn against its owners? Three conditions, each common.
When it survives its system. Diagrams are drawn at design time and consulted for years; the system underneath moves weekly. Nobody versions the picture, so it drifts toward fiction at the rate of change, and its authority does not drift with it. The newest engineer trusts it most, which inverts its usefulness exactly. We have watched an incident response route around a service that had been deleted for two years, on the strength of a wall poster.
When it draws the boxes and not the arrows. We have said it before: the boxes are what the organization owns; the arrows are what it suffers. A diagram with twelve labeled services and unlabeled lines between them documents the easy half. The failure modes, the retries, the timeout mismatches, the queue that backs up, all live in the ink the diagram spends least on.
And when it becomes the interface to leadership. The moment executives reason from the picture, the picture acquires political mass: simplifications made for legibility become commitments, the messy exception disappears because it ruins the layout, and eventually the estate is quietly pressured to resemble its own diagram rather than the reverse. The map stops describing the territory and starts governing it.
The fix is not better drawing. It is cheaper honesty: date every diagram like milk, name what it omits in a caption, and keep one "as-observed" view generated from the running system, however ugly, beside every "as-intended" one. The gap between the two views is the most informative artifact in the review. Where it is small, we relax. Where it is large, we have found either the debt or the self-deception, and usually the pair; they travel together, one funding the other.
A diagram is a claim. Treat it like every other claim in this practice: name the conditions under which it is true, and go and look.