Organizational flowcharts with swimlanes in Mermaid

Every process crosses organizational boundaries. An order flows from customer → sales → engineering → operations → support. A bug report goes from QA → developers → devops → customers. Without clear ownership, work gets stuck in gaps or duplicated.

Swimlanes in Mermaid flowcharts let you visualize exactly which team or person owns each step. They transform a generic flowchart into a map of roles, responsibilities, and handoffs — perfect for documenting workflows, onboarding new team members, and spotting bottlenecks.

Basic swimlanes: subgraphs in flowcharts

Use subgraph blocks to group steps by team or function:

flowchart LR
    
    subgraph Customer
        A([Submit Order])
    end
    
    subgraph Sales
        B[Validate<br/>& Quote]
        C[Send Invoice]
    end
    
    subgraph Engineering
        D[Design<br/>Solution]
        E[Code]
        F[Test]
    end
    
    subgraph Operations
        G[Deploy]
        H[Monitor]
    end
    
    A --> B --> C --> D --> E --> F --> G --> H

Each subgraph is a lane (a column or row, depending on your flowchart direction). Steps inside a lane belong to that team. The arrows show the flow across teams.

Key pattern:

• Use flowchart LR (left-to-right) for process flows that cross teams horizontally
• Use flowchart TD (top-down) for hierarchical workflows
• Name each subgraph by the team, department, or role that owns it

Left-to-right swimlanes: process handoffs

The horizontal layout is best for workflows that move left-to-right through an organization:

flowchart LR
    
    subgraph Product["Product Team"]
        idea[Define Feature]
        spec[Write Spec]
    end
    
    subgraph Frontend["Frontend Eng"]
        design[Design UI/UX]
        dev[Implement]
        review1[Code Review]
    end
    
    subgraph Backend["Backend Eng"]
        api[Build API]
        db[Design DB]
        review2[Code Review]
    end
    
    subgraph QA["QA Team"]
        test[Test Feature]
        bugs{Bugs Found?}
    end
    
    idea --> spec --> design
    design --> dev --> review1
    spec --> api --> db --> review2
    review1 --> test
    review2 --> test
    test --> bugs
    bugs -->|Yes| dev
    bugs -->|No| release["Release ✓"]

The diagram reads left-to-right: ideas start with Product, split into parallel Frontend and Backend work, converge at QA, and loop back if bugs are found. At a glance, you see which team owns each step and where work happens in parallel vs. sequentially.

Top-down swimlanes: hierarchical organization

Use vertical swimlanes to show org hierarchy and escalation paths:

flowchart TD
    
    subgraph CEO["CEO"]
        goal[Set Strategy]
    end
    
    subgraph Leadership["Leadership Team"]
        vp[Allocate Budget]
        plan[Quarterly Planning]
    end
    
    subgraph Teams["Individual Teams"]
        exec["Execute OKRs"]
    end
    
    subgraph Feedback["Feedback Loop"]
        review[Review Results]
        retro[Retrospective]
    end
    
    goal --> vp --> plan
    vp --> exec
    plan --> exec
    exec --> review --> retro
    retro -.->|Inform Next Quarter| goal

This models information flow from top (strategy) down to execution (teams), then back up (feedback). The dotted line shows the cycle — learnings from retrospectives inform next quarter's strategy.

Real-world examples

Software bug triage

flowchart LR
    
    subgraph User["User / QA"]
        report["🐛 Report Bug"]
    end
    
    subgraph Triage["Triage Team"]
        review["Review Report<br/>Gather Info"]
        valid{Valid?}
    end
    
    subgraph Dev["Dev Team"]
        assign["Assign to Dev"]
        fix["Fix Bug"]
        test["Dev Tests"]
    end
    
    subgraph QA["QA Team"]
        verify["Verify Fix"]
        approved{Pass?}
    end
    
    subgraph Release["Release"]
        merge["Merge to Main"]
        deploy["Deploy"]
    end
    
    report --> review --> valid
    valid -->|No| close["Close Issue"]
    valid -->|Yes| assign --> fix --> test
    test --> verify --> approved
    approved -->|No| fix
    approved -->|Yes| merge --> deploy

Each team's responsibility is clear: users report, triage validates, devs fix, QA verifies, release deploys. Bottlenecks jump out (e.g., if QA is slow, devs and release wait).

Content publishing workflow

flowchart LR
    
    subgraph Author["Author"]
        write["Write Draft"]
        review_self["Self-Review"]
    end
    
    subgraph Editor["Editor"]
        edit["Edit for Clarity<br/>& Style"]
        fact_check["Fact Check"]
        approve1{Approved?}
    end
    
    subgraph Designer["Design Team"]
        graphics["Create Graphics<br/>& Illustrations"]
        layout["Layout & Format"]
    end
    
    subgraph Marketing["Marketing"]
        seo["SEO Review"]
        social["Plan Social Posts"]
        schedule["Schedule Publish"]
    end
    
    write --> review_self --> edit
    edit --> fact_check --> approve1
    approve1 -->|No| edit
    approve1 -->|Yes| graphics --> layout
    layout --> seo --> social --> schedule

