Notes from the field
Why architecture diagrams lie
Every diagram I've ever been handed on day one was wrong by day two. Not because anyone was careless. Because a diagram describes an intention, and the system has already moved on.
This isn't a complaint about documentation discipline. It's a pattern worth noticing, because of what it implies about trust.
A diagram is a claim, not a fact
A diagram is somebody's best understanding of the system, at the moment they drew it, simplified enough to fit on a slide. That's a reasonable thing for it to be. The trouble starts when it gets treated as a fact rather than a claim — something to build a decision on rather than something to test.
The gap between the diagram and the running system isn't usually where anyone lied. It's where the system quietly changed, and nobody updated the picture, because updating the picture was never anyone's job.
What actually tells the truth
The system tells the truth about itself constantly, if you're willing to look at it directly: the logs, the traffic, the on-call history, the code path that actually executes under load. None of it is as tidy as a diagram. All of it is more honest.
Good technical judgement leans on that evidence first, and treats the diagram as a useful starting hypothesis rather than a verdict.
The reframe
A diagram is a hypothesis about the system, not a description of it. Treat it as one and it stops lying to you — because you stop expecting it to tell you something it was never built to know.