How to Draw a System Architecture Diagram

By the Diagramium team · 2026-08-13 · 7 min read

To draw a system architecture diagram, decide which one question it must answer, then place only the components that help answer it — typically a client, an API boundary, the services behind it, any queue that decouples them, and the datastores each service owns. Label every arrow with what actually crosses it, and the diagram becomes useful instead of decorative.

Live interactive diagramUse the player controls to follow the steps

How a URL shortener worksPlaying silently in this guideWatch with narration

This compact player stays quiet while you read. Open the full presentation when you want narration and the complete walkthrough.

When an architecture diagram is the right choice

An architecture diagram shows what exists and how it is wired. Reach for one when someone needs the shape of a system in their head — a new engineer on their first week, a reviewer deciding whether a design is sound, or an interviewer asking you to design a URL shortener.

It is the wrong tool for showing an ordered interaction. "The client calls the API, which checks the cache, then reads the database" is a sequence, and a sequence diagram shows it far better. The architecture diagram shows that the cache and the database exist and who talks to them; it does not show the order.

An architecture diagram that tries to show every component ends up explaining none of them.

The components worth drawing

Most useful system diagrams are built from a small set of pieces. The architecture editor carries these as shapes:

Client. Browser, mobile app, another company's server. The thing outside your boundary that starts the work.
API / gateway. The front door. Worth drawing separately whenever routing, auth or rate limiting happens there rather than in each service.
Service. A deployable unit that owns some behaviour. Name it for what it does — Billing, not Service 2.
Queue or topic. Draw one wherever the sender does not wait for the receiver. A queue on the diagram is a promise that the two sides can fail independently.
Datastore. Database, cache, object storage. Attach it to the service that owns it — shared ownership is the single most consequential fact a diagram can reveal.
External system. A payment provider, an identity provider. Drawn distinctly, because you cannot change it.
Boundary. A container around a group — a VPC, an account, a trust zone.

The discipline that separates a good diagram from a wall of boxes: every arrow carries a label saying what crosses it. "HTTPS: order payload" or "publishes OrderPlaced" tell a reader something. An unlabelled arrow tells them only that two things are connected, which they had already assumed.

How to draw a system architecture diagram, step by step

Write down the question the diagram answers. "How does an order get paid for?" or "What breaks if Redis goes down?" A diagram without a question grows until it is useless.
Draw the boundary first. What is yours and what is someone else's. This decides what you get to change.
Place the client and the entry point. Requests should enter from a consistent edge — usually the left or the top — so every reader starts in the same place.
Add only the services the question needs. If removing a box does not change the answer, remove it.
Attach each datastore to its owning service. If two services touch one database, draw it — that is a fact people need to argue about, not hide.
Add the asynchronous edges. Where a queue or topic sits between two services, draw it as its own node rather than an arrow, so the decoupling is visible.
Label every arrow. Protocol, payload, or event name. Do this last and you will find arrows you cannot explain — those are the ones worth a conversation.

Worked examples you can open and edit

Editable diagrams, not screenshots — open one and move a component to see the connectors re-route.

ArchitectureNarratedWatch onlyHow a URL shortener worksThe system-design interview staple: client, API, cache, database and analytics in one picture.View example Play presentation
ArchitectureMicroservices architectureA gateway in front of independent services, each owning its own database, joined by an event bus.View example Use template
ArchitectureNarratedWatch onlyReal-time chat backendWhere a queue earns its place: pub/sub fan-out so one message reaches every connected device.View example Play presentation
ArchitectureNarratedWatch onlyCaching, from browser to databaseSix caches between a click and a disk — the diagram to draw when latency is the argument.View example Play presentation
ArchitectureNarratedWatch onlyHow websites handle millions of usersThe same system drawn at four sizes, from one box to load-balanced stateless replicas.View example Play presentation
ArchitectureNarratedWatch onlyAI RAG pipelineA retrieval-augmented generation pipeline: index, retrieve, then ground the answer.View example Play presentation

