Mermaid Flowchart Examples for Docs, Workflows, and System Design

# Mermaid Flowchart Examples for Docs, Workflows, and System Design

Mermaid flowcharts are the fastest way to turn a process, decision, system path, or runbook into a diagram that stays close to the code. You write plain text, commit it with the docs, and avoid the usual screenshot drift that happens with drag-and-drop diagram tools.

This guide gives you practical Mermaid flowchart examples you can copy into a README, product spec, architecture decision record, support playbook, or engineering wiki.

Basic Process Flowchart

Use this pattern when you need to explain a linear workflow with one or two important branches.

flowchart TD
    A[Receive request] --> B[Validate input]
    B --> C{Valid?}
    C -->|Yes| D[Process request]
    C -->|No| E[Return validation error]
    D --> F[Send response]

Keep node labels short. A flowchart should make the path obvious before the reader studies every detail.

Product Signup Flow

Product teams can use Mermaid to document activation paths, onboarding gates, and where users drop off.

flowchart LR
    Visitor[Landing page visitor] --> CTA[Click sign up]
    CTA --> Form[Create account]
    Form --> Verify[Verify email]
    Verify --> Workspace[Create workspace]
    Workspace --> Invite[Invite teammate]
    Workspace --> FirstDiagram[Create first diagram]
    FirstDiagram --> Activated[Activated user]

This type of diagram is useful in growth experiments because it separates the desired user journey from analytics implementation details.

API Request Flowchart

For backend documentation, show the route from client request to auth, business logic, data access, and response.

flowchart TD
    Client[Client app] --> Gateway[API gateway]
    Gateway --> Auth{Token valid?}
    Auth -->|No| Unauthorized[401 response]
    Auth -->|Yes| Handler[Route handler]
    Handler --> Cache{Cache hit?}
    Cache -->|Yes| Cached[Return cached response]
    Cache -->|No| Service[Service layer]
    Service --> DB[(Database)]
    DB --> Service
    Service --> StoreCache[Update cache]
    StoreCache --> Response[200 response]

Label decisions as questions. That makes the yes/no branches easier to scan in code reviews.

Incident Response Runbook

Mermaid flowcharts work well for on-call docs because engineers need fast, unambiguous next steps during an incident.

flowchart TD
    Alert[Pager alert fires] --> Triage[Check dashboard and logs]
    Triage --> CustomerImpact{Customer impact?}
    CustomerImpact -->|No| Ticket[Create follow-up ticket]
    CustomerImpact -->|Yes| Declare[Declare incident]
    Declare --> Mitigate[Apply safest mitigation]
    Mitigate --> Stable{Metrics stable?}
    Stable -->|No| Escalate[Escalate to service owner]
    Stable -->|Yes| Postmortem[Write postmortem]

A good runbook diagram should include escalation, not just the happy path.

System Design Flowchart with Subgraphs

Use subgraphs to group services by boundary, team, network, or responsibility.

flowchart LR
    subgraph Client[Client layer]
        Web[Web app]
        Mobile[Mobile app]
    end

    subgraph Backend[Backend services]
        API[Public API]
        Worker[Background worker]
        Billing[Billing service]
    end

    subgraph Data[Data layer]
        Postgres[(Postgres)]
        Queue[Message queue]
        Warehouse[(Analytics warehouse)]
    end

    Web --> API
    Mobile --> API
    API --> Postgres
    API --> Queue
    Queue --> Worker
    Worker --> Billing
    Worker --> Warehouse

This is often clearer than an architecture diagram that tries to show every host, subnet, and implementation detail at once.

Approval Workflow Flowchart

Decision-heavy business processes are easier to maintain as text than as exported images.

flowchart TD
    Draft[Draft proposal] --> Review[Manager review]
    Review --> Approved{Approved?}
    Approved -->|No| Revise[Revise proposal]
    Revise --> Review
    Approved -->|Yes| Legal{Legal needed?}
    Legal -->|Yes| LegalReview[Legal review]
    Legal -->|No| Send[Send to customer]
    LegalReview --> Send

When a loop exists, show it. Hidden retry paths are where process docs usually become misleading.

Flowchart Styling Example

A small amount of styling can show status or category without making the diagram noisy.

flowchart LR
    Start[Start]:::ok --> Build[Build]:::work
    Build --> Test{Tests pass?}:::decision
    Test -->|Yes| Deploy[Deploy]:::ok
    Test -->|No| Fix[Fix failure]:::bad
    Fix --> Build

    classDef ok fill:#dcfce7,stroke:#16a34a,color:#111827
    classDef work fill:#dbeafe,stroke:#2563eb,color:#111827
    classDef decision fill:#fef3c7,stroke:#d97706,color:#111827
    classDef bad fill:#fee2e2,stroke:#dc2626,color:#111827

Use semantic colors: green for success, yellow for decisions, red for failures, and blue for normal work.

Mermaid Flowchart Checklist

Before publishing a flowchart, check these points:

1. Does the title explain the exact process or system being shown?
2. Are decisions written as questions?
3. Are branch labels explicit enough: yes, no, retry, timeout, approved?
4. Are external systems, databases, queues, and humans visually distinguishable?
5. Is the diagram small enough to understand without zooming?
6. Would someone know what to update when the code or process changes?

Final Recommendation

Start with the simplest flowchart that answers the reader's question. Add subgraphs only when boundaries matter, add styling only when it improves scanning, and keep the Mermaid source next to the documentation it supports.

If you want to experiment quickly, paste any example into MermaidEditor.lol, adjust the labels for your system, and export the finished diagram when the flow is clear.