The Architecture Diagram Is Not the Architecture

A diagram can lie.

Not intentionally. But easily.

Boxes look clean. Arrows look simple. Labels look definitive.

Then you inspect the system and find hidden dependencies, manual steps, shared tables, undocumented jobs, batch files, direct database access, retry scripts, and one old service nobody wants to touch.

The diagram was not wrong. It was incomplete.

Architecture is the actual structure and behaviour of the system, not the picture of what people wish it was.

Good diagrams are still valuable. They help people reason, communicate, and align. But they must be treated as living artefacts, not decorations.

A useful architecture diagram should show boundaries, data flow, ownership, failure points, and operational reality.

If the diagram cannot help during an incident, migration, onboarding session, or design review, it may just be technical wallpaper.

Draw the system you have. Then draw the system you want. Do not confuse the two.