Sign in Subscribe
System Design

Using Mermaid.js to Generate Live System Diagrams from Markdown

Doron Katz

• 3 min read
Using Mermaid.js to Generate Live System Diagrams from Markdown
Photo by Bruce Christianson / Unsplash

Version-Control Your Architecture Diagrams Like Code

I often solicit architectural diagram from teams as part of production readiness reviews, and just as often lament the number of times I come across stale diagrams. You’ve seen it before: outdated Visio charts buried in a SharePoint folder, or a PNG diagram with no context or history behind it.

I recently came across a nifty tool, Mermaid.js which comes in a lightweight, markdown-friendly syntax that allows you to create version-controlled, easy-to-update architecture diagrams directly in your documentation.

In this article, I’ll demonstrate how as a TPM you can:

  • Write system architecture diagrams using Mermaid syntax
  • Embed those diagrams in Markdown-based platforms (such as GitHub)
  • Version-control your diagrams just like code.
I may also do a video version of this presentation, stay tuned!

Why Use Mermaid.js as a TPM?

As a TPM, you’re often the bridge between technical and non-technical stakeholders. As the conduit, leveraging clear diagrams helps everyone align faster. We have historically relied on traditional diagram tools like LucidChart or draw.io, and while they are great diagramming tools, if they don’t get updated they aren’t worth much, and it’s hard to continuously keep the updated.

Low and behold, Mermaid solves this by letting you write your diagrams rapidly in plain text, using simple syntax, and render them on the fly.

Getting Started with Mermaid.js

1. The Basics: Mermaid in Markdown

Let’s start off by installing Mermaid.js. Firstly, make sure you have node installed. There are tons of instructions online on how to do that on your Mac or Windows machine.

Next, install the app itself in terminal:

npm install mermaid

Install the CLI as well:

npm install -g @mermaid-js/mermaid-cli

Next, we will create a simple systems architecture flowchart. In your favorite code editor, create a file called diagram.mmd. 

graph TD
  user[User]
  web[Web App]
  api[API Layer]
  db[(Database)]

  user --> web --> api --> db

To see it visually, run the following:

mmdc -i diagram.mmd -o diagram.svg

You can now open up the file and it will render something like this:

In GitHub or GitLab, this block renders as a dynamic diagram. Updating the diagram? Just update the text. Simple as that.

2. Common Use Cases for TPMs

Some common use cases for using this tool as a TPM could include:

  • System architecture diagrams: Show flow between services, APIs, or databases
  • Decision trees: Represent product paths or incident decision-making
  • Gantt charts: Visualize project timelines right in README.md
  • Dependency maps: Model microservice or pipeline dependencies

Version Controlling Your Diagrams

As a text-based file, Mermaid diagrams are easily version-controlled in Git alongside your application code.

Benefits

Why use Mermaid? As a TPM for me it allows me to document:

  • Traceability: Know when and why a system changed.
  • Peer review: Engineers can suggest diagram edits via PRs.
  • Rollback capability: Revert to previous diagram versions like code.
“[Good documentation] is a way to think together—across space and time.”
— Sarah Drasner, Engineering Manager, Google

An Example: TPM System Overview Diagram

Let’s say you’re building a new internal SRE platform. Here’s a simplified Mermaid diagram:

graph LR
  User -->|Request| Frontend
  Frontend -->|API Call| Backend
  Backend -->|Queries| PostgreSQL
  Backend -->|Events| Kafka
  Kafka -->|Consume| Monitoring[Monitoring Service]

This makes it crystal clear to engineers, SREs, and leadership what connects to what, without requiring any design tool expertise.

Tips for TPM Adoption

I’ve noted some tips and ideas for integrating this tool as part of your teams’ workflows:

  • Create a diagram repo: Store architecture diagrams in a dedicated GitHub repository or /docs folder.
  • Integrate into reviews: Add Mermaid updates to design or readiness review processes.
  • Document standards: Create guidelines for formatting, naming conventions, and storage location of diagrams.

Conclusion: Make Diagrams a Living Part of Your Program

Static diagrams die in folders. Living diagrams live in code.

Adopting tools like Mermaid.js helps TPMs:

  • Document technical systems more accurately
  • Foster better cross-team understanding
  • Keep architecture aligned with evolving systems
“If it’s not in version control, it doesn’t exist.”
— Unknown Engineering Wisdom

No design degree required. Just Markdown.

References: