Mermaid Diagrams

Generate diagrams using Mermaid syntax. All diagrams render in markdown code blocks with mermaid language identifier.

Decision Guide

Use Case	Diagram Type
Process flow, decision trees	Flowchart
API calls, system interactions over time	Sequence
OOP structure, domain models	Class
State machines, workflows	State
Database schemas, data relationships	ER
Software architecture (C4 model)	C4
Brainstorming, hierarchical organization	Mindmap
Git branching, commit history	GitGraph

Quick Reference

Flowchart

mermaid

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Sequence

mermaid

sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Request
    S-->>U: Response

Class

mermaid

classDiagram
    Animal <|-- Dog
    Animal : +String name
    Animal : +makeSound()
    Dog : +fetch()

State

mermaid

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Done --> [*]

ER

mermaid

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

C4 Context

mermaid

C4Context
    Person(user, "User", "End user")
    System(app, "Application", "Main system")
    Rel(user, app, "Uses")

Mindmap

mermaid

mindmap
  root((Topic))
    Branch A
      Leaf 1
      Leaf 2
    Branch B

GitGraph

mermaid

gitgraph
    commit
    branch feature
    commit
    checkout main
    merge feature

Flowchart Reference

Directions: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

Node Shapes

Shape	Syntax	Example
Rectangle	`[text]`	`A[Process]`
Rounded	`(text)`	`A(Start)`
Stadium	`([text])`	`A([Terminal])`
Diamond	`{text}`	`A{Decision}`
Circle	`((text))`	`A((Event))`
Hexagon	`{{text}}`	`A{{Prepare}}`
Cylinder	`[(text)]`	`A[(Database)]`
Subroutine	`[[text]]`	`A[[Subprocess]]`
Parallelogram	`[/text/]`	`A[/Input/]`
Trapezoid	`[\text\]`	`A[\Manual Op\]`

Link Types

Type	Syntax	Description
Arrow	`-->`	Solid with arrowhead
Open	`---`	Solid, no arrowhead
Dotted arrow	`-.->`	Dotted with arrowhead
Thick arrow	`==>`	Thick with arrowhead
With text	`--\|text\|>`	Label on link
Multi-length	`---->`	Longer link (more ranks)

Subgraphs

mermaid

flowchart TD
    subgraph Backend["Backend Services"]
        direction LR
        API --> DB[(Database)]
    end
    Client --> API

Styling

mermaid

flowchart TD
    A[Node]:::highlight
    classDef highlight fill:#ff9,stroke:#333
    style A stroke-width:2px

Sequence Diagram Reference

Arrow Types

Syntax	Style
`->>`	Solid with arrowhead
`-->>`	Dotted with arrowhead
`-x`	Solid with cross
`-)`	Async (open arrow)
`<<->>`	Bidirectional

Participants

mermaid

sequenceDiagram
    actor User
    participant API as API Server
    participant DB as Database

Activations

mermaid

sequenceDiagram
    User->>+API: Request
    API->>+DB: Query
    DB-->>-API: Result
    API-->>-User: Response

Control Flow

mermaid

sequenceDiagram
    alt Success
        A->>B: OK
    else Failure
        A->>B: Error
    end

    loop Every 5s
        A->>B: Ping
    end

    opt Optional
        A->>B: Maybe
    end

Notes

mermaid

sequenceDiagram
    Note right of A: Single note
    Note over A,B: Spanning note

Grouping with Boxes

mermaid

sequenceDiagram
    box Blue Frontend
        participant U as User
        participant W as Web
    end
    box Green Backend
        participant A as API
    end

Class Diagram Reference

Visibility Modifiers

Symbol	Meaning
`+`	Public
`-`	Private
`#`	Protected
`~`	Package

Relationships

Type	Syntax	Meaning
Inheritance	`<\|--`	Extends
Composition	`*--`	Strong owns
Aggregation	`o--`	Weak owns
Association	`-->`	Uses
Dependency	`..>`	Depends on
Realization	`..\|>`	Implements

Full Example

mermaid

