Mermaid C4 vs C4-PlantUML: Architecture Examples

This article focuses only on C4 architecture diagram expression. It does not cover Markdown support, documentation platform integration, plugins, or rendering services. For those broader tool differences, see the series overview: Mermaid vs PlantUML: Which diagram-as-code tool should you choose in 2026?.

The conclusion needs a little nuance: Mermaid provides an official C4 Diagram syntax, but it is still marked experimental. It is useful for lightweight architecture explanations and quick Markdown embedding. PlantUML teams usually draw C4 diagrams through the C4-PlantUML library, which is more mature for architecture reviews, consistent styling, complex layout, and long-term maintenance.

There is an important boundary here: C4-PlantUML is not a normal built-in PlantUML diagram type in the core UML syntax. It is a C4 macro library built on top of PlantUML. You can use it through the PlantUML standard library with !include <C4/C4_Container>, or include the latest files directly from the C4-PlantUML repository. So the precise comparison is: Mermaid C4 Diagram vs C4-PlantUML.

More precisely:

Mermaid is lightweight and direct. Its C4 syntax is close to part of C4-PlantUML and supports System Context, Container, Component, Dynamic, and Deployment diagrams. For quickly adding a context or container view to Markdown documentation, Mermaid has a low barrier to entry.

C4-PlantUML has the broader ecosystem. It has a more mature include system, layout helpers, tags and stereotypes, themes, legends, sprites, styling, and many examples. It is a better fit when a team treats C4 diagrams as long-lived architecture documentation.

This comparison is based on official documentation:

• Mermaid C4 Diagram documentation
• C4-PlantUML official repository
• PlantUML Standard Library documentation

Key Differences

In one sentence:

Mermaid C4 is good for quick architecture views; C4-PlantUML is better when C4 becomes a maintained architecture language for the team.

Mermaid Can Quickly Draw a C4 Context Diagram

A C4 Context diagram focuses on the system boundary: who uses the system, and which external systems it interacts with. Mermaid can express the core elements: Person, System, System_Ext, and Rel.

Mermaid

C4Context
  title System Context diagram for OnUML

  Person(user, "Diagram Author", "Creates and edits architecture diagrams")
  System(onuml, "OnUML", "Diagram-as-code editor for Mermaid and PlantUML")
  System_Ext(github, "GitHub", "Stores documentation and source code")
  System_Ext(email, "Email Service", "Sends workspace notifications")

  Rel(user, onuml, "Creates diagrams with")
  Rel(onuml, github, "Exports documentation to")
  Rel(onuml, email, "Sends notifications through")

C4-PlantUML

@startuml
!include <C4/C4_Context>

title System Context diagram for OnUML

Person(user, "Diagram Author", "Creates and edits architecture diagrams")
System(onuml, "OnUML", "Diagram-as-code editor for Mermaid and PlantUML")
System_Ext(github, "GitHub", "Stores documentation and source code")
System_Ext(email, "Email Service", "Sends workspace notifications")

Rel(user, onuml, "Creates diagrams with")
Rel(onuml, github, "Exports documentation to")
Rel(onuml, email, "Sends notifications through")
@enduml

For simple Context diagrams, the difference is small. Mermaid avoids include statements and PlantUML wrappers, which is convenient for docs. C4-PlantUML becomes more valuable when the diagram set grows and needs a stronger ecosystem.

Container Diagrams Work in Both Tools

A Container diagram shows the deployable or runnable units inside a system, such as a web app, API, database, or queue.

Mermaid

C4Container
  title Container diagram for OnUML

  Person(user, "Diagram Author", "Creates architecture diagrams")

  System_Boundary(onuml, "OnUML") {
    Container(web, "Web App", "Next.js", "Provides editor and documentation UI")
    Container(api, "API Routes", "Next.js Edge Runtime", "Handles rendering and workspace requests")
    ContainerDb(db, "Database", "PostgreSQL", "Stores users, projects, and workspaces")
    ContainerQueue(queue, "Job Queue", "Queue", "Processes async rendering jobs")
  }

  System_Ext(email, "Email Service", "Sends notifications")

  Rel(user, web, "Uses")
  Rel(web, api, "Calls", "HTTPS")
  Rel(api, db, "Reads and writes")
  Rel(api, queue, "Publishes jobs")
  Rel(api, email, "Sends email through")

C4-PlantUML

@startuml
!include <C4/C4_Container>

title Container diagram for OnUML

Person(user, "Diagram Author", "Creates architecture diagrams")

System_Boundary(onuml, "OnUML") {
  Container(web, "Web App", "Next.js", "Provides editor and documentation UI")
  Container(api, "API Routes", "Next.js Edge Runtime", "Handles rendering and workspace requests")
  ContainerDb(db, "Database", "PostgreSQL", "Stores users, projects, and workspaces")
  ContainerQueue(queue, "Job Queue", "Queue", "Processes async rendering jobs")
}

System_Ext(email, "Email Service", "Sends notifications")

