C4Contextv0.9.4

What is a C4 diagram?

Software architecture at four levels of zoom.

Open in editor →Ready-to-use templates

C4Context

When to use it

Use a C4 when…

Software architecture docs

System context for stakeholders

Onboarding to a new codebase

Syntax basics

The minimal syntax

Copy this and you have a working c4. Build from here.

c4.mmd

C4Context
    title System context for MERMAIDEDITOR
    Person(user, class="code-str">"Reader", class="code-str">"Visits pages, edits diagrams.")
    System(app, class="code-str">"MERMAIDEDITOR", class="code-str">"Static SPA, no backend.")
    System_Ext(auth, class="code-str">"Auth0", class="code-str">"Optional sign-in for Pro.")
    Rel(user, app, class="code-str">"Uses")
    Rel(app, auth, class="code-str">"OIDC")

Common patterns

Patterns worth memorizing

Four levels

C4Context → C4Container → C4Component → C4Dynamic. Start at the top, drill down only as needed.

Boundaries

`Enterprise_Boundary(b, "Acme") { … }` groups elements visually.

External vs internal

`System_Ext(...)` and `Person_Ext(...)` render in lighter colors to signal "not ours".

Common gotchas

The things that will trip you up

Mermaid silently ignores misspellings — these are the failures we see most.

01
C4 in Mermaid is still maturing — for production diagrams many teams pair with PlantUML+C4-PlantUML.
02
Relationships need an explicit verb (`"Uses HTTPS"`); empty `Rel(...)` calls render unlabeled.
03
Layout is hard to control; trust the auto-layout or split into multiple smaller diagrams.

Related diagram types