The workflow is clearly sequential, with feedback loops back to the editor. Marketing can't finalize social posts until design is done — the diagram shows this dependency.

Customer request resolution

flowchart TD
    
    subgraph Customer["Customer"]
        request["Submit Request"]
    end
    
    subgraph Support["Customer Support"]
        intake["Intake & Categorize"]
        simple{Simple?}
    end
    
    subgraph Specialist["Specialist Team"]
        investigate["Investigate"]
        propose["Propose Solution"]
        followup["Follow Up"]
    end
    
    subgraph Engineering["Engineering"]
        assess["Assess Impact"]
        bugfix["Fix Bug / Build<br/>Feature"]
        release["Deploy Fix"]
    end
    
    request --> intake --> simple
    simple -->|Yes| respond["Respond to<br/>Customer"]
    simple -->|No| investigate --> propose
    propose --> followup
    followup --> bugfix
    bugfix --> release --> respond

This vertical flow shows escalation: simple requests stay with Support, complex ones go to Specialists, then Engineering if a code change is needed. It models real triage paths.

Designing effective swimlanes

1. One swimlane per distinct role or team Don't create a swimlane for "engineering" if backend and frontend have very different workflows. Separate them if they split and recombine.

2. Show decision points at the right level If a decision is made by a specific team (e.g., QA decides "pass or fail"), put the decision diamond in that lane. If it's shared (e.g., "is this high priority?"), consider a shared lane or a central decision point.

3. Highlight handoffs Arrows crossing lane boundaries are handoffs — those are your risk points. If a handoff takes days or causes confusion, redesign the process.

4. Use consistent terminology If the swimlane is "Product", every step should be something Product does: "Prioritize", "Specify", "Backlog". Don't mix verbs across lanes (e.g., "Implement" belongs in Dev, not Product).

5. Color-code by team (optional) In MermaidCreator, you can style each subgraph with a background color:

flowchart LR
    subgraph Support["Customer Support"]
        a[Intake]
    end
    
    style Support fill:#e1f5ff

Consistent colors (green for engineering, blue for support, orange for operations) make the diagram scan faster.

Common patterns

Parallel work:

flowchart TD
    A["Product<br/>Spec"] --> B["Frontend<br/>Design"]
    A --> C["Backend<br/>API Design"]
    B --> D["Code Review"]
    C --> D
    D --> E["Integrate &<br/>Test"]

Frontend and backend work in parallel after the spec, then converge at integration.

Escalation:

flowchart TD
    A["Support"] --> B{Can resolve?}
    B -->|Yes| C["Close"]
    B -->|No| D["Escalate to<br/>Specialist"]
    D --> E{Still stuck?}
    E -->|No| C
    E -->|Yes| F["Escalate to<br/>Engineering"]
    F --> C

Work moves up the ladder only if lower levels can't resolve it.

Feedback loop:

flowchart LR
    A["Dev"] --> B["QA"]
    B --> C{Pass?}
    C -->|Yes| D["Release"]
    C -->|No| E["Report to Dev"]
    E -.->|Fixes| A

Dotted line shows feedback flowing backward without creating a visual tangle.

Using swimlanes for onboarding

New team members often don't know where their work fits in the larger organization. A swimlane diagram answers:

• Who do I hand off to next?
• Who depends on my work?
• What happens if I'm blocked?
• Why does this take longer than I thought?

Post it in your wiki or onboarding docs. Update it whenever a process changes.

FAQ

Can I add swimlanes to other diagram types (sequence, state)? Sequence diagrams use participant blocks, which are like swimlanes. State diagrams don't have swimlanes — use them for organizational flows or multi-team processes, not internal state machines.

What if the process is too complex for one diagram? Split it. Create a high-level diagram that shows major teams and handoffs, then detail sub-diagrams for each team's internal process. Link them: "See Engineering's internal workflow" in the prose.

How do I show work that's optional or conditional? Use decision diamonds ({...}) and label the exits ("Yes", "No", "Urgent", etc.). If the entire swimlane is optional, use a dotted subgraph boundary (though Mermaid doesn't render this directly — describe it in prose).

Can I show dependencies across swimlanes? Yes, arrows can cross lanes. Use thick or colored arrows for critical paths, thin arrows for optional dependencies.

Draw your first organizational flowchart in MermaidCreator — map one workflow from start to finish, assign steps to lanes, then share it with your team to validate roles and handoffs.