Mermaid Diagrams

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

Decision Guide

Quick Reference

Flowchart

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

Sequence

mermaid
1sequenceDiagram
2    participant U as User
3    participant S as Server
4    U->>S: Request
5    S-->>U: Response

Class

mermaid
1classDiagram
2    Animal <|-- Dog
3    Animal : +String name
4    Animal : +makeSound()
5    Dog : +fetch()

State

mermaid
1stateDiagram-v2
2    [*] --> Idle
3    Idle --> Processing: start
4    Processing --> Done: complete
5    Done --> [*]

ER

mermaid
1erDiagram
2    CUSTOMER ||--o{ ORDER : places
3    ORDER ||--|{ LINE-ITEM : contains

C4 Context

mermaid
1C4Context
2    Person(user, "User", "End user")
3    System(app, "Application", "Main system")
4    Rel(user, app, "Uses")

Mindmap

mermaid
1mindmap
2  root((Topic))
3    Branch A
4      Leaf 1
5      Leaf 2
6    Branch B

GitGraph

mermaid
1gitgraph
2    commit
3    branch feature
4    commit
5    checkout main
6    merge feature

Flowchart Reference

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

Node Shapes

Link Types

Subgraphs

mermaid
1flowchart TD
2    subgraph Backend["Backend Services"]
3        direction LR
4        API --> DB[(Database)]
5    end
6    Client --> API

Styling

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

Sequence Diagram Reference

Arrow Types

Participants

mermaid
1sequenceDiagram
2    actor User
3    participant API as API Server
4    participant DB as Database

Activations

mermaid
1sequenceDiagram
2    User->>+API: Request
3    API->>+DB: Query
4    DB-->>-API: Result
5    API-->>-User: Response

Control Flow

mermaid
1sequenceDiagram
2    alt Success
3        A->>B: OK
4    else Failure
5        A->>B: Error
6    end
7
8    loop Every 5s
9        A->>B: Ping
10    end
11
12    opt Optional
13        A->>B: Maybe
14    end

Notes

mermaid
1sequenceDiagram
2    Note right of A: Single note
3    Note over A,B: Spanning note

Grouping with Boxes

mermaid
1sequenceDiagram
2    box Blue Frontend
3        participant U as User
4        participant W as Web
5    end
6    box Green Backend
7        participant A as API
8    end

Class Diagram Reference

Visibility Modifiers

Relationships

Full Example

mermaid
1classDiagram
2    class Animal {
3        <<abstract>>
4        +String name
5        +int age
6        +makeSound()* void
7    }
8    class Dog {
9        +String breed
10        +fetch() void
11    }
12    Animal <|-- Dog
13    Dog "1" --> "*" Toy : plays with

Generics

mermaid
1classDiagram
2    class List~T~ {
3        +add(T item)
4        +T get(int index)
5    }

Annotations

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

State Diagram Reference

Basic Syntax

mermaid
1stateDiagram-v2
2    [*] --> State1
3    State1 --> State2: trigger
4    State2 --> [*]

Composite States

mermaid
1stateDiagram-v2
2    state Active {
3        [*] --> Running
4        Running --> Paused: pause
5        Paused --> Running: resume
6    }
7    [*] --> Active
8    Active --> [*]: stop

Fork and Join

mermaid
1stateDiagram-v2
2    state fork <<fork>>
3    state join <<join>>
4    [*] --> fork
5    fork --> Task1
6    fork --> Task2
7    Task1 --> join
8    Task2 --> join
9    join --> [*]

Choice

mermaid
1stateDiagram-v2
2    state check <<choice>>
3    [*] --> check
4    check --> Success: valid
5    check --> Error: invalid

Notes

mermaid
1stateDiagram-v2
2    State1
3    note right of State1
4        Description here
5    end note

ER Diagram Reference

Cardinality

Relationship Types

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

Attributes

mermaid
1erDiagram
2    USER {
3        int id PK
4        string email UK
5        string name
6        datetime created_at
7    }
8    POST {
9        int id PK
10        int user_id FK
11        string title
12        text content
13    }
14    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

Boundaries

mermaid
1C4Container
2    System_Boundary(app, "Application") {
3        Container(web, "Web App", "React")
4        Container(api, "API", "Node.js")
5        ContainerDb(db, "Database", "PostgreSQL")
6    }
7    Rel(web, api, "HTTP/JSON")
8    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
1C4Context
2    Person(user, "Customer", "Uses the system")
3    System(app, "E-Commerce", "Online store")
4    System_Ext(payment, "Payment Gateway", "Processes payments")
5    System_Ext(shipping, "Shipping API", "Handles delivery")
6
7    Rel(user, app, "Browses, orders")
8    Rel(app, payment, "Processes payments")
9    Rel(app, shipping, "Ships orders")

Mindmap Reference

Uses indentation for hierarchy. Root node required.

Node Shapes

mermaid
1mindmap
2    root((Central Topic))
3        [Square]
4        (Rounded)
5        ))Cloud((
6        {{Hexagon}}

With Icons

mermaid
1mindmap
2    root((Project))
3        Tasks ::icon(fa fa-tasks)
4        Team ::icon(fa fa-users)

Styling

mermaid
1mindmap
2    root
3        Important:::urgent
4        Normal

GitGraph Reference

Basic Operations

mermaid
1gitgraph
2    commit id: "initial"
3    commit id: "feature"
4    branch develop
5    commit
6    checkout main
7    merge develop tag: "v1.0"

Commit Types

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

Full Example

mermaid
1gitgraph
2    commit id: "init"
3    branch feature
4    commit id: "add-login"
5    commit id: "add-logout" type: HIGHLIGHT
6    checkout main
7    commit id: "hotfix" type: REVERSE
8    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