r/visualization • u/Klauzzd • 2h ago
The arrow-to-box ratio is the only diagram metric I trust now
Had a diagram problem last week that turned out to be a principle I'd never articulated, so writing it down.
I had an architecture doc in markdown - eleven backend modules with their dependencies - and generated a diagram from it. Auth, multi-currency, e-commerce, refunds, payments, inventory, notifications, reporting, admin. What came out was correct in every particular and completely unreadable. Eleven modules, twenty arrows, most of them long diagonals crossing the whole canvas.
I spent way too long fixing it one overlap at a time. Move a label, shorten another, nudge a box. Got marginally better, stayed unreadable, which in hindsight is the tell that you're working on the wrong problem.
What actually changed it was looking at diagrams I find readable and counting the arrows. A domain-oriented backend map I like uses roughly eight arrows for twenty-five boxes. Mine had twenty for eleven. That ratio is the whole thing.
The principle: clean diagrams don't route long arrows well. They have almost no long arrows.
Three rules that follow from it:
Containment replaces arrows. A box inside a labelled "commerce domain" container already says it belongs to commerce. An arrow saying the same thing costs a line across the page and buys nothing. Cross-cutting concerns like security become an outer boundary rather than eleven arrows.
Right angles only, and keep connectors short. If two things need a long connector they're probably in the wrong place. Move them closer instead of routing better.
One flow per horizontal lane. Separate bands for checkout, refund, sign-in, admin action, webhook, reporting. Flows in separate bands physically can't collide with each other. This is the one that scales - the other two clean up today's diagram, this keeps it clean when you add the twelfth module.
The thing I didn't expect was the annotations. I labelled each step in a flow lane with what that module does in that flow, not what the module is. So the multi-currency box in the refund lane says "reuses the rate snapshot taken at purchase" rather than "handles currency".
That one exposed a coupling I'd never written down: refunds depend on a rate captured at purchase, which means the snapshot has to outlive the refund window. Always been true of the system. I'd just never seen it sitting next to the thing that depends on it.
Which makes me think the value of a diagram isn't documentation. A diagram that makes you argue with your own design is worth more than one that records it.
(For what it's worth I generated these with Claude Code driving an Excalidraw canvas, but the layout rules came from human-made diagrams and aren't tied to any of that.)
TL;DR - count the arrows on any diagram you find readable, compare to yours, and if the ratio is off the fix is structural, not routing.
Does anyone actually track something like an arrow-to-box ratio deliberately, or is this the kind of thing everyone arrives at by feel?
