Mermaid Flowchart Examples: 10+ Real-World Patterns

Why Flowcharts Matter in Software

Flowcharts are the most intuitive way to communicate processes to both technical and non-technical stakeholders. A well-crafted flowchart can replace paragraphs of written explanation, making it instantly clear how a system works, where decisions are made, and what happens in edge cases. In software engineering, flowcharts are used to document deployment pipelines, explain authentication mechanisms, map error handling strategies, and describe state transitions.

Each example below is a complete, valid Mermaid diagram that you can paste directly into our Mermaid Diagram Renderer to see it rendered. Every pattern comes from real-world software systems and has been chosen because it solves a problem you are likely to encounter.

1. CI/CD Pipeline

This pattern shows a typical continuous integration and deployment pipeline. It captures the build, test, and deploy stages with conditional gates that prevent broken code from reaching production.

flowchart TD
    A[Push to Main] --> B[Run Linter]
    B --> C[Run Unit Tests]
    C --> D{All Tests Pass?}
    D -->|Yes| E[Build Docker Image]
    D -->|No| F[Notify Developer]
    F --> G[Fix & Re-push]
    G --> A
    E --> H[Push to Registry]
    H --> I[Deploy to Staging]
    I --> J[Run E2E Tests]
    J --> K{E2E Pass?}
    K -->|Yes| L[Deploy to Production]
    K -->|No| F
    L --> M[Health Check]
    M --> N{Healthy?}
    N -->|Yes| O[Done]
    N -->|No| P[Rollback]
    P --> F

When to use: README files for open-source projects, onboarding documentation for new team members, or ADRs (Architecture Decision Records) that describe your deployment strategy.

2. Authentication Flow

This diagram documents a login flow with multi-factor authentication. It shows the happy path alongside the failure paths, which is critical for security-sensitive processes.

flowchart TD
    A[User Visits Login] --> B[Enter Credentials]
    B --> C{Valid Credentials?}
    C -->|No| D[Show Error]
    D --> E{Attempts < 5?}
    E -->|Yes| B
    E -->|No| F[Lock Account 15 min]
    C -->|Yes| G{MFA Enabled?}
    G -->|No| H[Create Session]
    G -->|Yes| I[Send OTP]
    I --> J[Enter OTP]
    J --> K{Valid OTP?}
    K -->|Yes| H
    K -->|No| L{Retries Left?}
    L -->|Yes| J
    L -->|No| D
    H --> M[Redirect to Dashboard]

When to use: Security documentation, product requirement documents, and as a visual companion to authentication middleware code reviews.

3. Error Handling Strategy

Error handling is often described in prose but is much clearer as a flowchart. This pattern shows a retry-with-backoff strategy commonly used in distributed systems.

flowchart TD
    A[API Request] --> B{Response Status}
    B -->|2xx| C[Return Success]
    B -->|4xx| D{Retryable?}
    D -->|No: 400,403,404| E[Return Error to Caller]
    D -->|Yes: 429| F[Wait for Retry-After]
    F --> A
    B -->|5xx| G{Attempt Count}
    G -->|< Max Retries| H[Exponential Backoff]
    H --> I[Wait 2^n seconds]
    I --> A
    G -->|>= Max Retries| J[Log to Sentry]
    J --> K[Return Fallback / Cached]
    B -->|Timeout| L[Cancel Request]
    L --> G

When to use: API client library documentation, internal runbooks for on-call engineers, and design documents for resilience patterns.

4. Pull Request Workflow

This flowchart documents the lifecycle of a pull request from creation to merge. It is valuable for team onboarding and engineering handbook pages.

flowchart TD
    A[Create Branch] --> B[Write Code]
    B --> C[Open PR]
    C --> D[Automated Checks]
    D --> E{CI Green?}
    E -->|No| B
    E -->|Yes| F[Request Review]
    F --> G{Approved?}
    G -->|Changes Requested| B
    G -->|Approved| H{Merge Conflicts?}
    H -->|Yes| I[Rebase / Resolve]
    I --> D
    H -->|No| J[Squash & Merge]
    J --> K[Delete Branch]
    K --> L[Auto-deploy to Staging]

5. Order Processing State Machine

E-commerce order processing involves multiple states and transitions. This flowchart maps the complete lifecycle of an order, including cancellation and refund paths.

flowchart TD
    A([Order Placed]) --> B[Payment Processing]
    B --> C{Payment Success?}
    C -->|No| D[Notify Customer]
    D --> E{Retry Payment?}
    E -->|Yes| B
    E -->|No| F([Order Cancelled])
    C -->|Yes| G[Reserve Inventory]
    G --> H{In Stock?}
    H -->|No| I[Backorder]
    I --> J[Notify ETA]
    H -->|Yes| K[Pick & Pack]
    K --> L[Ship]
    L --> M[Send Tracking]
    M --> N{Delivered?}
    N -->|Yes| O([Order Complete])
    N -->|No: Lost| P[File Claim]
    P --> Q[Reship or Refund]

6. Incident Response

On-call engineers benefit from having incident response procedures documented as flowcharts. When an alert fires at 3 AM, the last thing you want is to parse through a long runbook document.

