The Binary Blob Problem
Historically, if you wanted a flowchart, you used Visio or Lucidchart, exported a .png image, and uploaded it to the Wiki. This creates a critical problem: the diagram is now a binary blob — an opaque file that Git cannot meaningfully diff. If the architecture changed, you could not "edit" the PNG. You had to find the original source file (if it still existed), update it, re-export it, and re-upload it. In practice, people just did not bother. The diagram stayed wrong for years.
The Solution: Mermaid.js
Mermaid.js allows you to define diagrams using plain text. The browser (or the SSG) renders the text as a diagram dynamically. Because the diagram is just text, it is version-controlled, diffable in Pull Requests, and editable by anyone with a text editor.
Most modern documentation platforms — GitHub, GitLab, Notion, MkDocs with the right plugin — render Mermaid natively. You write a fenced code block with the language set to mermaid, and the platform handles the rest.
A simple service dependency graph:
graph TD;
Client-->LoadBalancer;
LoadBalancer-->Server1;
LoadBalancer-->Server2;
Server1-->Database;
Server2-->Database;
A state machine for an order lifecycle:
stateDiagram-v2
[*] --> Pending
Pending --> Processing : payment_confirmed
Processing --> Shipped : fulfillment_complete
Shipped --> Delivered : delivery_confirmed
Processing --> Cancelled : payment_failed
Shipped --> Returned : return_requested
Mermaid Diagram Types
Mermaid supports a wide range of diagram types, each suited to different documentation needs:
| Type | Keyword | Best For |
|---|---|---|
| Flowchart | graph or flowchart |
Decision trees, process flows |
| Sequence | sequenceDiagram |
API call chains, protocol flows |
| State machine | stateDiagram-v2 |
Lifecycle modeling |
| Entity-Relationship | erDiagram |
Database schema documentation |
| Gantt | gantt |
Project timelines |
| Git graph | gitGraph |
Branching strategy documentation |
The senior-level insight: Diagrams-as-Code is not just about convenience — it is about trust. When a diagram is a PNG, there is no way to know if it reflects the current system. When it is Mermaid text in the same repo as the code, you can run git log docs/architecture.md and see exactly when it was last changed and by whom. That audit trail is what makes the diagram trustworthy.