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.
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.
zahlman 2 hours ago [-]
> 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.
dpark 1 hours ago [-]
A picture’s worth a thousand words.
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.
vanviegen 1 hours ago [-]
> A diagram is a dense way to express information.
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.
dpark 39 minutes ago [-]
> I'd say it's a lossy way to express information.
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.
zahlman 55 minutes ago [-]
> Usually you can’t just throw things away from the system to make it easier to describe.
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.
dpark 36 minutes ago [-]
This is essentially a statement that the system shouldn’t be unnecessarily complex. And sure, but that’s not really relevant to the discussion.
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.
zahlman 27 minutes ago [-]
My point was that the attitude of being able to explain systems by drawing them, leads to over-architecting them. If you stick to prose then you can't as easily delude yourself about the complexity by staring at pretty pictures.
I was not considering the case of documenting already existing systems, just talking about the planning stage. Your point is well taken.
stronglikedan 59 minutes ago [-]
Some stakeholders will gain more understanding from a diagram than any amount of simplified prose, so both are typically helpful.
orthoxerox 5 hours ago [-]
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.
HotGarbage 4 hours ago [-]
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.
kqr 1 hours ago [-]
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.
cenamus 3 hours ago [-]
C4 is great, even if I can't be bothered to model every layer
NalNezumi 3 hours ago [-]
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
pepperoni_pizza 3 hours ago [-]
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.
zabzonk 4 hours ago [-]
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.
segmondy 4 hours ago [-]
yup, A interacts with B with the interaction originating from A.
chrisweekly 40 minutes ago [-]
related tangent
(outside of diagrams)
lt < and gt > symbols are often dangerously ambiguous; does
A > B > C
mean "A then B then C"?
or "A is superior to B which is superior to C"?
layer8 8 minutes ago [-]
> 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.
icedchai 3 hours ago [-]
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.
pinko 1 hours ago [-]
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...)
dawnerd 4 hours ago [-]
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.
zabzonk 5 hours ago [-]
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.
gruez 5 hours ago [-]
>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).
zabzonk 5 hours ago [-]
I don't think the type needs to be in the name because it is displayed elsewhere in the diagram, possibly as the object's icon. Plus of course the reasons no-one uses Hungarian anymore - types change.
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.
tremon 4 hours ago [-]
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.
rawgabbit 2 hours ago [-]
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.
datadrivenangel 5 hours ago [-]
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.
kingforaday 5 hours ago [-]
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.
ranman 1 hours ago [-]
Route53 being off on the side but unconnected is still valuable info...
ashwinnair99 6 hours ago [-]
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
chaps 5 hours ago [-]
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.
It amazes me that they are spending all of this time reducing the memory footprint and not do the most obvious thing - just stop using fucking Electron
raw_anon_1111 3 hours ago [-]
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.
Rendered at 18:21:12 GMT+0000 (Coordinated Universal Time) with Vercel.
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.
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.
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.
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.
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
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.
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.
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.
> 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.