flowchart TD
    A[Alert Fires] --> B{Severity}
    B -->|P1: Critical| C[Page On-Call]
    B -->|P2: Major| D[Slack Notification]
    B -->|P3: Minor| E[Queue for Next Sprint]
    C --> F[Acknowledge in 5 min]
    F --> G[Open Incident Channel]
    G --> H[Assess Impact]
    H --> I{Customer-Facing?}
    I -->|Yes| J[Post Status Page Update]
    I -->|No| K[Internal Communication]
    J --> L[Investigate Root Cause]
    K --> L
    L --> M{Fix Identified?}
    M -->|Yes| N[Apply Fix]
    N --> O[Verify Resolution]
    O --> P[Write Postmortem]
    M -->|No| Q[Escalate]
    Q --> L

7. Feature Flag Decision Tree

Feature flags add complexity to request handling. This diagram makes the evaluation logic explicit.

flowchart TD
    A[Incoming Request] --> B{Feature Flag: new_checkout}
    B -->|Enabled| C{User in Beta?}
    C -->|Yes| D[Render New Checkout]
    C -->|No| E{Percentage Rollout}
    E -->|In Rollout %| D
    E -->|Not in %| F[Render Legacy Checkout]
    B -->|Disabled| F
    D --> G[Log Metrics: variant=new]
    F --> H[Log Metrics: variant=legacy]

8. Database Migration Strategy

Zero-downtime database migrations require careful sequencing. This flowchart captures the expand-contract migration pattern.

flowchart TD
    A[Plan Migration] --> B[Add New Column]
    B --> C[Deploy Dual-Write Code]
    C --> D[Backfill Existing Data]
    D --> E{Backfill Complete?}
    E -->|No| F[Run Batch Job]
    F --> D
    E -->|Yes| G[Verify Data Consistency]
    G --> H{Data Matches?}
    H -->|No| I[Fix Discrepancies]
    I --> G
    H -->|Yes| J[Switch Reads to New Column]
    J --> K[Monitor for Issues]
    K --> L{Stable for 48h?}
    L -->|No| M[Rollback Reads]
    M --> K
    L -->|Yes| N[Remove Old Column]
    N --> O[Clean Up Dual-Write Code]

9. User Registration Funnel

Product teams use flowcharts to visualize conversion funnels and identify drop-off points.

flowchart TD
    A[Landing Page Visit] --> B{Has Account?}
    B -->|Yes| C[Login]
    B -->|No| D[Click Sign Up]
    D --> E[Enter Email]
    E --> F[Verify Email]
    F --> G{Verified?}
    G -->|No: Timeout| H[Resend Email]
    H --> F
    G -->|Yes| I[Complete Profile]
    I --> J[Choose Plan]
    J --> K{Free or Paid?}
    K -->|Free| L[Onboarding Tour]
    K -->|Paid| M[Enter Payment]
    M --> N{Payment OK?}
    N -->|Yes| L
    N -->|No| O[Show Error]
    O --> M
    L --> P[Dashboard]

10. Microservices Request Routing

In a microservices architecture, understanding how requests flow through the system is essential for debugging and optimization.

flowchart LR
    subgraph Edge
        A[CDN] --> B[API Gateway]
    end
    subgraph Services
        B --> C[Auth Service]
        B --> D[User Service]
        B --> E[Order Service]
        E --> F[Payment Service]
        E --> G[Inventory Service]
    end
    subgraph Data
        D --> H[(Users DB)]
        E --> I[(Orders DB)]
        F --> J[Stripe API]
        G --> K[(Inventory DB)]
    end
    subgraph Async
        E -.-> L[Event Bus]
        L -.-> M[Email Service]
        L -.-> N[Analytics]
    end

11. Git Branching Model

Documenting your team's branching strategy prevents confusion about where to create branches and how releases work.

flowchart LR
    A[main] --> B[develop]
    B --> C[feature/login]
    B --> D[feature/dashboard]
    C --> B
    D --> B
    B --> E[release/1.0]
    E --> A
    E --> B
    A --> F[hotfix/security]
    F --> A
    F --> B

Tips for Better Flowcharts

After working with hundreds of Mermaid flowcharts, several best practices emerge that consistently produce clearer, more maintainable diagrams:

• Choose direction intentionally. Use TD (top-down) for sequential processes and LR (left-right) for data flow or architecture diagrams. The direction should match the mental model of the reader.
• Use subgraphs for bounded contexts. Group related nodes into subgraphs to create visual boundaries. This is especially important for microservice architectures and system boundaries.
• Label your edges. An unlabeled arrow is an ambiguous arrow. Always add |label| text to decision branches and important transitions.
• Keep node text short. If a node label requires more than 4-5 words, your diagram might be at the wrong abstraction level. Consider breaking it into sub-diagrams.
• Use diamond shapes for decisions only. The {} diamond shape has a strong semantic meaning (decision point). Using it for non-decision nodes confuses readers.
• Use stadium shapes for terminals. The ([text]) stadium shape is ideal for start and end states, making the diagram boundaries visually clear.

To render any of these diagrams, paste the code block into our Mermaid Diagram Renderer. You can modify the examples, switch between themes, and export the result as SVG or PNG for your documentation.