Mermaid.js: Architecture Diagrams as Code for Developer Documentation

TL;DR:

• Mermaid.js renders diagrams from plain text in Markdown — GitHub, GitLab, Notion, Obsidian, Confluence (plugin), and the Mermaid Live Editor all support it natively
• You write flowcharts, sequence diagrams, ER diagrams, Gantt charts, and more as code that lives in your repository and gets reviewed in PRs like any other change
• The biggest practical win: architecture docs that stay in sync with the code instead of living in a forgotten Confluence page

The problem with architecture diagrams is the same as the problem with comments: they start accurate and end stale. A Visio file or Lucidchart export checked into docs/ as a PNG tells you what the architecture looked like when someone last exported it, which may have been two product cycles ago.

Mermaid.js takes a different approach. The diagram is text. The text lives in the repo. The diagram renders wherever Markdown renders.

Getting Started in 60 Seconds

No installation required for GitHub or GitLab. Just add a code block with the mermaid language tag in any Markdown file:

```mermaid
graph TD
    A[User Request] --> B[API Gateway]
    B --> C{Auth Check}
    C -->|Valid Token| D[Service Layer]
    C -->|Invalid| E[401 Response]
    D --> F[Database]
    D --> G[Cache]
    F --> H[Response]
    G --> H
```

GitHub renders this directly in the README. GitLab does the same. No plugins, no exports.

Diagram Types You’ll Actually Use

Flowcharts

The workhorse. Good for request flows, decision trees, deployment pipelines.

flowchart LR
    dev[Developer] -->|git push| gh[GitHub]
    gh -->|trigger| ci[CI Pipeline]
    ci -->|tests pass| staging[Staging Deploy]
    ci -->|tests fail| notify[Notify Slack]
    staging -->|approval| prod[Production Deploy]

Direction options: LR (left-right), TD (top-down), RL, BT. Use LR for pipeline flows, TD for hierarchies.

Sequence Diagrams

For API call flows, authentication sequences, multi-service interactions. Especially useful when reviewing how a new service integrates with existing ones.

sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant DB

    Client->>API: POST /login {email, password}
    API->>Auth: validateCredentials(email, password)
    Auth->>DB: SELECT user WHERE email = ?
    DB-->>Auth: user record
    Auth-->>API: {userId, roles}
    API-->>Client: 200 {token, expiresIn}

Arrows: ->> (solid, async), -->> (dashed, return), -> (solid, sync). The dashed arrows for responses is a useful visual convention.

Entity-Relationship Diagrams

For database schemas in PRs. Reviewers can see the relationships without checking the migration files.

erDiagram
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total
        string status
        timestamp created_at
    }
    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        int quantity
        decimal unit_price
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

State Diagrams

For documenting state machines — order statuses, payment flows, content moderation states.

stateDiagram-v2
    [*] --> Draft
    Draft --> InReview : submit
    InReview --> Approved : approve
    InReview --> Draft : request changes
    Approved --> Published : publish
    Published --> Archived : archive
    Archived --> [*]

C4 Architecture Diagrams

For higher-level system context and container diagrams:

C4Context
    title System Context — Order Management
    
    Person(customer, "Customer", "Places and tracks orders")
    System(oms, "Order Management System", "Handles order lifecycle")
    System_Ext(payment, "Payment Provider", "Stripe")
    System_Ext(shipping, "Shipping Provider", "Royal Mail API")
    
    Rel(customer, oms, "Uses", "HTTPS")
    Rel(oms, payment, "Charges", "HTTPS/REST")
    Rel(oms, shipping, "Books", "HTTPS/REST")

Where Mermaid Renders

The Mermaid Live Editor at mermaid.live is invaluable for iterating — paste your diagram, see it render instantly, export as SVG or PNG.

Integrating Into Your Workflow

Put diagrams in the PR: The most practical adoption pattern is requiring architecture diagrams in PRs for any service boundary changes. When someone adds a new service or modifies an integration, the PR includes an updated sequence diagram. Reviewers can read it in the GitHub diff.

Architecture Decision Records (ADRs): Embed flowcharts and sequence diagrams in your ADR template. The diagram explains the decision visually; it lives in docs/adr/ with the text.

README architecture section: A README.md with a system diagram at the top is genuinely useful for new engineers joining. Keep it to the top-level system context only — detailed sequence diagrams belong in service-specific docs.

CLI rendering for CI: The @mermaid-js/mermaid-cli package renders diagrams to PNG/SVG in CI:

npm install -g @mermaid-js/mermaid-cli
mmdc -i architecture.mmd -o architecture.png

Useful for generating documentation site assets or embedding in generated PDF reports.

Common Pitfalls

Complex diagrams become unreadable. If your flowchart has more than ~15 nodes, split it. A top-level system diagram and a detailed flow for each major subsystem is better than one enormous graph.

Syntax errors are silent in GitHub. If a diagram doesn’t render, GitHub shows nothing — no error, just a blank block. Test in mermaid.live first, then paste into the PR.

Subgraphs for grouping:

graph TD
    subgraph Frontend
        UI[React App]
        Cache[Browser Cache]
    end
    subgraph Backend
        API[FastAPI]
        DB[PostgreSQL]
    end
    UI --> API
    API --> DB

The text-first approach won’t suit every team. For complex infrastructure diagrams with precise positioning requirements, dedicated tools like Excalidraw or draw.io still have their place. But for service flows, database schemas, state machines, and sequence diagrams in a repository — Mermaid is usually the right default.