Mermaid vs a Diagram Canvas: When Diagrams as Code Work, and When They Don't

Few tooling debates in engineering teams last as long as this one. Some people want every diagram as code, in Mermaid, reviewed in pull requests. Others want a canvas where they can move boxes around and see the system. Both camps are right, about different diagrams.

This guide compares Mermaid and a diagram canvas honestly: what each does well, where each breaks down, a decision table for common cases, and the same small system drawn both ways.

What Mermaid does well

Mermaid turns a few lines of text into a diagram. That has real advantages:

• It lives next to the code. A diagram in a Markdown file changes in the same pull request as the code it describes, and reviewers see the diff.
• It renders where engineers already are. GitHub and GitLab render Mermaid code blocks in Markdown files, issues and pull requests, and tools such as Notion and Obsidian display them too.
• No extra tool or account. Anyone who can edit the file can edit the diagram.
• Sequence diagrams are excellent. For a request flow between four services, Mermaid's sequence syntax is hard to beat.
• AI assistants write it fluently. Ask any chat assistant for a Mermaid flowchart and you get valid syntax most of the time.

Where Mermaid struggles

• You do not control the layout. Mermaid places nodes automatically. Add one edge and the picture can rearrange itself, and past a couple of dozen nodes it becomes hard to read.
• Text diffs hide visual changes. A one-line change in a pull request can move half the diagram, and reviewers only see the line.
• The vocabulary is thin for infrastructure. Flowchart shapes are generic. Newer architecture and C4 diagram types exist, but they are less mature than flowcharts and sequence diagrams.
• Non-engineers rarely edit it. Product managers, designers and support teams can read the result but usually do not change the source.
• No shared, live session. You edit text in your editor; there are no cursors, no live review and no one watching a change land.

What a canvas does well

• Layout is yours. Position carries meaning: the edge of a trust boundary, the left-to-right flow of a request, the cluster in the middle.
• Typed nodes and frames. On a canvas like Archboard, a Kubernetes Service or a C4 container is a node with ports, and namespaces or VPCs are frames that hold their contents.
• Everyone can edit. People who never open the repository can still fix a label or add a note.
• Live collaboration and sharing. Several people, and AI agents, edit together with cursors, and a live link or an embed keeps every reader on the current version.

Where a canvas struggles

• It drifts from the code unless updating it is part of your workflow. A canvas is not in the pull request by default.
• Some formats are opaque. A PNG or a proprietary file cannot be diffed or generated. Archboard mitigates this with JSON export and a published JSON Schema, but a JSON document is still not a ten-line Markdown block.
• It needs a tool. Readers can view a share link without an account, but editors need one.

A decision table

The pattern: Mermaid wins when the diagram belongs to one change and lives in the code. A canvas wins when the diagram belongs to the team and outlives any single change.

The same system, both ways

Here is a small system in Mermaid:

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

It is readable, it diffs well, and GitHub renders it. Now the same flowchart on a canvas. We gave it to an AI agent connected to Archboard over MCP, with a mapping from Mermaid ids to node types: user to a C4 person, web, api and worker to C4 containers, db to Postgres, q to a Topic, mail to an external system. The agent drew it in one step, and a second step arranged it into two rows:

The subgraph became a frame, the nodes became typed nodes with ports, and the result is a starting point you can now arrange, annotate and share like any other diagram.

Use both, on purpose

A workable split for most teams:

1. Mermaid for diagrams that belong to a change: sequence diagrams in design docs and pull requests, state machines next to code, small flowcharts in READMEs.
2. A canvas for diagrams that belong to the team: system overviews, infrastructure, security reviews, onboarding.
3. Bridge them. Start from Mermaid when you already have it: an agent connected to Archboard over MCP can turn a Mermaid flowchart into a canvas diagram with real node types. Export the canvas as JSON into the repository when you want it reviewed with the code, and link the live diagram from the README.

FAQ

Can I paste Mermaid into the Archboard editor? Not directly today. An AI agent connected over MCP can draw a Mermaid flowchart, including subgraphs, as a canvas diagram with real node types. Other Mermaid diagram kinds, such as sequence diagrams, are not converted.

Does a canvas diagram show up in pull requests? Not by itself. Export it as JSON or SVG into the repository if you want it reviewed with the code, or link the live diagram from the pull request.

Is diagrams as code always more up to date? Only if people update it. A Mermaid block that nobody touches goes stale as fast as a canvas; the difference is that it sits closer to the change that should update it.

What about PlantUML or Structurizr? Same trade-offs. PlantUML is strong for UML and sequence diagrams; Structurizr is built for C4 models as code. Choose by who edits the diagram and how long it has to live.

Which one do AI assistants handle better? Both. Assistants write Mermaid fluently, and through MCP an agent can also edit a canvas directly, where people see the change live and can undo it.

Start free — one seat, no credit card.