Architecture Diagrams for Engineers with C4 and Mermaid
A practical guide to creating clear software architecture diagrams using the C4 model and Mermaid, with worked examples for every level of abstraction.
Architecture diagrams are the map that helps your team navigate a complex system. The C4 model, combined with tools like Mermaid, gives engineers a structured, repeatable way to document software architecture at every level of detail.
What is the C4 Model?
The C4 model (created by Simon Brown) organises architecture diagrams into four levels of abstraction:
| Level | Name | Audience | Shows |
|---|---|---|---|
| C1 | System Context | Everyone | Your system in the world |
| C2 | Container | Engineers | The high-level technology choices |
| C3 | Component | Developers | Components inside a container |
| C4 | Code | Developers | Classes and interfaces |
The power of C4 is that each level zooms in on the previous one — like Google Maps moving from a world map to street view.
Level 1: System Context Diagram
The context diagram shows your system as a single box, surrounded by the users and other systems it interacts with. It answers: “What does this system do and who uses it?”
Level 2: Container Diagram
The container diagram zooms in on your system, showing the applications, databases, and services that make it up. It answers: “What are the major technology building blocks?”
Level 3: Component Diagram
The component diagram zooms into a single container, showing its internal components. This is most useful for the most complex container.
Level 4: Code Diagrams
Code diagrams are usually only worthwhile for complex domain logic. Use Mermaid class diagrams for this level:
Tips for Great Architecture Diagrams
Keep Each Diagram Focused
A diagram that shows everything is a diagram that explains nothing. Each C4 level should zoom into exactly one level of abstraction. If a C2 diagram has 30 boxes, split it into multiple diagrams.
Use Consistent Notation
Stick to a consistent visual language across all diagrams:
- Boxes = containers or components
- Cylinders = databases
- Arrows = data flow or calls, labelled with the protocol (
HTTPS,SQL,AMQP) - People icons = human users
Add a Key
Always include a legend that explains the shapes and colours used:
> **Key:** Blue boxes = internal systems, Grey boxes = external systems, Cylinders = databases
Update Diagrams with the Code
Out-of-date architecture diagrams are worse than no diagrams — they actively mislead. Keep diagrams in the same repository as the code and update them in the same PR as architectural changes.
Mermaid vs Dedicated C4 Tools
| Tool | Pros | Cons |
|---|---|---|
| Mermaid | In-editor, no extra tools, version-controllable | Less C4-specific notation |
| Structurizr | Native C4 with auto-layout | Requires separate tool/account |
| Draw.io | Visual drag-and-drop | Not text-based, hard to diff |
| PlantUML C4 | Rich C4 library | Verbose syntax |
For most teams, Mermaid in Markdown hits the best balance of accessibility, version control, and output quality.