What is the C4 model?
A short introduction to the C4 model for software architecture: the four levels, the words it uses, and how ArchLens turns them into diagrams your team edits together.
The idea
The C4 model is a way to describe the architecture of a software system as a small set of diagrams at different levels of detail, like the zoom levels of a map. It was created by Simon Brown and is documented at c4model.com.
It is deliberately simple. There are only a few kinds of element: people, software systems, containers and components, joined by relationships that say what talks to what and how. It does not prescribe shapes or colours; what matters is that each diagram has a clear scope, a title, a key, and labels on every line.
Because every level zooms into one element of the level above, a reader can start with the big picture and go down only where they need detail. A product manager may stop at the first diagram; a new developer keeps going.
The four levels
| Level | Shows | Typical reader |
|---|---|---|
| 1. System Context | your software system as one box, the people who use it, and the other systems it depends on | everyone, technical or not |
| 2. Container | the separately running or deployable parts inside the system: web and mobile apps, services, databases, queues, file stores, and how they communicate | developers, architects, operations |
| 3. Component | the main building blocks inside one container (modules, controllers, services) and their responsibilities | developers working on that container |
| 4. Code | how one component is implemented (classes, functions, tables) | usually generated from the code when needed |
A container in C4 is not a Docker container: it is anything that has to be running for the system to work, such as a single-page app, an API, a database or a serverless function.
The C4 model also describes supporting diagrams: a system landscape (many systems at once), dynamic diagrams (the order in which elements talk for one scenario) and deployment diagrams (where containers run).
How ArchLens draws the C4 model
ArchLens draws levels 1 to 3 as views of one shared model per workspace. You add an object once and it can appear on any number of diagrams; rename it in one place and every diagram follows.
| C4 level | In ArchLens | You add |
|---|---|---|
| System Context | the Context view of a diagram | Person, Software System (either can be marked external) |
| Container | double-click a system to open its containers | Container, Store (a database, queue or file store) |
| Component | double-click a container to open its components | Component |
| Code | not drawn; a Store can describe its tables and columns instead, with an ER diagram and SQL export | tables, columns, keys |
| Dynamic diagrams | Flows: ordered steps over the connections you drew, replayed on the diagram or shown as a sequence diagram | steps, parallel steps, notes |
- Rolled-up connections. When a container of system A calls a container of system B, the Context view shows a line between A and B. You draw the detail once; the higher levels follow.
- Every object carries a technology (with its logo), a status (live, future, deprecated, removed), tags and a description, so one model can show today's architecture and the planned one.
- Text out. Any view can be copied as Mermaid C4 or PlantUML C4 for a README, and a whole diagram can be exported as Structurizr DSL.
Draw your first C4 diagram
- Sign up with Google or GitHub and create a workspace.
- On Diagrams, choose New board. You start at the Context level.
- Add the people (P) and the software systems (S), then drag from one object's connection point to another to connect them. Double-click a line to label it.
- Double-click your own system to open its Container level and add its apps, services and stores. Connect them to each other and to the outside systems.
- Invite your team from Settings; they edit with you live. Share a read-only link or embed the diagram in your wiki when it is ready.
Already have a model in Structurizr DSL? Import it instead. Prefer to describe it in words? Let an AI assistant draw it into a draft for you to review.