8 ms·
More common mistakes to avoid when creating system architecture diagrams
- ashwinnair99 7mo agoThe 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 7mo agoOnce 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.
- 01HNNWZ0MV43FF 7mo agoThe Slack notification flowchart is an old favorite: https://slack.engineering/reducing-slacks-memory-footprint/ https://slack.engineering/reducing-slacks-memory-footprint/
- raw_anon_1111 7mo agoIt 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
- zabzonk 7mo agoCouple 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 7mo 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 7mo agoI 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 7mo agoAnd 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.
- datadrivenangel 7mo agoDiagrams 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.
- orthoxerox 7mo agoThe 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.
- zabzonk 7mo agoIn 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 7mo agoyup, A interacts with B with the interaction originating from A.
- chrisweekly 7mo agorelated 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"?
- zabzonk 7mo agoWhich (I think) is why we prefer to use "A --> B" rather than "A>B" or "A > B"
- growse 7mo agoI do similar, but frame it in terms of dependencies. 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.
- 7mo ago
- kingforaday 7mo agoTheir 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.
- dawnerd 7mo agoThis 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.
- hrmtst93837 7mo ago[flagged]
- lolive 7mo agoIn my company, we generate diagrams from data coming from external referencials that ARE source of truth, by process. Not the perfect solution, but much better than representations of a reality that has already moved miles ahead.
- ddrdrck_ 7mo agoIf 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.
- raw_anon_1111 7mo agoMy 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.
- icedchai 7mo agoThe 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 7mo agoUnderrated 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...)
- dematz 7mo agoIdk, 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_lines/#diagrams-huh-what-are-they-good-for 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 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.
- zahlman 7mo 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 7mo agoA 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 7mo ago
- rawgabbit 7mo agoI 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.
- ranman 7mo agoRoute53 being off on the side but unconnected is still valuable info...
- layer8 7mo 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.
- RaftPeople 7mo agoI 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.
- azov 7mo agoSame for me. The arrows are so small I can’t even see them on my phone, but animation makes direction clear.
- motohagiography 7mo agoThe 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.
- devnotes77 7mo ago[dead]
- bamwor 7mo ago[dead]
- chrisss395 7mo agoArchitecture 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.
- lolive 7mo agoAt 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]
- drewbeck 7mo agoAs 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.
- exogenousdata 7mo agoJust 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.
- corstian 7mo agoMultiple interlinked diagrams? A whole bunch of diagrams at different levels, from different perspectives all designed to answer different questions?
- billyp-rva 7mo agoYou are defining the goal of Ilograph to a T.
- drewbeck 7mo agoYep! That's almost always the correct solution. It can be a lot to figure out, tho: which perspectives are most valuable to present? Are the linkages clear? Does this kind of box belong on THIS chart or THAT chart?!
- zmmmmm 7mo agoTo 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.
- ranger_danger 7mo agoHave you tried C4-PlantUML? It actually has functions for manually adjusting the layout when it doesn't do what you want.
- deejayy 7mo agoI 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".
- ChrisMarshallNY 7mo agoI’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-protocol-default/#what https://littlegreenviper.com/the-curious-case-of-the-protoco...
- faizan199 7mo ago[dead]
- matthewaveryusa 7mo agoOne common mistake when pointing out common mistakes: Show the good example!
- perrygeo 7mo agoMost 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.