Rel(user, web, "Uses")
Rel(web, api, "Calls", "HTTPS")
Rel(api, db, "Reads and writes")
Rel(api, queue, "Publishes jobs")
Rel(api, email, "Sends email through")
@enduml

If the diagram only needs Person, System, Container, Database, Queue, and relationships, both tools can express the core architecture. C4-PlantUML becomes more valuable when you need consistent style and layout across many diagrams.

C4-PlantUML Is Better for Architecture Standards

Mermaid's official C4 documentation says C4 Diagram is experimental and that syntax and properties can change. It also notes that styling is relatively fixed, layout is influenced by declaration order, and features such as tags, links, and Legend are not fully supported.

C4-PlantUML is better suited for team-level architecture standards. It provides:

• LAYOUT_* and Lay_* helpers for layout control.
• Tags and stereotypes for risk, external systems, legacy systems, cloud services, and other categories.
• Themes, skinparam, and style extensions for consistent output.
• Legends to explain colors, line styles, and markers.
• Sprites and icons for cloud providers, technologies, or custom assets.

Here is a review-oriented C4-PlantUML example that marks a legacy system and shows a legend.

C4-PlantUML

@startuml
!include <C4/C4_Container>

AddElementTag("legacy", $bgColor="#fff3cd", $borderColor="#b7791f", $legendText="Legacy system")
AddRelTag("async", $lineStyle=DashedLine(), $legendText="Async message")

title Container diagram with architecture review tags

Person(user, "Diagram Author")

System_Boundary(onuml, "OnUML") {
  Container(web, "Web App", "Next.js", "Editor and documentation UI")
  Container(api, "API Routes", "Next.js Edge Runtime", "Workspace and rendering API")
  ContainerQueue(queue, "Job Queue", "Queue", "Async rendering jobs")
}

System_Ext(oldRenderer, "Legacy Renderer", "Old rendering service", $tags="legacy")

Rel(user, web, "Uses")
Rel(web, api, "Calls")
Rel(api, queue, "Publishes job", $tags="async")
Rel(api, oldRenderer, "Falls back to")

SHOW_LEGEND()
@enduml

Mermaid Approximation

C4Container
  title Container diagram with architecture review notes

  Person(user, "Diagram Author")

  System_Boundary(onuml, "OnUML") {
    Container(web, "Web App", "Next.js", "Editor and documentation UI")
    Container(api, "API Routes", "Next.js Edge Runtime", "Workspace and rendering API")
    ContainerQueue(queue, "Job Queue", "Queue", "Async rendering jobs")
  }

  System_Ext(oldRenderer, "Legacy Renderer", "Old rendering service")

  Rel(user, web, "Uses")
  Rel(web, api, "Calls")
  Rel(api, queue, "Publishes job")
  Rel(api, oldRenderer, "Falls back to")

Mermaid can express the main structure, but it is not ideal for a full architecture standard:

• Mermaid C4 is still experimental.
• Mermaid C4 layout control is limited and complex diagrams can depend heavily on declaration order.
• Mermaid official documentation lists tags, links, and Legend as unsupported short-term items.
• C4-PlantUML can use tags, themes, legends, sprites, and layout helpers to create a team standard.

When to Choose Which

Choose Mermaid for C4 diagrams when:

• You want to quickly explain a system context or container relationship.
• The diagram belongs in README, Markdown docs, or lightweight design notes.
• The diagram mostly uses Person, System, Container, Database, Queue, and Rel.
• You do not need complex layout, tags, legends, themes, or visual standards.
• You can accept Mermaid C4's current experimental status.

Choose C4-PlantUML when:

• You are building a long-lived architecture diagram set.
• You need Context, Container, Component, Dynamic, and Deployment views.
• You need layout control, tags, stereotypes, legends, themes, sprites, or style rules.
• The diagrams are part of architecture reviews, ADRs, design archives, or governance.
• You want the more mature C4 ecosystem and examples.

FAQ

Is Mermaid C4 stable?

Not fully. Mermaid's official documentation marks C4 Diagram as experimental and says syntax and properties can change. It is fine for lightweight documentation, but use caution for long-term architecture assets.

Does PlantUML support C4 natively?

More precisely, PlantUML supports C4 through the C4-PlantUML library. You can include remote C4-PlantUML files or use the PlantUML standard library includes such as <C4/C4_Container> and <C4/C4_Context>.

Are Mermaid C4 and C4-PlantUML syntax compatible?

Mermaid's documentation says its C4 syntax is compatible with part of C4-PlantUML and recommends C4-PlantUML syntax as a reference. That does not mean full equivalence. Mermaid C4 still has limitations around tags, links, Legend, and some styling capabilities.

How should I choose based only on diagram capability?

If you just need a quick Context or Container diagram, Mermaid is convenient. If you need a full architecture documentation system with multiple views, style standards, tags, legends, and layout control, C4-PlantUML is the better fit.

Bottom line:

For C4 diagrams, Mermaid is lightweight, easy to embed, and fast to start. C4-PlantUML is more mature, more complete, and better for team-wide architecture documentation.

You can try the examples in the OnUML editor by switching between Mermaid and PlantUML modes.