Skip to content
MermaidViewer

Software diagram

Mermaid C4 diagram

Mermaid C4 diagram syntax for context and container diagrams, with people, systems and relationships.

By MermaidViewer editorsPublished Updated

Basic c4 diagram example

Basic c4 diagram example diagram
mermaid
C4Context
    title System context – Online banking
    Person(customer, "Customer", "A bank customer")
    System(bank, "Internet Banking", "Lets customers view accounts and make payments")
    System_Ext(mail, "Email system", "Sends notifications")
    System_Ext(core, "Core banking", "Stores accounts and transactions")
    Rel(customer, bank, "Uses")
    Rel(bank, core, "Reads/writes", "HTTPS")
    Rel(bank, mail, "Sends emails", "SMTP")
    Rel(mail, customer, "Emails")
Open in the live editor

The C4 model describes software architecture at four zoom levels: system context, containers, components and code. Mermaid supports C4 context, container, component, dynamic and deployment diagrams with a syntax compatible with C4-PlantUML.

C4 diagrams answer questions like who uses the system, which applications and databases it consists of, and how they communicate — ideal for architecture decision records and onboarding docs.

When to use a c4 diagram

  • System context for stakeholders
  • Container diagrams for engineering onboarding
  • Architecture decision records (ADRs)
  • Security and compliance reviews

C4 Diagram syntax reference

SyntaxWhat it does
C4Context / C4Container / C4Component / C4Dynamic / C4DeploymentPick the C4 diagram level.
Person(alias, "Label", "Description")A user or role.
System(alias, …) / System_Ext(alias, …)Internal / external software system.
Container(alias, "Label", "Tech", "Description")An application or data store.
ContainerDb(alias, …)Database container.
System_Boundary(alias, "Label") { … }Group elements in a boundary.
Rel(from, to, "Label", "Tech")Relationship between elements.

C4 Diagram examples

Container diagram

Zoom into a system to show its applications and data stores.

Container diagram diagram
mermaid
C4Container
    title Containers – Diagram SaaS
    Person(user, "User")
    System_Boundary(app, "MermaidViewer") {
      Container(web, "Web app", "Next.js", "Editor and pages")
      Container(api, "API", "Node.js", "Auth, diagrams, AI")
      ContainerDb(db, "Database", "PostgreSQL", "Users and diagrams")
    }
    System_Ext(ai, "OpenAI", "LLM API")
    Rel(user, web, "Uses", "HTTPS")
    Rel(web, api, "Calls", "JSON")
    Rel(api, db, "Reads/writes", "SQL")
    Rel(api, ai, "Prompts", "HTTPS")
Open in the live editor

People and systems, and a verb between them, are the context view. A mermaid c4 diagram at this level hides databases, classes, and queues on purpose. If a box isn't something a user could name, it's probably a level too low. The syntax table lists Person, System, and Rel. This section is about keeping a context diagram small enough to brief someone.

Persons, systems, and relationships

C4Context starts the diagram. Person(user, "User") is a person. The first argument is the id, a token you'll reuse. The quoted string is the label. System(app, "Notes", "Stores pages") is a system you own. The third argument is a one-line description, not a feature list.

Rel(user, app, "Writes") draws the arrow. The arguments are source, target, and a verb. Quote the verb. An unquoted Uses fails the parse. The verb should be something the source does to the target. "Writes" is better than "related to."

Two systems are enough when one is yours and one is a neighbor, such as mail. You don't need a box for every process inside the app. Those belong on a container diagram later. The context diagram's promise is that a new teammate can read it in a minute and know who is outside the boundary.

Ids stay stable when labels change. mail can be labeled "Mail" today and "Postmark" later without retargeting every Rel, as long as you keep the id.

Worked example

A person writes in a notes app. The app notifies a mail system. That's the whole context.

Mermaid diagram
mermaid
C4Context
    Person(user, "User")
    System(app, "Notes", "Stores pages")
    System(mail, "Mail", "Sends mail")
    Rel(user, app, "Writes")
    Rel(app, mail, "Notifies")
Open in the live editor

user is outside, which is what Person signals. app is the product. The description "Stores pages" is deliberately dull. If it said "React, Postgres, and a queue," you would have smuggled an implementation into a context view. mail is a separate system because you don't build it. The two relationships are the only behaviors this picture claims: people write notes, and the app sends notifications.

If you need to show the browser, the API, and the database, you have left context. Start a new diagram for that level instead of adding three systems here. A context diagram with twelve boxes is a container diagram that refused to change keyword.

Descriptions wrap poorly when they're long. "Stores pages" fits. "Stores pages, shares them, and indexes them for search" belongs in the doc under the picture. The same rule applies to people. "User" is enough when there's one human role. Split into "Admin" and "Member" only when they touch different systems. Two persons with the same arrows are one person drawn twice, and the diagram gets wider without saying anything new. Read the verbs in a circle before you ship it. Each Rel should still make sense if you say it aloud as "source verb target."

When this is the wrong diagram

An architecture diagram is the better picture when you want cloud icons, a network boundary, and deployment boxes. A sequence diagram is the better picture when the order of calls is the design. Use a C4 context diagram when the audience needs the boundary and the neighbors, not the internals.

Common mistakes

  1. An unquoted label or verb, as in Rel(user, app, Uses). Quote the text arguments: Rel(user, app, "Uses").
  2. A space in an id, or a fresh id that doesn't match the Person or System you declared. Rel resolves ids, not labels.
  3. Putting databases, frameworks, and queues in a context description. The third argument is one line about purpose.
  4. A relationship verb with no direction in the sentence, such as "integration." Use a verb the source does: "Writes", "Notifies", "Pays".

Where to go next

The AI C4 generator will draft a context view from a product description. Cut boxes in the editor until a new hire can read it quickly, and the cheat sheet lists Person, System, and Rel. The SaaS context template shows the same level with a few more neighbors.

One system in the middle

A context diagram has one system you are building and the people and systems around it. If two boxes are both "the system," you drew a container diagram and labeled it wrong. Containers are the deployable pieces inside that one system. Components are the modules inside one container. Mixing those levels on one chart is how a C4 picture becomes a poster.

Relationship labels are verbs the person does: "Sends receipts", "Charges card". "Connected to" says nothing. The C4 guide walks the levels, and the SaaS context template is a filled-in start.

Tips and best practices

  • Start at the context level and only zoom in where readers need more detail.
  • Always include the technology on containers and relationships — it's the most useful information for engineers.
  • If the automatic layout gets crowded, consider an architecture-beta or flowchart diagram instead.

Generate a c4 diagram with AI

Not sure where to start? Describe what you need and the AI c4 diagram generator writes the Mermaid code for you. Try prompts like:

  • “Container diagram for a food delivery platform”
  • “System context for a hospital records system”
  • “Microservices e-commerce architecture”

C4 Diagram templates

C4 Diagram FAQ

Is Mermaid C4 compatible with C4-PlantUML?

The syntax is largely compatible with C4-PlantUML macros such as Person, System, Container and Rel, so many diagrams can be ported with small changes.

Which C4 levels does Mermaid support?

System context (C4Context), container (C4Container), component (C4Component), dynamic (C4Dynamic) and deployment (C4Deployment) diagrams.