A complete small system: the URL shortener

The URL shortener example contains every component in the list above at a size you can hold in your head: a client, an API, a cache, a database, and an analytics path that is deliberately asynchronous. It is worth studying because of that last piece — recording a click must not slow down the redirect, so the write goes to a queue and the redirect returns immediately. On the diagram that is one extra node, and it changes the system's entire failure behaviour: analytics can be down for an hour and no user notices.

Services, queues and per-service databases

The microservices example shows the arrangement people most often draw badly: a gateway in front of independent services, each with its own database, joined by an event bus. The detail that matters is the per-service database. A diagram showing five services all pointing at one database is not a microservice architecture, whatever the boxes are labelled — and drawing it honestly is usually how a team discovers that.

Building one in Diagramium

Open the architecture diagram editor.

Drop components from the shapes panel — clients, services, queues, datastores and boundaries.
Drag from a port to connect two components. Connectors route around obstacles rather than through them, so a dense diagram stays readable.
Label the connectors in the inspector; the label sits in a pill that masks the line behind it.
Group related components inside a container to show a boundary.
Press Present to build the system up one component at a time — the single most effective way to explain an architecture to people who have never seen it.

The architecture editor is canvas-based; there is no text syntax, and the Text editor tab is hidden in this mode.

Present assembles the system in front of the audience instead of dropping a finished picture on them. For onboarding and design reviews this is the difference between a diagram people follow and one they photograph and never open.
Export PNG, SVG or PDF free with no account; SVG is the right choice for a wide system diagram in a document, because it stays sharp at any zoom. Animated SVG, GIF and video need a free account, not a subscription.
Embed a published diagram in an engineering handbook as a player that reveals the system step by step.

Common mistakes

Unlabelled arrows. The commonest defect and the easiest fix. If you cannot name what crosses an arrow, you may not need the arrow.
Every component on one page. Draw the system at one altitude per diagram. If you need both the whole estate and the inside of one service, that is two diagrams — which is exactly the problem the C4 model exists to solve.
Shared databases drawn as separate boxes. If two services write to the same store, one box with two arrows is the truth. Duplicating it to keep the picture tidy hides the coupling.
Queues drawn as arrows. A queue is a component with its own durability and failure behaviour. Give it a box.
Logos instead of labels. A vendor logo says who built the thing, not what it does in your system. Label it Session cache and let the shape carry the rest.
A diagram that will be wrong next month. Draw the parts that are stable. Version numbers and instance counts belong in the runbook.

For layered views of the same system — context, containers, components — use the C4 model.
For the order in which components talk during one request, draw a sequence diagram.
For where data comes from and what transforms it, use a data flow diagram.
For the schema inside a datastore, draw an ER diagram.
For routers, switches and physical topology, use the network diagram editor.
To reason about attackers rather than traffic, build a STRIDE threat model.

Questions people actually ask

What is the difference between an architecture diagram and a C4 diagram?

C4 is a specific discipline for architecture diagrams: it fixes four zoom levels (context, container, component, code) so every diagram states its altitude. A general architecture diagram has no such rule. Use C4 when several diagrams must fit together consistently.

How much detail belongs on one diagram?

One altitude, and only the components that help answer the stated question. The test is subtractive: remove a box and ask whether the answer changed. If it did not, leave it out.

Should I show every microservice?

Only those involved in the question. A diagram of forty services is an inventory, and an inventory is better as a list. Draw the eight that participate in the flow you are explaining.

Do I need to follow a standard notation?

No standard governs general architecture diagrams. Consistency within your own set matters more than conformance — pick shapes for client, service, queue and store, and keep them the same across every diagram your team draws.

How do I show that something is asynchronous?

Draw the queue or topic as its own component between sender and receiver, and label the arrow with the event name. That reads unambiguously in a way a dashed line alone does not.

Ready to build one? Open the Architecture editor on a blank canvas, or start from one of the templates above — they are all editable.Open the Architecture editor Browse all templates