back
70 comments
The most common mistake I've seen is not agreeing on what arrows represent: control or data. Does A-(customer data)->B mean A asks B for data or A sends customer data to B?

Of course, sequence diagrams make it clear with two separate arrows when control and data flow in different directions, but a lot of diagrams are of the "plain old boxes and arrows" variety.

This is why the C4 Model insists on using verbs to label interactions. (e.g. “reads/writes data from”, “sends reports to”, etc).

Most of the article's diagrams are actually terrible in this regard.

This is an older discoery than that. Expert systems back in the day often modeled knowledge as graphs with the arrows being labeled with the specific relationship between the things.

It works because (node, edge, node) triplets then form propositions, the fundamental units of knowledge

Come to think of it, expertise researchers still do this today to make rough sketches of domains of study. The result is called a concept map.

C4 is great, even if I can't be bothered to model every layer
This is what I like about electronic circuit schematics: there is only one way to interpret them.

Unfortunately, the exception is in the "functional block diagram" sections in datasheets, where a more loose format is used.

The one solution that works for me is to color code each arrow and at the top left of the diagram add a legend that describe what each colored arrow represent.

This way sometimes the color can describe control, data, and sometimes even teams expected to implement this arrow by color coding teams.

The latter is very helpful for cross team meetings to make each group focus on the part of the diagram that will affect them the most, and give pointed feedback to assumptions and lack in specs

One company I worked for solved this by agreeing on "triangle-headed arrow ⭢ means control, barbed arrow 🡒 means data" and putting this into the legend. "Calls REST endpoint to get customer data" would then be a double-headed arrow.
Colors are not an adequately accessible differentiator.
There is in fact a 3rd: build time dependencies.

Control: Object/module/function A calls object/module/function B.

Data: The call can either push or pull data.

Build dependency: The call can be direct (A depends on B) or indirect through an interface/callback/etc (both A and B depends on the interface).

Ideally every design document includes all 3 as separate diagrams.

In high-level diagrams, which I think is what is being discussed here, I like to think that A --> B means that A "uses" B in some way, and leave it at that.
Yup, we had exactly those hangups when diagrams showed data flowing from restricted network system to data lake. The data is generated and owned by the system and the lake has a secondary copy, except the physical implementation is that the lake opens a connection and pulls. Somehow that is forbidden and we spent months fighting firewall people. Fortune 50 is fun.
Yeah, you're gonna need separate sequence diagrams.
The biggest mistake is not knowing your audience.

Is the diagram for marketing? A sales proposal? A business person using the product? Technical peer?

If you don't know this, you don't know if you have the right level of detail.

Underrated comment in this thread, which is full of asserts of universal abstractions and patterns which are not universal. (And of course this insight applies to all kinds of written communication, diagrammatic or prose...)
Idk, while system architecture diagrams look cool and feel informative, I generally don't feel like they actually help you get started working somewhere on a project. Mistake #3 in this article, putting too much in, is part of this.

So https://www.jerf.org/iri/post/2025/on_layers_and_boxes_and_l... is an interesting take: put links in your diagram, so it functions as a table of contents. This seems most useful for someone who needs to start working on a project.

Similarly https://haskellforall.com/2026/02/browse-code-by-meaning asks how to show what's in a repo, but maybe file tree is not best and a diagram with links as table of contents is the answer.

That said practically speaking, I'm not sure what tooling easily creates working links in a diagram that looks good in any context, for instance mermaid might render on github but not a text editor.

Of course for other purposes maybe just go crazy with the diagram. I once had a coworker draw this super detailed master diagram, maybe 50-100 things on it, which I was told impressed senior government officials (after my manager recolored all the red to avoid connoting errors). But for the purpose of orienting developers a table of contents with links sounds better.

> Idk, while system architecture diagrams look cool and feel informative, I generally don't feel like they actually help you get started working somewhere on a project.

My reaction to the title was that trying to create the diagram is the mistake. If you can't explain it in prose, simplify.

>Idk, while system architecture diagrams look cool and feel informative, I generally don't feel like they actually help you get started working somewhere on a project.

Can't speak to that, but they're enormously helpful in reviewing the security architecture of a design, especially when you're doing this at scale and might only get a few hours to look into a given project.

This is just an advertisement for their service.

In my 20 years in this field I can easily count on one hand the times a diagram like this has been useful. I’ve seen more cases where they were clearly created to satisfy some exec that wanted to see it and never updated again.

If you are doing any architectural work, whether at the software or infrastructire level, I fail to see how you can deal without diagrams to 1/ understand interactions between all system components 2/ make your changes understood and validated by relevant people.

Granted I speak about real, useful, technical diagrams, whose purpose is to convey useful information and highlight data flows. Not marketing diagrams you may find on marketing presentations, but this is not what this discussion is about.

To me the biggest issue is keeping it all up to date. For that reason I've completely shifted to text-to-diagram tools like PlantUML / Mermaid. As imperfect as they are, they mean you can insist the diagrams are updated in the same commit (or merge request) as the code, and the AI tools are pretty good at working with them too.

I am pretty frustrated at times though with PlantUML / Mermaid. They just do not give enough power to format the diagrams in a human legible way. Am curious what others do for more complex diagrams in this regard.

Have you tried C4-PlantUML? It actually has functions for manually adjusting the layout when it doesn't do what you want.
As the resident Diagram Maker at my job I really appreciate any and all discourse on the topic. Knowing the purpose of your diagram is a hugely under-appreciated part of the process. Service flow chart or system architecture? High level system overview or actionable, followable flow-chart? The engineer in me always wants to put All The Things in the chart, to make it maximally "correct". It's never the right move. But how to make it clear what's included or not, and why?

