Mermaid C4 Diagram Tutorial: Architecture Diagrams with C4Context and Beyond
The C4 model describes software at four zoom levels, and Mermaid lets you write the top three as text - this guide covers the C4Context, C4Container, and C4Component syntax.
The C4 model is a way of describing software architecture at four levels of zoom - Context, Container, Component, and Code - so that each diagram answers one question at one altitude rather than cramming everything into a single overwhelming picture. Mermaid supports the top three levels directly, which means you can write an architecture model as text and get consistent, standard-shaped diagrams without a dedicated modeling tool. The C4 support in Mermaid is marked experimental, but it covers the syntax teams reach for most.
This tutorial explains the C4 keywords and how the levels build on each other, with snippets ready for the Mermaid editor at /diagram-tools/mermaid-editor. Rendered C4 diagrams open as editable, shareable models in Atlas Diagram Studio at /diagrams, and for teams that prefer a drawing-first approach the C4 diagram tool at /diagram-tools/c4-diagram offers the same model on a canvas. To draft a context diagram from a description of your system, the AI diagram generator at /diagram-tools/ai-diagram-generator is a fast starting point.
The four levels and what Mermaid covers
C4 stands for Context, Container, Component, and Code. A Context diagram shows your system as a single box surrounded by the users and external systems it interacts with - the big-picture view for non-technical stakeholders. A Container diagram zooms in to show the deployable or runnable pieces inside your system, such as a web app, an API, and a database. A Component diagram zooms further into one container to show its internal parts. The fourth level, Code, is usually left to the IDE and is not a Mermaid diagram type.
Mermaid maps these to the keywords "C4Context", "C4Container", and "C4Component", plus "C4Dynamic" and "C4Deployment" for runtime and infrastructure views. You pick the keyword for the altitude you want and then declare the elements at that level. The discipline of the model is that each diagram stays at one level - you do not mix a low-level component into a context diagram - and Mermaid's separate keywords nudge you toward that discipline.
Elements, boundaries, and relationships
Within a C4 diagram you declare the actors and systems with a small set of element functions, then connect them with relationship functions. The syntax is function-call-like: each element takes an alias, a label, and optional description text. The bullets below cover the constructs you will use in almost every C4 diagram.
- 'Person(alias, "Name", "Description")' declares a human user of the system.
- 'System(alias, "Name", "Description")' declares your software system as a whole.
- 'System_Ext(alias, "Name", "Description")' declares an external system you depend on.
- 'Container(alias, "Name", "Technology", "Description")' declares a runnable piece like a web app or API.
- 'Component(alias, "Name", "Technology", "Description")' declares a part inside a container.
- 'Rel(from, to, "Label", "Protocol")' draws a labeled relationship arrow between two elements.
- 'System_Boundary(alias, "Name") { ... }' wraps elements in a boundary box to show they belong together.
Layout and keeping diagrams readable
C4 diagrams can get crowded, so Mermaid offers directional relationship helpers - "Rel_Up", "Rel_Down", "Rel_Left", and "Rel_Right" - that hint the layout engine where to place the connected element, which helps you avoid crossed lines. You can also set the number of boundary columns with a layout configuration to control how elements wrap. These hints matter more in C4 than in some other Mermaid diagrams because architecture diagrams are judged partly on how uncluttered they look.
The best readability lever, though, is staying at one level. A context diagram with three external systems and two users is clear; the same diagram with every internal container crammed in is not. If a diagram feels busy, that is usually a signal to split it - push the internal detail down to a container diagram and keep the context diagram at its proper altitude. This is the whole philosophy of C4, and honoring it produces diagrams that stakeholders at different levels can each actually use.
Fitting C4 into your documentation
C4 shines in living architecture documentation because its leveled structure resists the usual failure of architecture diagrams - the single sprawling picture that tries to show everything and ages instantly. By splitting the model into a stable context view and more volatile container and component views, you can update the parts that change without touching the parts that do not. Writing them as Mermaid means they version in the repository next to the code, so they are reviewed and updated in the same pull requests.
Author your C4 set in the Mermaid editor at /diagram-tools/mermaid-editor, refine and style it in Atlas Diagram Studio at /diagrams, and share it with the team for review. Pair the container view with sequence diagrams for the important flows and an ERD from /diagram-tools/erd-tool for the data model, and you have a documentation set that covers structure, behavior, and data. The guide on documenting software with diagrams and the complete Mermaid reference at /guides/mermaid-js-complete-guide go deeper on assembling that set.