Mermaid.js Architecture Diagrams: Complete Guide for 2026

# Mermaid.js Architecture Diagrams: Complete Guide for 2026

Software architecture diagrams are the most common reason developers reach for a diagramming tool. And yet, most teams end up with a half-updated Lucidchart link buried in a Confluence page that nobody trusts.

Mermaid.js fixes this by making architecture diagrams part of your code. They live in your repo, they're reviewed in pull requests, and they get updated when the system changes. This guide covers every approach for drawing architecture diagrams in Mermaid.js — from simple flowcharts to layered cloud infrastructure.

Why Mermaid.js for Architecture Diagrams?

Before picking a tool, the question is: *where does the diagram live?*

- A PNG in Google Drive goes stale in weeks

- A link to Lucidchart requires another tool's login

- A Mermaid diagram in your README stays next to the code it describes

Architecture diagrams as code means:

• PR reviews catch stale docs — when the code changes, reviewers see if the diagram didn't
• No drag-and-drop overhead — write once, render everywhere GitHub/GitLab/Notion support Mermaid
• Diff-friendly — git diff shows exactly what changed in the architecture
• Automatable — generate diagrams programmatically from infra configs

Which Mermaid Diagram Type for Architecture?

Mermaid offers several diagram types. Here's which to use for architecture work:

System Architecture Flowchart

The workhorse for architecture documentation. A left-to-right flowchart with subgraphs maps perfectly to layered systems:

flowchart LR
    subgraph Client["Client Layer"]
        Web["React SPA"]
        Mobile["iOS / Android"]
    end

    subgraph Edge["Edge Layer"]
        CDN["CloudFront CDN"]
        WAF["Web Application Firewall"]
    end

    subgraph API["API Layer"]
        GW["API Gateway"]
        Auth["Auth Service"]
    end

    subgraph Services["Business Services"]
        Users["User Service"]
        Orders["Order Service"]
        Notify["Notification Service"]
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL")]
        Redis[("Redis Cache")]
        S3["S3 / Object Store"]
    end

    Web & Mobile --> CDN
    CDN --> WAF
    WAF --> GW
    GW --> Auth
    GW --> Users & Orders & Notify
    Users & Orders --> PG
    GW --> Redis
    Notify --> S3

This renders as a full system diagram with five clearly separated layers. Change a service name or add a new one — two seconds of text editing and the diagram is updated.

Microservices Architecture Diagram

For microservices, the key is showing service boundaries and communication patterns. Subgraphs represent bounded contexts or domains:

flowchart TD
    subgraph Gateway["API Gateway"]
        GW["Kong / NGINX"]
    end

    subgraph Identity["Identity Domain"]
        AuthSvc["Auth Service"]
        UserSvc["User Service"]
        AuthDB[("Users DB")]
    end

    subgraph Commerce["Commerce Domain"]
        CatalogSvc["Catalog Service"]
        OrderSvc["Order Service"]
        PaySvc["Payment Service"]
        CommerceDB[("Commerce DB")]
    end

    subgraph Messaging["Async Messaging"]
        Queue["Message Broker (RabbitMQ / Kafka)"]
    end

    subgraph Infra["Shared Infrastructure"]
        Cache[("Redis")]
        Storage["Object Storage"]
    end

    Client(["Client"]) --> GW
    GW --> AuthSvc & CatalogSvc & OrderSvc
    AuthSvc --> AuthDB
    UserSvc --> AuthDB
    CatalogSvc --> CommerceDB
    OrderSvc --> CommerceDB
    OrderSvc --> Queue
    Queue --> PaySvc & Notify["Notification Service"]
    PaySvc --> CommerceDB
    GW --> Cache

The domain groupings immediately communicate ownership boundaries — something flat node lists can't do.

Cloud Infrastructure Block Diagram

For cloud infrastructure, the block-beta syntax gives you direct grid control. It's better than a flowchart for diagrams where spatial zones carry meaning — VPCs, availability zones, security tiers:

block-beta
  columns 5
  block:Internet:5
    Users["Users / Internet"]
    CF["CloudFront"]
  end
  ALB["Application Load Balancer"]:5
  block:AZ1:2
    ECS1["ECS Task 1"]
    ECS2["ECS Task 2"]
  end
  block:AZ2:2
    ECS3["ECS Task 3"]
    ECS4["ECS Task 4"]
  end
  space:1
  RDS["RDS Primary (Multi-AZ)"]:2 Elastic["ElastiCache"]:2 S3Bucket["S3"]:1

The columns 5 declaration controls the grid, and :N spans give you layout control that flowcharts can't provide.

Sequence Diagram for Architecture Flows

System diagrams show *what exists*. Sequence diagrams show *how components interact at runtime*. Both are essential for a complete architectural picture:

