Software Architecture Diagrams: Types, Examples and Best Practices

A software architecture diagram shows how a system is put together — its parts, what each one is responsible for, and how they communicate. There is no single "architecture diagram": there are roughly six useful types, each answering a different question. Context shows the system's place in the world, container shows its deployable pieces, component shows the inside of one piece, deployment shows where it runs, data flow shows what information moves, and sequence shows the order things happen. Pick by the question you are being asked, and draw one diagram per question rather than one diagram for all of them.

Live interactive diagramUse the player controls to follow the steps

Microservices architecturePlaying silently in this guideWatch with narrationOpen in editor

What this diagram shows

1. Two clients sit at the top: a web app and a mobile app.
2. Both call a single API gateway, which fronts an auth and identity component.
3. Behind the gateway sit three services — orders, payments and inventory.
4. Each service owns its own database: orders DB, payments DB and inventory DB, never shared.
5. An event bus connects the services asynchronously.
6. A notifications worker consumes from the bus rather than being called directly.

Why "one architecture diagram" is the problem

The classic failure is a single picture holding load balancers, classes, AWS regions, business capabilities and a queue, connected by unlabelled lines. It happens because each stakeholder asked a different question and every answer was added to the same canvas.

The discipline of separate views is old and well founded. Kruchten's "4+1" view model made the argument in 1995: describe an architecture through several concurrent views — logical, process, development, physical, plus scenarios — because no single projection serves every stakeholder. The vocabulary has moved on; the reasoning has not.

If you cannot say who asked for the diagram, you cannot know when it is finished.

The six types worth knowing

1. System context — where the system sits

One box for your system, the people who use it, and the external systems it depends on. No internals at all. This is the diagram for someone who does not work on the system: an executive, a new joiner, a security reviewer establishing scope. It is also the cheapest diagram to keep accurate, because its contents change perhaps twice a year.

2. Container — the deployable pieces

The applications and data stores that make up the system, and how they talk. Web app, mobile app, API, database, message bus, worker. This is the workhorse: it is detailed enough for engineers to reason about and stable enough to survive a quarter. Both context and container are levels of the C4 model, which is the most widely used naming convention for this hierarchy.

3. Component — inside one container

The major building blocks within a single application and their responsibilities. Useful for a service complex enough that new contributors get lost, and dangerous elsewhere: it is the level that goes stale fastest, because it changes every sprint.

4. Deployment — where it actually runs

Nodes, regions, availability zones, clusters, and which containers run on which. This is the diagram for capacity, failover, cost and compliance conversations, and it is the one people most often skip and then need urgently during an incident or an audit.

5. Data flow — what information moves

Processes, data stores, external entities and the data that travels between them. It answers a question the others cannot: where does personal data go, and which boundaries does it cross? That makes it the backbone of privacy reviews and threat models. See how to create a data flow diagram.

6. Sequence — the order things happen

Participants as lifelines, messages in time order. Structural diagrams show what exists; a sequence diagram is the only one of the six that shows when, which is why it is the right tool for an authentication handshake, a checkout, or a retry-and-timeout path. See how to create a sequence diagram. The notation is standardised by the OMG in UML 2.5.1.

Choosing: a short decision list

1. Who is reading it, and what decision are they making? Write it down. Everything else follows.
2. Is the question "what is this system?" Context.
3. Is it "how is it built?" Container.
4. Is it "why is this service hard to change?" Component — and only for that service.
5. Is it "what happens if that region goes down?" or "what does this cost?" Deployment.
6. Is it "where does the data go?" Data flow.
7. Is it "in what order, and what if step three fails?" Sequence.

Most teams need two diagrams they keep current — context and container — plus a sequence diagram for each genuinely tricky interaction. Everything else is drawn on demand and allowed to expire.

A worked example: reading a container diagram

The diagram at the top of this page is a container-level view of a microservices system, and it is worth reading closely because its structure encodes several decisions.

Two clients — a web app and a mobile app — both enter through a single API gateway, which fronts auth and identity. Behind it sit three services: orders, payments and inventory. Each has its own database. That is not a drawing convention; it is the architectural claim. Three separate databases say "no service reads another's tables", which is the constraint that makes the services independently deployable, and drawing one shared database instead would describe a completely different system.

