Mermaid flowchart swimlanes for parallel workflows and concurrent processes

When multiple actors or systems work simultaneously—like a customer placing an order while a payment processor verifies and a warehouse picks inventory—a simple flowchart falls flat. Swimlanes divide your diagram into parallel tracks, one per actor or system, so you can see what happens concurrently and where synchronization points exist. Mermaid flowcharts support swimlanes through subgraphs, letting you model real-world concurrent workflows in code.

Why swimlanes matter for workflow design

Swimlanes are essential when:

• Multiple teams or systems collaborate — each lane shows one actor's responsibilities, preventing "who does what?" confusion in handoff-heavy processes
• You need to show parallel work — instead of sequential steps that hide concurrency, swimlanes reveal what can happen at the same time
• Synchronization points are critical — you can mark wait-states where one actor blocks another, surfacing bottlenecks
• Regulatory or audit trails require clarity — swimlanes make it obvious which actor performed each step

Unlike a simple flowchart, swimlanes enforce accountability and expose dependencies that would stay hidden in a linear view.

Swimlane syntax in Mermaid flowcharts

Mermaid represents swimlanes using subgraphs with a direction prefix:

flowchart TD
    subgraph Customer["🛒 Customer"]
        A["Browse items"]
        B["Add to cart"]
        C["Checkout"]
    end
    
    subgraph PaymentProcessor["💳 Payment Processor"]
        D["Validate card"]
        E["Authorize charge"]
        F["Confirm payment"]
    end
    
    subgraph Warehouse["📦 Warehouse"]
        G["Check inventory"]
        H["Pick items"]
        I["Ship order"]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I

Each subgraph becomes a lane. Edges crossing between lanes show handoffs and synchronization points. The prefix (🛒, 💳, 📦) labels each actor—optional but clarifies the diagram at a glance.

Real-world example: software release process

Here's a release workflow with three parallel tracks: development, QA, and operations:

flowchart TD
    subgraph Dev["👨‍💻 Development"]
        D1["Feature branch ready"]
        D2["Code review"]
        D3["Merge to main"]
        D4["Build artifact"]
    end
    
    subgraph QA["🧪 QA"]
        Q1["Wait for build"]
        Q2["Run test suite"]
        Q3["Execute manual tests"]
        Q4["Report issues"]
    end
    
    subgraph Ops["🚀 Operations"]
        O1["Wait for QA approval"]
        O2["Deploy to staging"]
        O3["Run smoke tests"]
        O4["Deploy to production"]
        O5["Monitor metrics"]
    end
    
    D1 --> D2
    D2 --> D3
    D3 --> D4
    D4 --> Q1
    Q1 --> Q2
    Q2 --> Q3
    Q3 --> Q4
    Q4 -->|Approved| O1
    Q4 -->|Issues found| D1
    O1 --> O2
    O2 --> O3
    O3 --> O4
    O4 --> O5

This diagram shows:

• Dev completes steps in sequence
• QA waits for a build, then runs tests in parallel branches
• Ops waits for QA approval before staging deployment
• A feedback loop returns issues to dev (showing iteration)
• The whole process takes the time of the slowest lane (critical path)

Advanced: cross-lane coordination

For complex workflows, you may need conditional handoffs. Use labeled edges to clarify:

flowchart TD
    subgraph HR["👔 HR Department"]
        H1["Receive application"]
        H2["Initial screening"]
        H3["Send to hiring manager"]
    end
    
    subgraph Manager["👨‍🔬 Hiring Manager"]
        M1["Review application"]
        M2["Schedule interview"]
        M3["Conduct interview"]
        M4["Make decision"]
    end
    
    subgraph Candidate["👤 Candidate"]
        C1["Submit application"]
        C2["Wait for update"]
        C3["Prepare for interview"]
        C4["Interview"]
        C5["Await decision"]
    end
    
    C1 --> H1
    H1 --> H2
    H2 -->|Pass screening| H3
    H2 -->|Reject| C2
    H3 --> M1
    M1 --> M2
    M2 -->|Candidate agrees| C3
    C3 --> C4
    C4 --> M3
    M3 --> M4
    M4 -->|Offer| C5
    M4 -->|No offer| C2

This hiring process shows:

• HR screens; Manager reviews
• Conditional paths: screening pass/fail, interview agreement, offer/rejection
• All three lanes need to align for progress (swimlanes expose where the process stalls)

Swimlanes vs. subgraphs: when to use which

In Mermaid, swimlanes are implemented as subgraphs, but the term "swimlane" implies horizontal or vertical lanes representing actors/roles. Use swimlanes when:

• You're modeling a cross-functional workflow (multiple teams, departments, or systems)
• Parallel work is explicit — the diagram should show what can happen at the same time
• You want to assign responsibility — each lane is a role

Use regular subgraphs (without swimlane semantics) when:

• You're grouping related steps within a single workflow (e.g., "error handling," "setup phase")
• The subgraph represents a logical block, not a separate actor
• You want to hide/show detail without changing responsibility

For example, a build pipeline inside a single CI/CD lane uses a subgraph for "build steps"; a multi-team process uses swimlanes for "Dev," "QA," "Ops."

Best practices for readable swimlanes

1. Limit to 3–4 lanes — more than four parallel tracks becomes cluttered; split into multiple diagrams
2. Keep lane height proportional — if one lane is much longer, it's your critical path; consider optimizing it
3. Use consistent shapes — all decision points should be diamonds; all steps should be rectangles
4. Label handoffs clearly — when a lane's output triggers another lane's input, use arrows and labels
5. Avoid criss-crossing edges — reorder lanes to minimize visual clutter
6. Test your story — read the diagram left-to-right and top-to-bottom; does the flow feel natural?

Swimlane challenges and solutions

Challenge	Solution
Diagram becomes wide and hard to render	Rotate to vertical flow (flowchart LR) or split into two diagrams
Too many handoffs between lanes	Refactor process to reduce cross-functional dependencies
Difficult to show start times	Add a "Time" column as a reference lane, or use a Gantt chart for scheduling
Need to show swimlanes in a sequence diagram	Use Mermaid's autonumber and participant instead—sequence diagrams handle parallel better

When to switch to a different diagram type

• Swimlanes are getting too complex? Use a Gantt chart to show timing and dependencies.
• Need to show request/response between systems? Sequence diagrams explicitly model interactions.
• Want to show state transitions per actor? Use multiple state diagrams, one per actor.

FAQ

Can swimlanes show time?
Swimlanes show order but not duration. For timelines, use a Gantt chart. Swimlanes in flowcharts are best for logical sequences, not temporal schedules.

How many lanes should a swimlane diagram have?
Aim for 2–4 lanes. Beyond that, the diagram becomes hard to read on a single screen. Split into two diagrams or use a different visualization (e.g., dependency graph or Gantt).

Can I nest swimlanes?
Mermaid doesn't support nested subgraphs directly. If you need hierarchical swimlanes, use separate diagrams—one at the "company" level, another at the "team" level.

Are swimlanes the same as BPMN lanes?
Conceptually, yes—both model actors or roles in a process. Mermaid's implementation is simpler than BPMN, so complex enterprise processes may outgrow Mermaid. For simple workflows, Mermaid swimlanes are perfect.

Design your next parallel workflow with swimlanes in the MermaidCreator editor. Swimlanes expose handoffs and bottlenecks, turning hidden dependencies into actionable insights.