Lesson 5.7 · 10 min read
Somebody puts a diagram on a screen. Boxes, arrows, a few cylinders, labels in small text. Everyone nods. The discussion begins, and it is conducted entirely in reference to this picture, as though its meaning were obvious.
For most of your career, it hasn't been. You could see that data went from here to there, roughly. You could not have said what would happen if one of those boxes disappeared, or which arrow was the one that would get slow, or why the person who drew it put a particular box in a particular place.
That changes in this post, and it changes because of everything before it. Architecture diagrams are not hard to read. They're hard to read without the vocabulary, and you now have all of it. This post is not new material. It is the moment where the entire series becomes a single skill: looking at a picture of a system and understanding how it behaves, where it will fail, and what it will cost.
Strip away the styling and every architecture diagram, no matter how intimidating, is made of exactly two kinds of thing.
Boxes are things that do work or hold state. A client, a server, a database, a cache, a queue, a worker, an external service.
Arrows are conversations. One thing making a request of another and getting a response. Every arrow you have ever seen on one of these diagrams is a version of the journey from post 0.1, and there are no exceptions.
That's it. Boxes and arrows, work and conversation. Everything else is convention: cylinders usually mean data stores, clouds usually mean things you don't control, dotted lines often mean asynchronous communication. But the substance is two things, and if you can name what each box does and what each arrow carries, you have read the diagram.
The mistake people make is trying to absorb the whole picture at once. Don't. A diagram is not a picture to be contemplated. It is a map to be walked.
Here is the single technique that makes any architecture legible. Pick one thing a user does, and follow it through the diagram, box by box, out and back.
Not the whole system. One action. "A user opens their dashboard." Put your finger on the client box and move.
The client sends a request. Where does it land? Follow the arrow. It probably hits a load balancer, which means there are multiple identical servers behind it, which means those servers are stateless and disposable, which you know from the scalability post. That single box just told you a great deal about the entire right-hand side of the picture.
Continue. The server needs data. Follow its arrows. Does it touch a cache first? Then most requests stop there and never reach the database, and now you know where this system's speed comes from, and you should immediately be wondering how that cache gets invalidated. Does it go straight to the database? Then every dashboard load is a query, and you can estimate what happens at ten thousand users.
Keep going until the response comes back to the client. You have now traced one path, and along the way you've learned more about the system than an hour of staring would have taught you.
Then trace a second one, deliberately different. "A user uploads a video." Watch where that goes. If it goes to a server that talks to a queue, and the arrow to the transcoding worker is dotted, you understand instantly: the upload returns immediately, the work happens later, the user will be told when it's done. That's the whole of post 5.3 written in three boxes and two arrows, and you read it in four seconds.
Trace three or four different actions through any diagram and you will understand the system better than most people in the room, who are looking at the same picture but not walking it.
As you walk, interrogate each box. You now have real questions, and each one has an answer that tells you something about the system's behavior.
Is it stateless? Application servers should be. If there are several identical ones behind a load balancer, they must be. Which means if you see a box that appears to be one of several and it seems to be storing something, you have found either a mistake or something you don't yet understand, and both are worth asking about.
What happens if it dies? This is the most valuable question you can ask of any box in any diagram. If one of five application servers dies, the load balancer stops sending it traffic and nobody notices. If the load balancer dies, everything is gone. If the cache dies, everything gets slow and continues working. If the database dies, you are down. If a worker dies, jobs pile up in the queue and get processed late, which is a delay rather than a failure.
Ask that of every box and you have just performed a real failure analysis. The boxes that take everything down with them are your single points of failure, and finding them is often the most useful thing anyone does with an architecture diagram. They're usually easy to spot once you look: they're the boxes with only one of themselves, that everything depends on.
Can it be scaled? Boxes that are stateless can be multiplied. Boxes that hold state cannot, easily, which is why the database is drawn as one thing and the servers as three. That asymmetry in the picture is the entire lesson of post 5.1, drawn.
Is it something we control? External services, a payment provider, an email service, an AI model, are boxes you cannot fix when they break. Every arrow pointing out of your system to one of them is a place where somebody else's outage becomes your outage, unless there's a queue in between, in which case it becomes somebody else's outage and a delayed email.
Arrows are where the costs live, and most people ignore them entirely.
How long does this take? Every arrow is a network trip, and every network trip has latency. An arrow to a cache costs a millisecond. An arrow to a database costs a few. An arrow to an external API across the internet costs a hundred, sometimes more, and you don't control it. Count the arrows on the path you traced. If a single user action requires six sequential trips, you can predict how that page will feel before you ever load it.
Is it synchronous or asynchronous? Does the caller wait? A solid arrow into a database means someone is waiting for the answer. A dotted arrow into a queue means nobody is waiting and the work will happen later. This is the distinction from the queues post, and on a diagram it is usually the difference between a page that responds instantly and one that hangs.
What happens if this arrow fails? The thing at the other end is down, or slow, or refusing. Does the whole request fail? Does it retry? Does it fall back to something? An arrow to a cache that fails should be harmless, you just go to the database. An arrow to the database that fails is fatal. An arrow to an email service that fails should be a retry, not an error shown to the user.
How many times does this arrow get traversed? An arrow that fires once per user session is different from one that fires once per item in a list. When a single page renders fifty items and each one triggers a query, that arrow is fifty arrows, and this is one of the most common real performance problems in software, hiding in plain sight as a single innocent line on a diagram.
Put it together. Imagine the diagram you'd see for a fairly ordinary product.
A mobile app and a web client, on the left. Both point at one box labeled API gateway or load balancer. Behind it, three identical boxes labeled API server. Those three point down to a cylinder labeled database, and also to a smaller box labeled cache. One server also has a dotted arrow to a box labeled queue, and from the queue, dotted arrows to two boxes labeled worker. The workers point at the database, and one of them has an arrow leaving the diagram entirely, to a cloud labeled email provider. Off to the side, a box labeled object storage, with an arrow from the clients directly to it.
You can now read this completely, and it takes a minute.
The clients talk to one address, which distributes across three interchangeable servers, so those servers hold no state and any of them can serve any request, and one of them can die without consequence. They read through a cache, so most requests never reach the database, which means the database is protected but also that something in here is serving data that may be slightly stale, and you should ask what invalidates it. The database is a single cylinder, which means it is the single point of failure and the scaling ceiling for this entire system, exactly as post 5.1 predicted.
Slow work goes into the queue rather than being done in the request, so uploads and emails don't hold connections open, and the workers can be scaled separately from the API servers. The arrow leaving to the email provider comes from a worker rather than from an API server, which is correct and deliberate: the email provider's outage will delay emails rather than break the product. Whoever drew this understood that.
And the clients talk directly to object storage rather than uploading through the servers, which means large files never consume application capacity at all, and which tells you the servers are handing out temporary permission to upload directly, because otherwise that arrow would be a gaping security hole.
Every one of those observations came from this series. You didn't learn anything new in the last two paragraphs. You just found out that you could already do this.
The last thing, and it's the point of the whole module.
Diagrams are not documentation. They're a thinking tool, and their value is mostly in the drawing. When you sit down to draw a system you're proposing, the picture forces questions that prose lets you avoid. Where does this data live? Who talks to whom? What is this box waiting for? What happens when this box is gone?
You cannot draw a box without deciding whether there is one of it or several. You cannot draw an arrow without implicitly claiming that this thing knows about that thing. You cannot leave the database as one cylinder without admitting, to yourself, that you have a single point of failure and have decided to accept it for now.
This is why architecture diagrams are drawn before systems are built, and why the drawing is often where the design actually happens. It is the same reason you sketch before you build a screen. The sketch is not a picture of the thinking. The sketch is the thinking.
When you build with AI and it proposes an architecture, ask it to show you the boxes and arrows, and then read the picture rather than the paragraph. Trace one user action through it. Ask what dies. Ask which arrows are slow. Ask which box has only one of itself. You will find things, because a diagram cannot hide the shape of a system the way a confident description can, and that is precisely why you want one.
Find a real architecture diagram. Search for how any large product you use is built; engineering blogs are full of them, and they are usually far more readable than you expect.
Do not read the article. Look at the picture first, and walk it. Pick one user action and trace it with your finger, box to box, saying out loud what each box does and what each arrow carries. Find the load balancer and note what its existence implies. Find the caches and ask what makes them stale. Find every box that exists only once, and ask what happens when it's gone. Find the arrows that leave the system entirely, and ask whether there's a queue protecting them.
Then read the article and see how much of it you had already deduced.
After that, draw your own. Take something you've built, however small, and put it on paper. Every box, every arrow. Be honest: if your uploads land on the server's disk, draw that, and then look at it, and notice that you cannot draw a second server without the picture becoming a lie. That moment, where the drawing tells you something about your system that you had managed not to notice, is what diagrams are for.
That is where this module has been going the whole time. Not to make you memorize caches and queues and partitions, but to make you someone who can look at a system, any system, including one you haven't built yet, and see it.