More common mistakes to avoid when creating system architecture diagrams
ilograph.com
ilograph.com
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.
A > B > C
The database can live without the web server, but the web server doesn't work without the database.
Therefore webserver ---> database.
Key thing in that these deployment / context / container diagrams don't have a temporal axis. If you want to represent a flow, then you want a diagram where time has directionality, like a sequence diagram.
Basically you're leaving it vague because you can't be arsed to actually work out what it means, and every reader is invited to come up with their own individual wrong assumptions and misunderstandings.
Most of the article's diagrams are actually terrible in this regard.
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.
Unfortunately, the exception is in the "functional block diagram" sections in datasheets, where a more loose format is used.
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
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.
This is why communicating architecture is often as hard if not harder than implementing it.
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.
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.
My reaction to the title was that trying to create the diagram is the mistake. If you can't explain it in prose, simplify.
A diagram is a dense way to express information. The same information in prose would take much longer for a typical human to absorb.
> If you can't explain it in prose, simplify.
Simplify what? The system? Usually you can’t just throw things away from the system to make it easier to describe.
I'd say it's a lossy way to express information. I find that architecture diagrams often cannot express the exact concepts I mean to communicate, so you're left trying to shoehorn concepts into boxes that are somewhat similar, and try to make up for the difference using a couple of cryptic words.
Prose doesn't look as nice, but allows me to describe exactly what I want to say, on any level of detail required. Of course, like with a diagram, you do need to put in significant time and effort to make it comprehensible.
A simplified explanation of the system is by definition lossy. This equally applies to a plain English description.
I’ve been in many design reviews and similar forums where someone has attempted to present a design through written English and finally someone says “we need a diagram here; this is too much to follow” and everyone in the audience nods because they are all lost.
One of the problems with trying to communicate system design with prose is that it makes sense to the person who writes it and has full context, but the audience is often left confused. Diagrams are often easier to follow specifically because they look under specified when they are.
Yes, that happens. I can't remember any occasions where the diagram actually cleared things up though.
Coming to think of it, one way that seems to be pretty effective at getting complex designs across is in an interactive presentation with the presenter drawing on a whiteboard, starting simple and adding stuff while explaining what and why. The narrative is very important though. The whiteboard drawings by themselves are absolutely useless.
I would be very concerned about the quality of the engineers I was working with if they couldn’t produce helpful diagrams.
It’s not coincidental that discussion of system architecture is usually accompanied by diagrams. They should be helpful. And in fact…
> Coming to think of it, one way that seems to be pretty effective at getting complex designs across is in an interactive presentation with the presenter drawing on a whiteboard, starting simple and adding stuff while explaining what and why.
You seem to agree that they are helpful.
> The whiteboard drawings by themselves are absolutely useless.
This seems like sort of a straw man, though. I don’t think anyone advocates for system diagrams in the absence of any context.
My point is that I see value in interactively building up a diagram together. The final artifact, even when provided with context in the form of prose, I've never found to be actually helpful. Apart from good looks of course.
You can't throw away requirements, but sometimes there don't need to be as many moving parts behind the curtain as you think in order to implement those requirements.
If you have a complex system, whether due to legacy or due to actual necessity, you aren’t going to redesign the system just for the sake of simpler explanation. Indeed if someone couldn’t explain the system in its current state I would have zero confidence they could successfully simplify it.
I was not considering the case of documenting already existing systems, just talking about the planning stage. Your point is well taken.
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.
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.
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.
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.
I still struggle with finding the best approach each time; I'd love more discussion of this stuff.
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.
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.
> 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.
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 for your naming, I would probably have something like "Unnormalized orders", "normalised orders", "queued orders", but obviously I can't tell without much more information.
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.
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 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...
- 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.
What a TERRIBLE way to store information in an AI era. Diagrams are so...human.