March 22, 2026
Boxes, arrows, and internet beef
More common mistakes to avoid when creating system architecture diagrams
Designers roast pretty diagrams, argue over names, arrows, and the “master map”
TLDR: A new guide calls out common diagram fails—unlabeled parts, unconnected boxes, and overloaded “master maps.” Readers clap back with hot takes: honesty over polish, a fight over naming rules, confusion over arrow meanings, and a hilarious catch that the article’s own example breaks its rules.
Another day, another diagram drama. A new guide warns builders to stop making the same architecture mistakes: unlabeled parts, lonely boxes that connect to nothing, one giant “master map” that tries to show everything at once, and oversimplified “conveyor belt” flows. The community? Absolutely on fire. One top comment calls out the industry’s obsession with neat graphics over truth, saying messy-but-honest beats pretty-but-misleading. Cue applause and a thousand bookmarked rants.
Then the naming war breaks out. The post says: label each piece with a clear name, not just its type. But a contrarian counters, “Don’t encode types in names,” and even floats that names may not be necessary. Meanwhile, a pragmatist crowd chimes in: tailor your diagram to your audience, and use the C4 model to show different zoom levels—big picture for execs, gritty detail for fixers.
The spiciest subplot? Arrow chaos. One commenter asks the existential question: does an arrow mean sending data or asking for it? Without rules, diagrams become vibes. Bonus drama: a reader spots the article’s own example committing the “unconnected box” sin—an orphaned Stripe account—sparking giggles and a collective facepalm. The moral: diagrams are for humans—show the tradeoffs, pick the right view, and stop drawing fairy tales.
Key Points
- •Omitting resource names creates ambiguity; include both name and type when possible.
- •All resources in architecture diagrams should be connected to show relationships and purpose.
- •Avoid “master” diagrams that attempt to show an entire system; instead, use multiple perspectives.
- •Model-based diagramming can share resources across perspectives to preserve connections.
- •Behavioral diagrams should reflect real interactions, including round trips and orchestrations, avoiding oversimplified linear flows.