I still struggle with finding the best approach each time; I'd love more discussion of this stuff.

Just because you said that you were interested in some Opinions, one of the least appreciated aspects of any documentation (but especially diagrams) is defining who the stakeholders are at the start of the document. It’s the difference between having frustrated users who can’t understand things to happy users that understand limitations.

The corollary to this is that the best diagram that boundaries are often along communication lines between teams. This is Conway’s law all the way down. And the reason is that most often people use diagrams to get a spatial sense of where ‘they’ fit into things. I have only anecdotal evidence for this, but the most helpful and lasting diagrams I’ve ever made are when 1) they define (and stick to) specific stakeholders, and b) they are delineated by groups/teams.

Multiple interlinked diagrams? A whole bunch of diagrams at different levels, from different perspectives all designed to answer different questions?
Diagrams are communication tools, and are best done with a target and goal in mind. The C4 framework is good for addressing multiple levels of abstraction and different types of viewers. The business execs don't need the level of detail that someone debugging the system does.
One common mistake when pointing out common mistakes: Show the good example!
Their master diagram example in #3 contains a #2 mistake with an unconnected resource (the stripe account). Maybe a double validation of why the master diagrams can be hard to maintain.
The main one i would add is a lack of symmetrical alignment. the point of a diagram is to create a shared abstraction for reasoning about a system or set of problems. The point of that is to scale work on it to other minds. It should enable others to parse it and ask useful questions.

If your diagram is ugly, you're probably mixing levels of abstraction without acknowledging it. It's a forcing function on articulating what you know and what is outstanding. Something that is black boxed should be referenced as a black box.

I use a lot of data viz because it's a high bandwidth way to show relationships, dynamics, order of complexity and its location, information problems, scope, and de-noise data. So much can be explained by having AI make you a uml sequence diagram of a concept. it is unreasonbly effective. If you are making a "chart for management" and using powerpoint or native excel charts, you're probably creating garbage though.

Couple of comments:

> This can be as simple as adding a type suffix to a resource name (e.g. Orders Table, Results Bucket)

Don't encode types in names. And I disagree somewhat that the names are really needed at all.

> Making a “master” diagram

I think such a diagram is useful but obviously each top-level "box" in it doesn't need to contain all sub-components.

>Don't encode types in names.

Why? Hungarian notation probably is probably going too far, but in cases where a single word is heavily overloaded encoding types is helpful (eg. image file, image table, image bucket).

And I disagree somewhat that the names are really needed at all

You want a diagram containing only icons? You will still need a legend somewhere that explains what each icon means, otherwise you will end up with at least as many interpretations of the diagram as there are readers of it.

And I'd say that that first image as shown is virtually useless anyway. There is little value in just laying out resource components without linking them to system operation in some way -- which means that that diagram can only be understood in its larger context, and that's typically not how diagrams are used: they end up being the main focus of discussions.

> Meaningless animations

As someone who usually hates animations, in the example given I actually find them useful, assuming that they are representative of the actual flow. They are also unobtrusive because they are steady-state.

I agree. I think it gives a quicker view of what is happening and for some subset of diagrams I have wanted to use tools that do more of this to help people build a mental model.
Same for me. The arrows are so small I can’t even see them on my phone, but animation makes direction clear.
I generally have given up on diagrams. Systems and flows I work with are too convoluted to be mapped out. Only the simplest of flows can be diagrammed and it usually leaves out important facts. When dealing with non technical people, I have found out through trial and error that excel works best. I start out with sample data on one sheet and walk them through the various transformations in sheet2, sheet3 etc. I even create a table of contents that has links to the different sheets. In a phrase, seeing data is believing.
I’ve always used a simplified UML style[0], even for system diagrams. OmniGraffle is an essential tool, for me.

I spell out what arrows and line types mean. I don’t rely on conventions, as I find “pure” UML to be something that most folks don’t know, so I”m basically writing in hieroglyphics.

[0] https://littlegreenviper.com/the-curious-case-of-the-protoco...

The worst ones are diagrams that look clean but hide all the decisions that actually matter. A messy diagram that shows the real tradeoffs is more useful than a pretty one that lies
Once worked with a systems architect who intentionally disorganized their flow diagrams by just moving nodes in their flow to random places (hi Dan!). The only reason I can think of why he'd do that is to maintain job security by keeping the junior apps folk confused.
The Slack notification flowchart is an old favorite: https://slack.engineering/reducing-slacks-memory-footprint/
Most common mistake: Creating diagrams in a graphics program without semantics. Why not write your "diagram" in code or at least some structured format?

- LLMs can read and write it, it serves as valuable context

- Always up to date, rendered on demand

- source controllable

- editable (thus will actually get edited)

Most architectural diagrams I see are just images with no source or semantics. Strictly less useful and more prone to rot.

I really miss a mistake which I see a lot: a simple frontend (the architecture component) talking to backend (also an architecture component). I had to put extra effort all the time to explain the "no, people, a static web server is not sending anything to anywhere, it just serves static files".
My thought process is that a diagram should stand on its own and should be understandable by non technical business people. I always have callout notes as stickies on the diagram explaining what it does.
Route53 being off on the side but unconnected is still valuable info...
Architecture diagrams are the bane of my existence right now. I sit there and listen to engineers opine on the different types, levels, details, etc. And all I can think is...

What a TERRIBLE way to store information in an AI era. Diagrams are so...human.

At my company, diagrams are usually generated from data. But when they are not, they are immediately extracted from the diagram authoring database and become data again, that we query for discrete information [much more than scrolling inside wall-size diagrams]