The event bus carries the second claim. Notifications hangs off the bus rather than being called by orders, so orders does not know notifications exists — the difference between a system you can extend and one where every new feature edits the checkout path.

What the diagram deliberately does not show: how many instances of each service run, which region they run in, or what happens inside the payments service. Those are the deployment and component diagrams, and cramming them in here would cost the clarity that makes this one useful.

Architecture diagrams you can open and edit

Building them in Diagramium

The architecture editor carries typed shapes — client, service, database, queue, cache, gateway, worker, external system — so a reader can tell a queue from a datastore without reading labels. For the C4 hierarchy specifically there is a dedicated C4 editor with person, software system, container and component shapes.

• Label every relationship. An unlabelled line between two services is the single biggest loss of information in architecture diagrams. "Reads from" and "publishes events to" are different systems.
• Show direction. Who initiates matters, especially for anything crossing a trust boundary.
• Use Present for reviews. Revealing a system one element at a time keeps a design review on the reviewer's question instead of the loudest thing on the slide.
• Export or embed. PNG, SVG and PDF need no account; animated SVG, GIF and video need a free one. An embedded interactive diagram in your docs beats a screenshot that quietly goes stale.

Best practices

• One question per diagram. If you cannot state the question, do not draw the diagram.
• Label every arrow, with a verb and ideally a protocol. Reads customer records from, over gRPC.
• Include a legend, or use shapes so conventional none is needed. Never rely on colour alone.
• Date every diagram and name an owner. Undated architecture diagrams are believed long after they stop being true.
• Keep the stable diagrams; let the volatile ones expire. Context and container are worth maintaining. A component diagram of a service under active development is not, and pretending otherwise produces confidently wrong documentation.
• Draw the boundary explicitly. What is yours, what is a third party, where a request leaves your control.

Common mistakes

• The everything diagram. Every layer at once, so no reader can find their own question in it.
• Unlabelled connections. Lines that mean "these are related somehow", which is not information.
• Logos instead of responsibilities. A wall of vendor marks says what you bought, not what the system does.
• Mixing levels. A Kubernetes cluster next to a Java class in the same picture.
• Drawing the target architecture and labelling it "architecture". Current and intended state are two diagrams, and conflating them misleads everyone who was not in the planning meeting.
• No context diagram. Teams jump straight to containers, and every newcomer spends their first fortnight inferring the boundary.

In short

There is no one architecture diagram, and trying to draw one is what makes architecture diagrams bad. Six types, one question each: context for scope, container for structure, component for the inside of a service, deployment for where it runs, data flow for where information goes, sequence for order. Maintain the two stable ones, draw the rest when someone asks, and label every arrow.

Open the architecture editor to start one, or take any diagram in the gallery above and edit it into your own system.

Questions people actually ask

What are the main types of software architecture diagram?

System context, container, component, deployment, data flow and sequence. Context, container and component are the structural levels of the C4 model; deployment covers infrastructure; data flow follows information; sequence covers ordering over time.

Which architecture diagram should I draw first?

A system context diagram. It is the cheapest to draw, the slowest to go out of date, and it settles the boundary question that every other diagram depends on.

What is the difference between a container diagram and a deployment diagram?

A container diagram shows the logical deployable pieces — an API, a database, a worker — and how they communicate. A deployment diagram shows the infrastructure those pieces run on: nodes, clusters, regions and instance counts. One is what the system is; the other is where it lives.

Should architecture diagrams use UML?

Only when the audience reads UML. Formal UML is precise and standardised by the OMG, and precision is worth having for component and sequence diagrams shared between engineers. For context and container diagrams read by mixed audiences, labelled boxes and arrows communicate better.

How often should architecture diagrams be updated?

Tie them to change rather than the calendar. Context and container diagrams should be updated when a system or container is added or removed, which is rare. Component diagrams go stale within a sprint, which is a good reason to draw them only when needed and let them lapse afterwards.

How do I keep a diagram in sync with the code?

Reduce what has to stay in sync. Keep the stable levels maintained by hand, note the diagram's date and owner on the diagram itself, and embed it where people read it rather than exporting copies that are stale the moment they are pasted.