Learn what a software architecture diagram is, the main diagram types, the C4 model levels, a worked container diagram example, and a free copyable template.

A software architecture diagram is a picture of how a software system is built: the people who use it, the applications and data stores inside it, the outside systems it depends on, and how they talk to each other. A good one answers one question for one audience, has a title and a legend, and labels every arrow with what flows along it and how.
This guide shows the common types of architecture diagrams, explains the C4 model that many teams use to keep them consistent, walks through a complete worked example, and ends with a copyable template you can redraw on any whiteboard.
Short version
- Start with two diagrams. A system context diagram (your system as one box, with its users and neighbors) and a container diagram (the apps, services, and databases inside it). The C4 model recommends both for every team.
- Add detail only when someone needs it. Component, deployment, sequence, and data flow diagrams answer narrower questions. Code-level diagrams are usually better generated by tools.
- Make every diagram readable on its own. Title, legend, element types, technology labels, and one-way arrows with specific labels such as "Reads and writes shifts [SQL/TLS]" instead of "Uses".
Published by AFFiNE, which makes a workspace with an Edgeless whiteboard where you can draw these diagrams. C4 model details were checked on c4model.com on October 28, 2026. Sources are listed at the end.
A software architecture diagram is a visual model of a software system's structure. It shows the major building blocks, their responsibilities, the technologies they use, and the relationships between them. Teams use architecture diagrams to onboard engineers, review designs before building, explain a system to security or operations teams, and plan changes such as splitting a monolith.
The word "architecture" covers several levels of zoom. A diagram for a product manager shows the system as a single box among its users. A diagram for a new backend engineer shows the API, the database, and the message queue. A diagram for a database reviewer shows tables. Most bad diagrams try to show all of these at once, which is why they end up as a wall of boxes nobody can read.
Each type answers a different question. Pick the question first, then the diagram.
| Diagram type | Question it answers | Typical audience | Level of detail |
|---|---|---|---|
| System context | What does the system do, who uses it, and which other systems does it depend on? | Everyone, including non-technical stakeholders | Lowest: one box for the system |
| Container | Which applications and data stores make up the system, and how do they communicate? | Developers, architects, operations | Apps, services, databases, queues |
| Component | What are the main parts inside one application? | Developers working on that application | Modules or services inside one container |
| Deployment | Where does each container run in a given environment? | Operations, SRE, security | Servers, clusters, cloud services, regions |
| Sequence or dynamic | In what order do parts interact for one scenario, such as checkout? | Developers, reviewers | One use case, step by step |
| Data flow | Where does data come from, where is it stored, and where does it go? | Security, privacy, compliance | Data stores, processes, trust boundaries |
| Code (class, ER) | How is one component implemented? | Developers | Classes, interfaces, tables |

For a deeper look at the first level, see our guide to the system context diagram. For scenario-level diagrams, see the UML sequence diagram guide, and for database structure, our ER diagram tool guide.
The C4 model is a lightweight approach to software architecture diagramming created by Simon Brown. According to the official site, its roots go back to around 2006 to 2009, the diagram types were named in early 2010, and the "C4" name was first used in early 2011. It gives you four levels of zoom, a bit like a map that goes from country to street:
C4 also describes three supporting diagrams: system landscape, dynamic, and deployment. Deployment diagrams matter in practice because the container diagram deliberately leaves out clustering, load balancers, and failover, which vary by environment.
Two details trip people up:

To make this concrete, here is a full container diagram for an invented product, Shiftly, a web and mobile app that restaurants use to schedule staff shifts. This is an illustrative example, not a real customer system, but the structure is typical of a small SaaS product.
Title: Container diagram for Shiftly
People
Containers inside the Shiftly boundary
External systems
Relationships (each arrow one direction, with intent and technology)
| From | To | Label |
|---|---|---|
| Restaurant manager | Web app | Builds weekly schedules [HTTPS] |
| Staff member | Mobile app | Views shifts, requests swaps [HTTPS] |
| Web app | API application | Makes API calls [REST/JSON, HTTPS] |
| Mobile app | API application | Makes API calls [REST/JSON, HTTPS] |
| API application | Database | Reads and writes schedules [SQL/TLS] |
| API application | Job queue | Enqueues reminder and billing jobs [Redis protocol] |
| Background worker | Job queue | Pulls jobs [Redis protocol] |
| Background worker | Email and SMS provider | Sends shift reminders [HTTPS API] |
| Payment provider | API application | Posts billing webhooks [HTTPS] |