classDiagram
    class Animal {
        <<abstract>>
        +String name
        +int age
        +makeSound()* void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    Animal <|-- Dog
    Dog "1" --> "*" Toy : plays with

Generics

mermaid

classDiagram
    class List~T~ {
        +add(T item)
        +T get(int index)
    }

Annotations

•<<interface>> - Interface
•<<abstract>> - Abstract class
•<<service>> - Service class
•<<enumeration>> - Enum

State Diagram Reference

Basic Syntax

mermaid

stateDiagram-v2
    [*] --> State1
    State1 --> State2: trigger
    State2 --> [*]

Composite States

mermaid

stateDiagram-v2
    state Active {
        [*] --> Running
        Running --> Paused: pause
        Paused --> Running: resume
    }
    [*] --> Active
    Active --> [*]: stop

Fork and Join

mermaid

stateDiagram-v2
    state fork <<fork>>
    state join <<join>>
    [*] --> fork
    fork --> Task1
    fork --> Task2
    Task1 --> join
    Task2 --> join
    join --> [*]

Choice

mermaid

stateDiagram-v2
    state check <<choice>>
    [*] --> check
    check --> Success: valid
    check --> Error: invalid

Notes

mermaid

stateDiagram-v2
    State1
    note right of State1
        Description here
    end note

ER Diagram Reference

Cardinality

Left	Right	Meaning
`\|o`	`o\|`	Zero or one
`\|\|`	`\|\|`	Exactly one
`}o`	`o{`	Zero or more
`}\|`	`\|{`	One or more

Relationship Types

•-- Identifying (solid line, child depends on parent)
•.. Non-identifying (dashed line, independent entities)

Attributes

mermaid

erDiagram
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }
    POST {
        int id PK
        int user_id FK
        string title
        text content
    }
    USER ||--o{ POST : writes

C4 Diagram Reference

C4 provides 4 levels of abstraction for architecture documentation.

Diagram Types

•C4Context - System context (level 1)
•C4Container - Container diagram (level 2)
•C4Component - Component diagram (level 3)
•C4Dynamic - Interaction sequences
•C4Deployment - Infrastructure layout

Elements

Element	Syntax	Use
Person	`Person(alias, label, desc)`	Users
Person_Ext	`Person_Ext(...)`	External users
System	`System(alias, label, desc)`	Software systems
System_Ext	`System_Ext(...)`	External systems
SystemDb	`SystemDb(...)`	Database systems
Container	`Container(alias, label, tech, desc)`	Applications
ContainerDb	`ContainerDb(...)`	Container databases
Component	`Component(alias, label, tech, desc)`	Internal parts

Boundaries

mermaid

C4Container
    System_Boundary(app, "Application") {
        Container(web, "Web App", "React")
        Container(api, "API", "Node.js")
        ContainerDb(db, "Database", "PostgreSQL")
    }
    Rel(web, api, "HTTP/JSON")
    Rel(api, db, "SQL")

Relationships

•Rel(from, to, label) - Standard relationship
•Rel_U/D/L/R(...) - Directional hints
•BiRel(from, to, label) - Bidirectional

Complete C4 Context Example

mermaid

C4Context
    Person(user, "Customer", "Uses the system")
    System(app, "E-Commerce", "Online store")
    System_Ext(payment, "Payment Gateway", "Processes payments")
    System_Ext(shipping, "Shipping API", "Handles delivery")

    Rel(user, app, "Browses, orders")
    Rel(app, payment, "Processes payments")
    Rel(app, shipping, "Ships orders")

Mindmap Reference

Uses indentation for hierarchy. Root node required.

Node Shapes

mermaid

mindmap
    root((Central Topic))
        [Square]
        (Rounded)
        ))Cloud((
        {{Hexagon}}

With Icons

mermaid

mindmap
    root((Project))
        Tasks ::icon(fa fa-tasks)
        Team ::icon(fa fa-users)

Styling

mermaid

mindmap
    root
        Important:::urgent
        Normal

GitGraph Reference

Basic Operations

mermaid

gitgraph
    commit id: "initial"
    commit id: "feature"
    branch develop
    commit
    checkout main
    merge develop tag: "v1.0"

Commit Types

•type: NORMAL - Default
•type: HIGHLIGHT - Emphasized
•type: REVERSE - Reverted

Full Example

mermaid

gitgraph
    commit id: "init"
    branch feature
    commit id: "add-login"
    commit id: "add-logout" type: HIGHLIGHT
    checkout main
    commit id: "hotfix" type: REVERSE
    merge feature tag: "v1.0"

Best Practices

DO

•Keep diagrams focused (one concept per diagram)
•Use clear, descriptive labels
•Add direction hints (TD, LR) explicitly
•Use subgraphs/boundaries for grouping
•Include legends for complex diagrams

DON'T

•Overcrowd with too many nodes (>15-20)
•Use cryptic single-letter IDs without labels
•Mix multiple concerns in one diagram
•Rely on auto-layout for complex diagrams

Layout Tips

•Flowchart: LR for processes, TD for hierarchies
•Sequence: Order participants by interaction frequency
•Class: Group related classes with namespaces
•C4: Start with Context, drill down to Container/Component
•ER: Place central entities in the middle

Common Fixes

Problem	Solution
Nodes overlap	Reduce node count, use subgraphs
Links cross confusingly	Reorder nodes, change direction
Text truncated	Use aliases: `A[Long Name] as short`
Diagram too wide	Switch `LR` to `TD`