A 10-Minute Guide to Mermaid Flowcharts

Flowcharts are the most common Mermaid diagram type because they fit everyday documentation work: user journeys, API request paths, approval flows, error handling, and internal business rules. This guide teaches the Mermaid flowchart syntax you need first, then shows how to turn a small diagram into a useful technical artifact.

You can copy each snippet into the Mermaid Preview editor and watch the diagram render as you edit. Start small, verify the preview, then add labels and branches one piece at a time.

1. Defining the Direction

Every Mermaid flowchart starts with the flowchart keyword followed by a layout direction. TD means top-down, LR means left-to-right, BT means bottom-to-top, and RL means right-to-left. For documentation, TD works well for step-by-step processes, while LR often works better for system pipelines.

flowchart TD
  A --> B

The letters A and B are node identifiers. They do not have to be shown to readers. You can attach readable text by wrapping it in brackets:

flowchart LR
  request[Client request] --> auth[Check authentication]

2. Node Shapes

The shape of a node is determined by the brackets you use around its label. Choose shapes for meaning, not decoration. A simple convention makes diagrams easier to scan across a team.

• [Rectangle] - Standard process step.
• (Rounded Rectangle) - Often used for start/end points.
• {Rhombus} - Used for decisions or conditions.
• ((Circle)) - Used for states or smaller connection nodes.

flowchart TD
  start([Start])
  validate[Validate payload]
  decision{Payload valid?}
  success((Accepted))
  failed((Rejected))
  start --> validate --> decision
  decision -->|Yes| success
  decision -->|No| failed

Notice that node IDs such as start and decision are short and stable, while labels such as Payload valid? are written for humans. This makes the source easier to maintain when labels change later.

3. Connectors and Labels

Connectors explain how the reader should move through the diagram. Use labels on branches whenever the next step depends on a condition. Unlabeled branches are fine for linear processes, but decision diamonds should usually have labels such as Yes, No, Valid, or Expired.

flowchart LR
  A[Start] --> B{Is it valid?}
  B -->|Yes| C[Process Data]
  B -->|No| D[Reject Request]

You can also use dotted connectors for optional or asynchronous paths:

flowchart LR
  A[Submit order] --> B[Create order record]
  B --> C[Return confirmation]
  B -.-> D[Send analytics event]

4. Subgraphs

To group related nodes, use subgraph. This is useful when a process crosses teams, services, or bounded contexts. Keep subgraph names short, because long names can make the rendered diagram wider than expected.

flowchart TD
  subgraph Frontend
    UI[User Interface]
  end
  subgraph Backend
    API[API Gateway]
    DB[(Database)]
  end
  UI --> API
  API --> DB

5. A Complete API Validation Example

The following example combines direction, labels, decision nodes, and subgraphs. It is realistic enough for API documentation but still small enough to paste into a README.

flowchart TD
  client([Client sends request])

  subgraph API Gateway
    auth{Authenticated?}
    rate{Rate limit ok?}
  end

  subgraph Application Service
    validate[Validate JSON payload]
    save[(Write to database)]
    publish[Publish domain event]
  end

  client --> auth
  auth -->|No| unauthorized[Return 401]
  auth -->|Yes| rate
  rate -->|No| limited[Return 429]
  rate -->|Yes| validate
  validate -->|Invalid| badRequest[Return 400]
  validate -->|Valid| save --> publish --> ok[Return 201]

Common Flowchart Mistakes

• Using punctuation in node IDs: keep IDs simple, such as paymentCheck, and put punctuation in the label instead.
• Forgetting quotes around complex text: if a label contains characters that confuse Mermaid, wrap the label with quotes inside the node syntax.
• Making one diagram explain everything: split very large flows into multiple diagrams, each focused on one decision or workflow.
• Mixing layout directions: choose TD or LR based on the reader's task and stay consistent.

When to Use a Flowchart Instead of Another Diagram

Use a flowchart when the important question is "what happens next?" For message timing, choose a sequence diagram. For data relationships, choose an ER diagram. For object structure, choose a class diagram. This simple distinction keeps your documentation readable.

When your snippet is ready, paste it into Mermaid Preview, export an SVG for crisp documentation, or copy the Mermaid source into your Markdown file.

Related Resources

• Mermaid diagram examples
• Mastering Mermaid sequence diagrams for API design
• How to embed Mermaid diagrams in Markdown