System Architecture Diagram Example: Map Your Stack
Here's a test. Open the codebase of any app you've shipped and try to draw, in two minutes, how its pieces fit together. Most people freeze — not because they don't understand the system, but because they've never decided what a "piece" even is. Is the login service a box? Is the database a box? What about the CDN?
That decision — what gets a box — is the whole game. A system architecture diagram is just boxes (the parts) and arrows (how they talk). Get the boxes right and the diagram explains your app in ten seconds. Get them wrong and you've drawn a plate of spaghetti nobody trusts.
Let me walk through a real one.
What a system architecture diagram actually shows
A system architecture diagram is the bird's-eye view of your software: the major components, where they live, and the paths data takes between them. It's deliberately not about code.
That's the part people miss. If you already write UML class diagrams or entity relationship diagrams, those zoom into the code and the data model. An architecture diagram zooms out. A whole microservice you spent three months building might be a single rectangle here. That's correct. The audience for this diagram is a new engineer, a security reviewer, or a future you at 2 a.m. trying to remember which service owns the payment webhook.
So the boxes are deployable, running things: a web app, an API server, a database, a cache, a queue, a third-party service. The arrows are requests or data flows: "the API reads from Postgres," "the worker pulls jobs off Redis."
A worked system architecture diagram example
Let's diagram a fairly normal product — call it a photo-sharing app. Users upload images, the app processes them (thumbnails, content checks), and friends see a feed. Nothing exotic. Here's how I'd build the boxes, in layers.
Layer 1 — the clients. Two boxes: a Mobile App and a Web App. These are the things users actually touch. Don't split the web app into "React components" — that's code, not architecture. One box.
Layer 2 — the front door. An API Gateway (or load balancer) box. Every client request hits this first. Drawing it explicitly is what stops the next mistake: arrows from both clients converge on this one box, instead of every client drawing a line to every backend service. One arrow in, clean fan-out after.
Layer 3 — the services. Three boxes: Auth Service, Upload Service, Feed Service. The gateway routes to these. This is where you resist the urge to draw all twelve of your internal modules. If two modules deploy together and scale together, they're one box.
Layer 4 — the stores and the async stuff. A Postgres database (user accounts, captions, who-follows-who). An S3 / object store for the actual image files. A Redis cache in front of the feed. And a Queue feeding an Image Worker that generates thumbnails after an upload.
Layer 5 — the outside world. One box for a third-party Content Moderation API the worker calls. Drawing external dependencies as distinct boxes (often dashed) matters — those are the parts you don't control and that fail in ways you can't fix.
Now the arrows. Upload Service writes the file to the object store and drops a job on the queue. The Image Worker pulls that job, calls moderation, writes thumbnails back. Feed Service reads from Postgres, checks Redis first. Auth Service reads and writes user rows. Suddenly the whole system is one readable picture: roughly thirteen boxes, maybe fifteen arrows.
That's a complete architecture diagram. Notice what's not there — no function names, no class hierarchies, no table columns. If you want the table columns, that's a separate, zoomed-in diagram, and keeping them separate is exactly why each stays readable.
Pick a level of abstraction and stay there
The single most common failure mode is mixing zoom levels. You'll see a diagram where one box says "User Service" and the box right next to it says "validateEmail() helper." Those don't belong on the same canvas. One is a service; the other is a function inside a service.
A simple discipline: every box on the page should be the same kind of thing. A "container" diagram has running processes and data stores. A "context" diagram, one level up, has whole systems and the external actors around them. A "component" diagram, one level down, opens a single service and shows its internal parts. Pick one altitude per diagram. If you need to show the inside of the Upload Service, make a second diagram — don't crack it open on the system map.
This is the same logic behind a sequence diagram for a login flow: it shows one interaction in detail precisely because the architecture diagram stays high-level. They're a pair. One says "what exists," the other says "what happens, step by step."
Common architecture diagram mistakes
A few patterns to catch before you ship the picture:
- Arrows with no direction or no meaning. Every arrow should answer "who initiates, and what flows?" A line that just connects two boxes because "they're related" tells the reader nothing. Point it. Label it if it's not obvious ("publishes job," "reads thumbnails").
- Too many boxes. If you're past ~20 boxes, you're probably mixing altitudes or showing internal detail that belongs elsewhere. Group or zoom.
- Hidden external dependencies. That payment provider, that email API, that auth SSO — they're part of your architecture even though you didn't write them. Leave them off and your diagram lies about where the system can break.
- No grouping. Draw a box around the things that live in your cloud account versus the third-party services outside it. A reader should see your trust boundary at a glance.
- Color as decoration. Five colors that mean nothing is noise. Either use color to encode something real (data stores vs. services vs. external) or stick to one.
Building one without dragging boxes for an hour
You can draw all of this by hand in any diagram tool, and for a small system that's fine. The slow part is the layout — nudging boxes so the arrows don't cross, re-spacing everything when you add one more service.
This is where I let AI do the first pass. In Ridvay you describe the system in plain English — "web and mobile clients hit an API gateway, which routes to auth, upload, and feed services; uploads go to object storage and a queue, a worker generates thumbnails and calls a moderation API; feed reads Postgres with a Redis cache" — and it lays out the boxes and arrows for you. Then you edit: rename a box, redraw an arrow, drop in the one service it didn't know about. You're correcting a draft instead of starting at a blank canvas, which is a much faster way to think.
The diagram you end up with is the one worth keeping anyway — the one a new teammate reads on day one and finally understands how the whole thing fits together.
Want a head start? Generate a system architecture diagram from a description and reshape it until it matches your real stack.