sequenceDiagram
    actor User
    participant FE as Frontend
    participant GW as API Gateway
    participant Auth as Auth Service
    participant API as Order API
    participant DB as PostgreSQL
    participant Cache as Redis

    User->>FE: Click "Place Order"
    FE->>GW: POST /orders (+ JWT)
    GW->>Auth: Validate JWT
    Auth-->>GW: 200 OK {userId}
    GW->>API: POST /orders {userId, items}
    API->>Cache: GET cart:{userId}
    Cache-->>API: cart items
    API->>DB: INSERT order
    DB-->>API: order_id
    API-->>GW: 201 {order_id}
    GW-->>FE: 201 {order_id}
    FE-->>User: Order confirmed

This pairs with the structural diagram above. One shows the system layout; the other shows a critical path through it. Together they answer both "what exists?" and "how does it work?"

Database Architecture with ER Diagrams

For data architecture, the erDiagram type is purpose-built. It's not just schema documentation — it communicates architectural decisions about data ownership and relationships:

erDiagram
    TENANT ||--o{ USER : "has many"
    TENANT ||--o{ PROJECT : "owns"
    USER ||--o{ PROJECT_MEMBER : "joins via"
    PROJECT ||--o{ PROJECT_MEMBER : "has"
    PROJECT ||--o{ TASK : "contains"
    USER ||--o{ TASK : "assigned to"
    TASK ||--o{ COMMENT : "has"
    USER ||--o{ COMMENT : "authors"

    TENANT {
        uuid id PK
        string name
        string plan
        timestamp created_at
    }
    PROJECT {
        uuid id PK
        uuid tenant_id FK
        string name
        string status
    }
    TASK {
        uuid id PK
        uuid project_id FK
        uuid assignee_id FK
        string title
        string priority
        timestamp due_at
    }

This communicates the multi-tenant data model and ownership hierarchy far more clearly than a list of CREATE TABLE statements.

Combining Diagram Types in Architecture Docs

The best architecture documentation uses multiple Mermaid diagram types together. A clean structure:

1. System context (flowchart) — Who uses the system? What external services does it depend on?

2. Container diagram (flowchart with subgraphs) — What are the major deployable components?

3. Key flows (sequenceDiagram) — How do the most critical paths work at runtime?

4. Data model (erDiagram) — What are the core entities and relationships?

5. Infrastructure (block-beta) — Where does everything run?

This roughly follows the C4 model structure, which Mermaid also supports directly via its C4 diagram type.

Styling Architecture Diagrams

Color-code by concern to make layers immediately readable:

flowchart LR
    classDef frontend fill:#3b82f6,stroke:#1d4ed8,color:#fff
    classDef backend fill:#10b981,stroke:#047857,color:#fff
    classDef database fill:#8b5cf6,stroke:#6d28d9,color:#fff
    classDef external fill:#f59e0b,stroke:#b45309,color:#fff

    Web["Web App"]:::frontend
    Mobile["Mobile"]:::frontend
    API["API Server"]:::backend
    Worker["Background Worker"]:::backend
    PG[("PostgreSQL")]:::database
    Redis[("Redis")]:::database
    Stripe["Stripe API"]:::external
    SendGrid["SendGrid"]:::external

    Web & Mobile --> API
    API --> PG & Redis
    API --> Stripe
    Worker --> PG
    Worker --> SendGrid

Blue for frontend, green for backend, purple for databases, amber for external services — your whole team immediately knows which color means what.

Architecture Diagram Anti-Patterns to Avoid

1. God diagrams — One massive diagram with 40 nodes and 80 arrows. Nobody reads these. Split by concern: one for services, one for data, one for infra.

2. Stale topology — A diagram that shows how the system *used* to look. Add a date or version to your diagram title: title System Architecture (2026-Q2). When it drifts, it's obvious.

3. Missing boundaries — Flat node lists without subgraphs make it impossible to see ownership or deployment boundaries. Always group by domain or layer.

4. Ignoring the unhappy path — Architecture diagrams often show only the sunny path. Add failure states and fallback paths — especially for external dependencies.

5. Over-engineering the diagram — Mermaid can express a lot, but a 5-node diagram that your team actually updates beats a 50-node masterwork nobody understands.

Where to Store Your Architecture Diagrams

• /docs/architecture.md — primary home, linked from README
• ADRs (Architecture Decision Records) — each decision gets a diagram showing before/after
• Pull requests — add a diagram when introducing a new service or changing a data flow
• Runbooks — sequence diagrams for incident response flows
• Onboarding docs — the first thing a new engineer should read

Try It Live

All the examples in this guide are ready to paste into mermaideditor.lol. The live preview updates as you type, so you can tweak layouts, add services, and experiment with styles before committing to your repo.

Start with the system architecture flowchart, adapt the service names to your stack, and you'll have a working architecture diagram in under five minutes — no Lucidchart account required.

---

*Related: Mermaid C4 Architecture Diagrams · Mermaid ER Diagram Guide · Mermaid Block Diagram Tutorial*