Flowchart vs sequence diagram: when to use each in Mermaid

Teams often reach for flowcharts and sequence diagrams to solve the same problem: "How does this process work?" But they answer different questions. A flowchart shows what decisions lead where. A sequence diagram shows who talks to whom and in what order. Choosing the wrong one wastes time; choosing the right one clarifies thinking in minutes.

What flowcharts show

Flowcharts answer: What happens next? They trace a single path (or multiple paths via branches) through logic, decisions, and steps.

A flowchart has:

• Start and end nodes (ovals)
• Decision nodes (diamonds) that branch based on conditions
• Process nodes (rectangles) for actions
• Arrows showing the direction of flow

Use flowcharts for:

• Business process flows (order fulfillment, approval workflows)
• Algorithm logic (how a system decides between branches)
• Decision trees (troubleshooting guides)
• State machines with conditional transitions
• User journeys with choices

Example: checkout process

flowchart TD
    A([Customer clicks checkout])
    B{Logged in?}
    C["Login page"]
    D["Cart review"]
    E{Items in stock?}
    F["Show warning"]
    G["Proceed to payment"]
    H{Payment approved?}
    I["Order confirmed"]
    J["Retry payment"]
    K([End])

    A --> B
    B -->|No| C --> D
    B -->|Yes| D
    D --> E
    E -->|No| F --> D
    E -->|Yes| G
    G --> H
    H -->|No| J --> G
    H -->|Yes| I --> K

The diagram shows every decision point and what leads to it. Readers can follow the happy path and spot alternate routes without reading prose.

What sequence diagrams show

Sequence diagrams answer: In what order do these actors interact? They're timelines of messages between participants, showing causality and dependencies.

A sequence diagram has:

• Participants (client, server, database, etc.) shown as columns
• Messages (arrows) flowing left/right, representing calls or responses
• Time flowing downward, so earlier messages are higher
• Blocks (alt, loop, par) for conditional or repeated interactions

Use sequence diagrams for:

• API request/response flows
• Multi-service interactions
• Authentication and authorization protocols
• Integration between systems
• Debugging traces (what actually happened)
• Database transaction flows

Example: same checkout, but from an API perspective

sequenceDiagram
    participant Frontend
    participant OrderAPI
    participant PaymentService
    participant Inventory

    Frontend->>OrderAPI: POST /checkout { cart, payment }
    OrderAPI->>Inventory: Check stock
    Inventory-->>OrderAPI: In stock ✓
    OrderAPI->>PaymentService: Charge card
    PaymentService-->>OrderAPI: 200 OK
    OrderAPI->>Inventory: Decrement stock
    Inventory-->>OrderAPI: Stock updated
    OrderAPI-->>Frontend: 201 Order created

The diagram shows when each service is involved and what messages flow. Readers understand the system boundaries and latency points without reading code.

Side-by-side comparison

Aspect	Flowchart	Sequence Diagram
Shows	Logic branches, decisions, flow	Interactions, timing, causality
Time axis	Implicit (top to bottom)	Explicit (vertical = time)
Best for	Business logic, algorithms	Distributed systems, APIs
Participants	Single or multiple implicit actors	Explicit, named participants
Branches	Conditional nodes (diamonds)	alt / else blocks
Loops	Loop nodes	loop blocks
Focus	What happens next?	Who talks to whom?

The litmus test

Ask yourself:

1. "Does my diagram care about which systems are involved?"

   • Yes → sequence diagram (e.g., "the client calls the server, the server queries the database")
   • No → flowchart (e.g., "if approved, proceed; if denied, retry")

2. "Is time or causality the main point?"

   • Yes → sequence diagram (e.g., "B happens after A finishes")
   • No → flowchart (e.g., "if condition X, go to Y")

3. "Do I need to show waiting or asynchronous operations?"

   • Yes → sequence diagram (e.g., "the client waits for the response")
   • No → flowchart (e.g., "a scheduled job runs every hour")

4. "Is this for a technical audience (engineers, architects) or business stakeholders?"

   • Technical (systems, APIs, transactions) → sequence diagram
   • Business (approval chains, workflows) → flowchart

When to use both

The best documentation uses both:

1. Flowchart for the high-level decision logic — what choices get made and why
2. Sequence diagrams for how the system implements those choices — which services are called and in what order

Example: payment approval workflow

Flowchart shows the business decision:

flowchart TD
    A{Over $5000?}
    B{Risk score high?}
    C["Auto-approve"]
    D["Manual review"]
    A -->|No| C
    A -->|Yes| B
    B -->|No| C
    B -->|Yes| D

Sequence diagram shows how the system executes that decision:

sequenceDiagram
    participant API
    participant RiskEngine
    participant ApprovalQueue
    participant Slack

    API->>RiskEngine: Analyze { amount, user }
    RiskEngine-->>API: { riskScore }
    alt riskScore < threshold
        API->>API: Approve
    else
        API->>ApprovalQueue: Enqueue
        ApprovalQueue->>Slack: Notify team
    end

Flowchart tells the why; sequence tells the how.

Hybrid diagram: using subgraphs

For complex scenarios, nest a flowchart inside a sequence diagram (or vice versa) using Mermaid subgraphs:

sequenceDiagram
    participant Client
    participant Auth
    participant API

    Client->>Auth: Login attempt
    Note over Auth: Flow: check credentials
    alt Valid
        Auth-->>Client: Token
        Client->>API: Request (token)
        API-->>Client: 200 OK
    else Invalid
        Auth-->>Client: 401 Unauthorized
    end

The alt block captures decision logic inline. This works when the decisions are simple; for complex trees, a separate flowchart is clearer.

Real-world examples

Use flowchart for:

• Troubleshooting guides ("Is the error a timeout? Yes → check logs; No → check config")
• DevOps pipelines (build → test → deploy, with optional steps)
• Feature flags (if flag X, enable feature Y)
• Approval workflows (manager approval → budget approval → procurement)

Use sequence diagram for:

• OAuth login flow (client → auth provider → client)
• Microservices payment processing (frontend → order service → payment service → database)
• Database transactions (app → ORM → database → indices)
• Event-driven workflows (user clicks → event published → multiple subscribers react)

FAQ

Can I combine flowchart and sequence diagrams in one file?
Not natively in Mermaid—each diagram is independent. But on MermaidCreator or in documentation, you can place them side by side and reference one from the other using internal links (/blog/<slug>).

Should I always show both?
No. A simple REST API endpoint might only need a sequence diagram. A business process might only need a flowchart. Use both when they answer different questions about the same system.

My team keeps asking for flowcharts when they need sequences. How do I explain the difference?
Show them the same process in both formats. The flowchart tells them what decision to make; the sequence shows them how the system executes it. Both are true; both are useful; they're just answering different questions.

Start in the MermaidCreator editor—sketch the same scenario as both a flowchart and a sequence diagram to feel the difference in your hands.