[HN Gopher] More common mistakes to avoid when creating system a...
___________________________________________________________________
More common mistakes to avoid when creating system architecture
diagrams
Author : billyp-rva
Score : 127 points
Date : 2026-03-22 11:51 UTC (11 hours ago)
(HTM) web link (www.ilograph.com)
(TXT) w3m dump (www.ilograph.com)
| ashwinnair99 wrote:
| 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 wrote:
| 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.
| 01HNNWZ0MV43FF wrote:
| The Slack notification flowchart is an old favorite:
| https://slack.engineering/reducing-slacks-memory-footprint/
| raw_anon_1111 wrote:
| 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_
| zabzonk wrote:
| 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 wrote:
| >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 wrote:
| 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 wrote:
| _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.
| datadrivenangel wrote:
| 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.
| orthoxerox wrote:
| 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.
| zabzonk wrote:
| 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 wrote:
| yup, A interacts with B with the interaction originating from
| A.
| chrisweekly wrote:
| 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"?
| growse wrote:
| I 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.
| HotGarbage wrote:
| 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.
| cenamus wrote:
| C4 is great, even if I can't be bothered to model every layer
| kqr wrote:
| 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.
| NalNezumi wrote:
| 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 wrote:
| 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.
| sly010 wrote:
| 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.
| sly010 wrote:
| Then of course there is the whole fractal nature of software.
| As you add more detail, the arrows can flip flop around.
| Polling in a lower level of a stack can very much be used as
| a push mechanism. (e.g. USB interrupts are in fact the host
| polling the device)
|
| This is why communicating architecture is often as hard if
| not harder than implementing it.
| kingforaday wrote:
| 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.
| dawnerd wrote:
| 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.
| hrmtst93837 wrote:
| Chasing perfect diagrams is usually an exercise in self-
| deception, since the second the infra changes, whatever picture
| you drew is wrong. The trickier part is when the diagram
| becomes canon inside the org and nobody notices it diverged
| from reality years ago, so tribal knowledge beats the official
| chart every time.
|
| Odd thing is, the only diagrams that seem to matter end up on
| whiteboards or living docs if anyone's actually building
| things. Few things age faster than polished Visio junk made for
| complaince audits and VP vanity.
| raw_anon_1111 wrote:
| 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.
| icedchai wrote:
| 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 wrote:
| 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...)
| dematz wrote:
| 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.
| zahlman wrote:
| > 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 wrote:
| 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 wrote:
| > 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 wrote:
| > 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.
| vanviegen wrote:
| > 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.
|
| 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.
| dpark wrote:
| > I can't remember any occasions where the diagram
| actually cleared things up though.
|
| 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.
| zahlman wrote:
| > 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 wrote:
| 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 wrote:
| 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 wrote:
| Some stakeholders will gain more understanding from a diagram
| than any amount of simplified prose, so both are typically
| helpful.
| rawgabbit wrote:
| 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.
| ranman wrote:
| Route53 being off on the side but unconnected is still valuable
| info...
| layer8 wrote:
| > 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 wrote:
| 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.
| azov wrote:
| Same for me. The arrows are so small I can't even see them on
| my phone, but animation makes direction clear.
| motohagiography wrote:
| 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.
| chrisss395 wrote:
| 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.
| drewbeck wrote:
| 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.
| exogenousdata wrote:
| 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.
| corstian wrote:
| Multiple interlinked diagrams? A whole bunch of diagrams at
| different levels, from different perspectives all designed to
| answer different questions?
| billyp-rva wrote:
| You are defining the goal of Ilograph to a T.
| zmmmmm wrote:
| 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.
___________________________________________________________________
(page generated 2026-03-22 23:00 UTC)