Mermaid Diagrams

Mermaid Diagrams

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

Decision Guide

Quick Reference

Flowchart

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

Sequence

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

Class

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

State

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

ER

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

C4 Context

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

Mindmap

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

GitGraph

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

Link Types

Subgraphs

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

Styling

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

Sequence Diagram Reference

Arrow Types

Participants

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

Activations

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

Control Flow

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

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

Grouping with Boxes

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

Relationships

Full Example

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

Generics

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

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

Composite States

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

Fork and Join

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

Choice

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

Notes

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

ER Diagram Reference

Cardinality

Relationship Types

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

Attributes

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

Boundaries

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

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

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

With Icons

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

Styling

mindmap
    root
        Important:::urgent
        Normal

GitGraph Reference

Basic Operations

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

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