Flowcharts: Decisions & Processes

🔄 In Lesson 2, you learned nodes, connections, and subgraphs. Now let’s apply those building blocks to the most versatile diagram type: flowcharts. You’ll model decisions, parallel processes, error handling, and real business workflows.

flowchart vs graph

Quick clarification before we start. Mermaid has two keywords:

• graph — The original syntax. Still works.
• flowchart — The newer syntax. Supports nested subgraphs, more shapes, and better rendering.

Use flowchart for all new diagrams. It’s forward-compatible and has features that graph doesn’t.

flowchart TD
    A[Start] --> B[Process]

Modeling Decisions

Decisions are the heart of flowcharts. Use diamond nodes with labeled paths:

flowchart TD
    A[Receive Order] --> B{In Stock?}
    B -->|Yes| C[Ship Order]
    B -->|No| D{Backorder Available?}
    D -->|Yes| E[Place Backorder]
    D -->|No| F[Cancel & Refund]
    E --> G[Notify Customer]
    C --> G
    F --> H[Send Cancellation Email]

Best practice: Label every exit from a decision node. An unlabeled path is ambiguous — the reader shouldn’t have to guess which branch is “yes” and which is “no.”

✅ Quick Check: Your decision node has three possible outcomes (Approve, Reject, Escalate). Can a diamond node have more than two exits? (Yes. A Mermaid decision node can have as many connections as you need. Use -->|Approve|, -->|Reject|, -->|Escalate| to label each path clearly.)

Parallel Flows

Some processes have steps that happen simultaneously. Model this by forking and joining:

flowchart TD
    A[Order Placed] --> B[Charge Payment]
    A --> C[Reserve Inventory]
    A --> D[Send Confirmation Email]
    B --> E{All Complete?}
    C --> E
    D --> E
    E -->|Yes| F[Begin Shipping]

The pattern: one node connects to multiple targets (the fork), and multiple nodes connect to one target (the join). The join point represents “wait for all to complete.”

Nested Subgraphs

Subgraphs can contain other subgraphs. This is perfect for showing system layers:

flowchart LR
    subgraph Cloud
        subgraph Frontend
            A[React App] --> B[API Client]
        end
        subgraph Backend
            C[Express API] --> D[(PostgreSQL)]
            C --> E[(Redis Cache)]
        end
    end
    B --> C
    F[User Browser] --> A

Three levels: the outer “Cloud” boundary, with “Frontend” and “Backend” inside it. The user sits outside the cloud. Each boundary tells the reader something about the architecture.

Error Handling Patterns

Real workflows need error paths. Use a consistent pattern: happy path flows down or right, error paths branch to the side.

flowchart TD
    A[API Request] --> B{Authenticated?}
    B -->|No| C[Return 401]
    B -->|Yes| D[Validate Input]
    D --> E{Valid?}
    E -->|No| F[Return 400]
    E -->|Yes| G[Process Request]
    G --> H{Success?}
    H -->|No| I[Return 500]
    H -->|Yes| J[Return 200]

The pattern: happy path goes straight down (B→D→G→J), error branches go right (C, F, I). This visual convention makes flowcharts scannable — the reader follows the main line and checks branches when needed.

Real-World Example: CI/CD Pipeline

Here’s a flowchart you’d actually put in a project README:

flowchart LR
    A[Push to main] --> B[Run Tests]
    B --> C{Tests Pass?}
    C -->|No| D[Notify Team]
    C -->|Yes| E[Build Docker Image]
    E --> F[Push to Registry]
    F --> G{Staging?}
    G -->|Yes| H[Deploy to Staging]
    G -->|No| I[Deploy to Production]
    H --> J[Run Smoke Tests]
    J --> K{Pass?}
    K -->|Yes| I
    K -->|No| L[Rollback]

This CI/CD pipeline is readable, version-controllable, and lives right in your repository. When the pipeline changes, update the text and commit alongside the code.

✅ Quick Check: Your teammate reads this CI/CD flowchart and asks: “What happens if staging smoke tests fail?” Trace the path. (Push → Tests → Build → Registry → Staging → Deploy → Smoke Tests → Fail → Rollback. The K -->|No| L[Rollback] path handles the failure.)

Flowchart Best Practices

The most common mistake: cramming too much into one diagram. If your flowchart has more than 15 nodes, ask yourself: “Can this be two diagrams?” Usually, yes.

Additional Shapes

The flowchart keyword unlocks shapes beyond the basics from Lesson 2:

You won’t need these often, but they’re useful when your flowchart needs to follow formal standards (like ISO 5807 for programming flowcharts).

Key Takeaways

• Use flowchart (not graph) for new diagrams — it supports more features
• Label every decision path — unlabeled exits are ambiguous
• Model parallel flows with fork (one → many) and join (many → one) patterns
• Use nested subgraphs to show system boundaries and layers
• Keep happy path in the main direction, error branches to the side
• Limit diagrams to ~15 nodes; split larger processes into multiple diagrams

Up Next

Flowcharts show what happens. In Lesson 4, we’ll learn sequence diagrams — which show who talks to whom and in what order. Perfect for APIs, microservices, and any system where timing and interaction matter.