⚡️ TL;DR
- Mermaid is a great way to put a diagram next to your code. It’s free and it renders natively in GitHub and most docs tools.
- It falls down when you have more than a handful of diagrams, because every Mermaid block is a standalone picture with no shared model behind it.
- If your architecture is simple and doesn’t need to span teams and agents, use Mermaid. If it spans 40 services and five teams, you need a model, and that’s what IcePanel is for.
🧊 Let’s kick off
Here’s a relatable scenario. Someone asks how the payments service actually talks to the ledger, and you find three Mermaid blocks across two repos and a Confluence page. All three conflict with each other. Nobody knows which one was updated last, and nobody wants to be the person who checks.
Mermaid is doing exactly what it was designed to do, render text into a picture, right where the text lives. The problem is that it isn’t an accurate view of our whole system.
📝 What Mermaid is good at
Pricing: Free. Mermaid.js is MIT licensed. Mermaid Chart, the hosted editor from the same team, has a free Basic tier plus paid Plus, Premium and Enterprise plans.
Best for: engineers who want a diagram to live in the same pull request as the code it describes.
What you get:
- Close to 30 diagram types: flowcharts, sequence, ER, class, state, Gantt, C4, and newer ones like block, Wardley and treemap
- Native rendering in GitHub, GitLab, Notion, Obsidian and most static site generators
- Text in, picture out so diffs are reviewable and history is free
- LLMs write it well, which makes it a natural output format for AI-generated docs
😖 Where it starts to hurt
Every diagram is its own island. Mermaid has no model underneath it. If you rename OrdersAPI to OrderService, there is no way to know which of your 40 diagram blocks mention it. You go and find them, by hand, one grep at a time. This is the same failure mode as any shape-based tool, it just happens in a text editor instead of on a canvas.
C4 support is still experimental. Mermaid’s docs make it explicit: “This is an experimental diagram for now. The syntax and properties can change in future releases.” Sprites, tags, links and legends aren’t supported yet, the Lay_U/Lay_D/Lay_L/Lay_R layout directives don’t work, and the docs note that “the position of shapes is adjusted by changing the order in which statements are written.” Your Level 2 layout is a function of what order you happened to type things in.
There’s no drill-down. C4’s whole value is that a stakeholder reads Level 1 and an engineer reads Level 3, from the same underlying model. In Mermaid, those are two unrelated code blocks that you keep in sync by remembering to. Visualization of diagrams is limited.
There’s no ownership or embedded review process. No owners on objects, no read-only Model Viewer for the people who only want to look, no drafts for proposing a future-state design before it’s real. Every change is a PR against a text file, which is fine for code and awkward for a landscape that fifteen people need to agree on.
🔁 “But I want my architecture in Git”
Fair. That’s the real reason most teams pick Mermaid, and it’s a good reason.
The distinction worth drawing is diagrams as code versus model as code. Mermaid gives you the first. IcePanel gives you the second. You can import and export your objects, connections and tags as plain JSON or YAML, via the app or the API/SDK (TypeScript, C#, Go, Java, Python, cURL). There’s an MCP server on paid plans too, so an agent can read the model and update it directly. There’s also a skill that allows you to create diagrams from code or a prompt.
So the model still lives in version control if you want it to. The difference is that you update it once, and every diagram, every level, and every flow updates with it. No hunting and excessive token spend.
💰 Pricing
- Mermaid: Free, Plus ($10/user/mo), Premium ($20/user/mo), Enterprise
- IcePanel: Free, Growth ($40/user/mo), Scale ($80/user/mo), Enterprise
🏁 To wrap up
- If your system is simple and the audience is other engineers reading the repo, use Mermaid. No need to overthink it.
- If you want C4 specifically and you’re relying on Mermaid’s C4 syntax, know that you’re building on something that’s still experimental.
- If you’re maintaining diagrams across multiple teams and they keep going stale, that’s not a syntax problem, it’s a missing model. IcePanel is built for that.
- And using both is completely reasonable. A Mermaid sequence diagram in a PR to explain one change, IcePanel for the source of truth.
The test is simple: when something in your architecture changes, how many places do you have to go and fix? If the answer is more than one, you’ve outgrown diagrams-as-code.