A few decisions in this example are worth copying:
Write one sentence at the top of the canvas, such as "How do Shiftly's apps and data stores fit together, for new backend engineers?" If you cannot write it, you do not know which diagram to draw yet.
Use a system context diagram for scope and stakeholders, a container diagram for building blocks and technology, and a deployment diagram for infrastructure. Draw one level per diagram instead of mixing them.
Write each person, container, and external system as a line of text with its name, type, technology, and a one-line responsibility. This list becomes the content of your boxes and catches missing pieces early.
Draw a dashed box for your system boundary. Put people at the top, your containers inside the boundary, and external systems outside it, usually to the right or bottom. Keep request flow running in one general direction.
Draw one arrow per relationship and label it with intent and technology, such as "Reads and writes schedules [SQL/TLS]". Avoid two-headed arrows and single-word labels like "Uses".
Title the diagram with its type and scope, add a legend for colors, shapes, and line styles, and walk someone who did not draw it through the diagram. Every question they ask is a missing label.
Copy this outline into a doc or whiteboard and replace the example values. It follows the C4 container level and fits on one screen. You can also open the editable software architecture diagram template in AFFiNE, which has the same layout, the Shiftly example, and a legend on an Edgeless whiteboard.
Title: Container diagram for <System name>
Question: <What this diagram explains, and for whom>
Last updated: <YYYY-MM-DD> Owner: <name or team>
PEOPLE (top row)
- <Role 1> [Person]: <what they do with the system>
- <Role 2> [Person]: <what they do with the system>
SYSTEM BOUNDARY: <System name> (dashed box)
- <Web app> [Container: <technology>]: <responsibility>
- <Mobile app> [Container: <technology>]: <responsibility>
- <API application> [Container: <technology>]: <responsibility>
- <Background worker> [Container: <technology>]: <responsibility>
- <Database> [Container: <technology>]: <what it stores>
EXTERNAL SYSTEMS (outside the boundary)
- <External system 1> [Software system]: <what it provides>
- <External system 2> [Software system]: <what it provides>
RELATIONSHIPS (one direction each: from -> to : intent [technology])
- <Role 1> -> <Web app> : <intent> [HTTPS]
- <Web app> -> <API application> : <intent> [REST/JSON, HTTPS]
- <API application> -> <Database> : <intent> [SQL/TLS]
- <Background worker> -> <External system 1> : <intent> [HTTPS API]
LEGEND
- Blue box: container we own
- Grey box: external software system
- Person shape: user role
- Dashed box: system boundary
- Solid arrow: request or data flow, labeled with intent and technology
REVIEW CHECKLIST
- [ ] Title states diagram type and scope
- [ ] Every element has a name, type, and one-line description
- [ ] Every container names its technology
- [ ] Every arrow is one-way and labeled with intent and technology
- [ ] Legend explains colors, shapes, and line styles
AFFiNE is a workspace where every doc has two modes: Page mode, a linear document, and Edgeless mode, an open canvas for shapes, connectors, frames, and notes. That combination suits architecture diagrams because the written design and the picture can live in the same doc. You can put the container diagram in a frame on the canvas and keep the element list, decisions, and open questions as text next to it, then link that doc from your other pages (how page linking works). The component diagram template and deployment diagram template cover the next levels down, and more are in the diagram template collection.
AFFiNE runs as a cloud service or self-hosted. Self-hosting is free for up to 10 seats per workspace; larger teams need a paid plan or license. See self-hosting and pricing for current terms.
Who should not use AFFiNE for this:
At minimum: a title with the diagram type and scope, the people and external systems involved, the main building blocks with their technology, one-way arrows labeled with what flows and how, and a legend that explains colors, shapes, and line styles.
The C4 model is an approach to software architecture diagramming created by Simon Brown. It describes four levels of zoom: system context, container, component, and code. It is notation independent and tooling independent, and its official site recommends system context and container diagrams for all teams.
A system context diagram shows your system as one box with its users and the other systems it depends on. A container diagram zooms into that box and shows the applications and data stores inside it, such as a web app, an API, and a database, with the technologies and protocols between them.
No. UML component and deployment diagrams work well, but many teams use simple boxes and arrows. What matters is that the notation is explained in a legend and that every element and arrow is labeled.
Most teams need a system context diagram and a container diagram, plus a deployment diagram per environment if infrastructure matters. Add component, sequence, or data flow diagrams only when a specific question or review needs them.
How this guide was prepared: AFFiNE wrote this article in October 2026. The diagram-type table, the Shiftly example, and the template reflect common architecture documentation practice and the published C4 guidance; Shiftly is invented and is not a customer case. AFFiNE sells a whiteboard and docs product, so we have a commercial interest in diagramming; the "who should not use AFFiNE" list is there to keep that honest. AI tools assisted with research and drafting, and the AFFiNE team reviewed and edited the content.