Statechart vs flowchart: when to use each in Mermaid

Mermaid's stateDiagram and flowchart both show transitions between nodes, so when do you use each? The difference is subtle but important: a flowchart describes a process (what happens when), while a statechart describes a system's state (what is possible from here). Mixing them up leads to confusing diagrams that don't reflect reality.

The core difference

Flowchart: "Here's the sequence of steps to accomplish a goal."

• Used for: workflows, procedures, algorithms
• Directionality: time-based (step A, then B, then C)
• Re-entry: steps don't repeat; you move forward
• Example: order checkout flow, account signup

Statechart: "Here are the states the system can be in, and what triggers transitions."

• Used for: system behavior, state machines, protocols
• Directionality: event-based (when X happens, go to state Y)
• Re-entry: you can return to previous states
• Example: payment status, user authentication, game state

When to use flowchart

Use flowchart when you're describing a linear or branching process — a sequence of decisions and actions that move you toward a goal.

flowchart TD
    A[User lands on site] --> B{Logged in?}
    B -->|No| C[Show login form]
    C --> D[User submits credentials]
    D --> E{Valid?}
    E -->|No| C
    E -->|Yes| F[Load dashboard]
    B -->|Yes| F

This reads as: "First, check if logged in. If not, show login. Validate. Then load dashboard."

Red flags for flowchart:

• You have cycles that loop back (login retries, process restarts)
• The same decision point appears multiple times
• You're describing "what the user does" or "what the system executes"

Flowcharts are action-oriented.

When to use statechart

Use stateDiagram when you're describing a system's possible states and the events that trigger transitions. The focus is on state identity, not on sequence.

stateDiagram-v2
    [*] --> Idle
    Idle --> Connecting: User clicks "connect"
    Connecting --> Connected: Connection established
    Connected --> Disconnecting: User clicks "disconnect"
    Disconnecting --> Idle: Connection closed
    Connecting --> Error: Connection failed
    Error --> Idle: User retries

This reads as: "The system can be in these states. From each state, here's what can happen."

Red flags for statechart:

• You care about what state the system is in at any point in time
• Events can happen in any order (user clicks buttons in different sequences)
• You need to handle the same state being reached from different paths
• You're modeling a protocol, game, or interaction pattern

Statecharts are state-oriented.

Side-by-side comparison

Consider a payment flow. Here's the flowchart approach (sequence of steps):

flowchart TD
    A[User clicks Pay] --> B[Show payment form]
    B --> C[User enters card]
    C --> D[Submit to Stripe]
    D --> E{Success?}
    E -->|No| F[Show error]
    F --> B
    E -->|Yes| G[Save transaction]
    G --> H[Show confirmation]

Here's the statechart approach (state identity + transitions):

stateDiagram-v2
    [*] --> Idle
    Idle --> PaymentForm: User initiates checkout
    PaymentForm --> Processing: User submits card
    Processing --> Success: Payment authorized
    Processing --> Failed: Declined or timeout
    Failed --> PaymentForm: User retries
    Success --> [*]

Notice the difference:

• Flowchart: Step B (show form) is a step in the process.
• Statechart: PaymentForm is a state the system occupies.

From the PaymentForm state, different events can occur (user submits, user cancels). From step B in the flowchart, you must proceed to step C.

How to choose

Ask yourself:

1. Are you describing a process (how to do something) or a system (what states it can be in)?

   • Process → flowchart
   • System state → statechart

2. Can you return to an earlier point without restarting?

   • Yes (retry, loop, revisit) → consider statechart
   • No (one-way process) → flowchart

3. Do external events matter, or just the sequence?

   • External events (user clicks, timer fires, message arrives) → statechart
   • Sequence of steps → flowchart

4. Will this be code?

   • State machines often become code (switch statements, event handlers) → statechart
   • Procedures often become prose or checklists → flowchart

Common mistakes

Mistake 1: Modeling retry as a flowchart cycle

❌ Wrong (flowchart with cycle):

flowchart TD
    A[Validate] --> B{Valid?}
    B -->|No| A
    B -->|Yes| C[Save]

This suggests you return to validation, but it's unclear what changed. Better as a state machine:

✅ Better (statechart):

stateDiagram-v2
    [*] --> Validating
    Validating --> Valid: Data OK
    Validating --> Invalid: Errors found
    Invalid --> Validating: User corrects
    Valid --> [*]

Mistake 2: Modeling parallel states as flowchart branches

❌ Wrong (flowchart):

flowchart TD
    A[Start] --> B{Path?}
    B -->|Frontend| C[Render]
    B -->|Backend| D[Process]
    C --> E[Done]
    D --> E

If frontend and backend happen together, this isn't a flowchart. Use a statechart with compound states or a sequence diagram.

Mistake 3: Confusion between decision and state

Flowcharts have decision nodes ({...}). Statecharts don't — instead, they have states and transitions labeled with events.

Flowchart: "If the user is logged in, do X." Statechart: "The system is in the LoggedIn state. When the user clicks logout, transition to LoggedOut."

When to use both

Large systems often need both:

• Statechart for the high-level machine (order: pending → processing → shipped)
• Flowchart for the details within each state (what happens during processing?)

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: Payment confirmed
    Processing --> Shipped: Items dispatched
    Shipped --> Delivered: Carrier scanned
    
    note right of Processing
        See "Order Processing Workflow" flowchart
        for details on inventory + invoice steps
    end note

Then in a separate diagram:

flowchart TD
    A[Order in Processing state] --> B[Check inventory]
    B --> C{In stock?}
    C -->|No| D[Backorder / notify customer]
    C -->|Yes| E[Pick items]
    E --> F[Generate invoice]
    F --> G[Hand to warehouse]

FAQ

Q: Can I use flowchart for everything? A: Technically yes, but statecharts make state-driven behavior clearer. A flowchart with many cycles becomes hard to follow.

Q: Is statechart overkill for a simple one-time process? A: Probably. If it's truly linear (no retries, no loops, no re-entry), flowchart is simpler and more intuitive.

Q: How do I model a process that depends on the current state? A: Use statechart. Each state can have entry/exit behavior or allowed transitions. That's the point of state machines.

Q: Can I convert a flowchart to a statechart? A: Often yes. Map flowchart steps to states, and decision branches to transitions. But if the flowchart is purely sequential, a statechart adds unnecessary complexity.

Q: Which one should I use in requirements? A: Both. Use statechart for "the feature can be in state X or Y" (what's allowed). Use flowchart for "here's what the user does" (the happy path or a procedure).

Choosing for your next diagram

Next time you sketch a system:

1. Ask: "What states can this be in?" Write them down. If you have a clear list (Pending, Processing, Done), statechart is a fit.
2. **Ask: "What sequence of steps?" ** If you have a linear process (upload → validate → process → export), flowchart is simpler.
3. Build in MermaidCreator and see which feels natural.

Ready to diagram your next system? Start with a state diagram if you're modeling behavior, or a flowchart if you're explaining a process.