Mermaid Swimlane Diagram: Build Process Lanes with Subgraphs

# Mermaid Swimlane Diagram: Build Process Lanes with Subgraphs

A swimlane diagram shows who owns each step in a process. Product teams use swimlanes for handoffs, support teams use them for escalation paths, and engineers use them to document how requests move across services.

Mermaid does not have a separate "swimlane" diagram type, but you can build clear swimlane-style diagrams with flowcharts, subgraphs, and a little styling. The result is still plain text, so the diagram can live in Markdown, pull requests, docs sites, and runbooks.

Basic Mermaid Swimlane Pattern

Use one subgraph per lane. Each lane can represent a person, team, service, or system boundary:

flowchart LR
    subgraph Customer["Customer"]
        A["Submit request"]
        E["Receive update"]
    end

    subgraph Support["Support Team"]
        B["Triage ticket"]
        C{"Known issue?"}
        D["Send workaround"]
    end

    subgraph Engineering["Engineering"]
        F["Investigate bug"]
        G["Ship fix"]
    end

    A --> B
    B --> C
    C -->|Yes| D --> E
    C -->|No| F --> G --> E

This reads like a swimlane diagram because each group owns a visible section of the process. The arrows show handoffs between lanes.

When to Use Mermaid Swimlanes

Swimlane-style flowcharts are useful when the main question is ownership. Use them for:

- customer support escalation flows

- approval processes

- incident response roles

- onboarding workflows

- API request paths across services

- product, legal, finance, and engineering handoffs

If the process is mostly about time, use a sequence diagram. If it is mostly about tasks and decisions, a swimlane flowchart is often easier to scan.

Approval Workflow Example

Here is a practical approval flow with three business lanes:

flowchart LR
    subgraph Requester["Requester"]
        Start(["Create purchase request"])
        Revise["Revise request"]
    end

    subgraph Manager["Manager"]
        Review{"Approve request?"}
    end

    subgraph Finance["Finance"]
        Budget{"Budget available?"}
        PO["Create purchase order"]
        Reject["Reject with reason"]
    end

    Start --> Review
    Review -->|Needs changes| Revise --> Review
    Review -->|Approved| Budget
    Budget -->|Yes| PO
    Budget -->|No| Reject

The lane names make responsibilities obvious. Readers can see that the manager approves the request, but finance owns the budget decision and purchase order.

API Swimlane Diagram

Swimlanes are also helpful for developer documentation when a request crosses frontend, backend, and third-party systems:

flowchart LR
    subgraph Browser["Web App"]
        Click["User clicks checkout"]
        Result["Show confirmation"]
    end

    subgraph API["Backend API"]
        Validate["Validate cart"]
        CreateOrder["Create pending order"]
        Confirm["Confirm payment"]
    end

    subgraph Payments["Payment Provider"]
        Charge["Authorize card"]
        Webhook["Send webhook"]
    end

    Click --> Validate --> CreateOrder --> Charge
    Charge -->|Authorized| Result
    Charge --> Webhook --> Confirm

This style works well in API docs because it keeps implementation detail close to the service that owns it.

Styling Lanes and Outcomes

Use light fills for subgraphs and stronger colors for important outcomes:

flowchart LR
    subgraph Ops["Operations"]
        Alert["Alert fires"]
        Triage{"Customer impact?"}
    end

    subgraph Eng["Engineering"]
        Debug["Debug service"]
        Fix["Deploy fix"]
    end

    subgraph Comms["Communications"]
        Status["Post status update"]
        Close["Close incident"]
    end

    Alert --> Triage
    Triage -->|Yes| Status --> Debug --> Fix --> Close
    Triage -->|No| Debug --> Fix --> Close

    style Ops fill:#eff6ff,stroke:#2563eb,stroke-width:2px
    style Eng fill:#ecfdf5,stroke:#16a34a,stroke-width:2px
    style Comms fill:#fff7ed,stroke:#ea580c,stroke-width:2px
    classDef done fill:#dcfce7,stroke:#16a34a,color:#14532d
    class Close done

Keep lane styling subtle. Heavy colors can make the arrows and labels harder to read.

Swimlane Best Practices

- Use one subgraph per owner, team, or system.

- Keep node labels short and action-oriented.

- Prefer flowchart LR when the process moves from left to right.

- Use flowchart TD for long troubleshooting or approval trees.

- Label decision branches with clear outcomes such as Yes, No, Approved, or Rejected.

- Split very large processes into multiple diagrams instead of forcing every lane into one image.

- Preview the diagram before publishing, especially when mixing subgraphs and cross-lane arrows.

Quick Template

Copy this starter template into your docs and replace the lane names:

flowchart LR
    subgraph LaneA["Team A"]
        A1["Start"]
        A2["Review"]
    end

    subgraph LaneB["Team B"]
        B1{"Decision?"}
        B2["Complete task"]
    end

    A1 --> A2 --> B1
    B1 -->|Approved| B2
    B1 -->|Changes needed| A2

Paste it into MermaidEditor.lol, adjust the lanes, and export SVG or PNG when you need a shareable image.

Final Recommendation

Use Mermaid swimlane diagrams when your documentation needs to explain both what happens and who owns each step. Subgraphs give you the lane structure, flowchart arrows show the handoffs, and the source stays easy to review alongside the rest of your docs.