Mermaid Diagrams

Mermaid Diagrams

Generate diagrams in markdown that render in GitHub, GitLab, VS Code, Obsidian, Notion.

Quick Start

````markdown

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

````

Quick Decision Tree

What to visualize?
├─ Process, algorithm, decision flow    → flowchart
├─ API calls, service interactions      → sequenceDiagram
├─ Database tables, relationships       → erDiagram
├─ OOP, type hierarchy, domain model    → classDiagram
├─ State machine, lifecycle             → stateDiagram-v2
├─ System architecture, services        → flowchart + subgraphs (or C4Context)
├─ Project timeline, sprints            → gantt
├─ User experience, pain points         → journey
├─ Git branches                         → gitGraph
├─ Data distribution                    → pie
└─ Priority matrix                      → quadrantChart

Diagram Types

Common Patterns

System Architecture

flowchart LR
    subgraph Client
        Browser & Mobile
    end
    subgraph Services
        API --> Auth & Core
    end
    subgraph Data
        DB[(PostgreSQL)]
    end
    Client --> API
    Core --> DB

API Request Flow

sequenceDiagram
    autonumber
    Client->>+API: POST /orders
    API->>Auth: Validate
    Auth-->>API: OK
    API->>+DB: Insert
    DB-->>-API: ID
    API-->>-Client: 201 Created

Database Schema

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    USER { uuid id PK; string email UK }
    ORDER { uuid id PK; uuid user_id FK }

State Machine

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit()
    Submitted --> Approved : approve()
    Submitted --> Rejected : reject()
    Approved --> [*]

Syntax Quick Reference

Flowchart Nodes

[Rectangle]  (Rounded)  {Diamond}  [(Database)]  [[Subroutine]]
((Circle))   >Asymmetric]   {{Hexagon}}

Flowchart Edges

A --> B       # Arrow
A --- B       # Line
A -.-> B      # Dotted arrow
A ==> B       # Thick arrow
A -->|text| B # Labeled

Sequence Arrows

->>   # Solid arrow (request)
-->>  # Dotted arrow (response)
-x    # X end (async)
-)    # Open arrow

ER Cardinality

||--||   # One to one
||--o{   # One to many
}o--o{   # Many to many

Best Practices

1. Choose the right type — Use decision tree above 2. Keep focused — One concept per diagram 3. Use meaningful labels — Not just A, B, C 4. Direction matters — LR for flows, TB for hierarchies 5. Group with subgraphs — Organize related nodes

Reference Documentation

Resources

• Official Documentation: https://mermaid.js.org
• Live Editor: https://mermaid.live
• GitHub Repository: https://github.com/mermaid-js/mermaid
• GitHub Markdown Support: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
• GitLab Markdown Support: https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts

mermaid-diagrams

Generate Mermaid diagrams in markdown. This skill activates automatically when you ask for diagrams, charts, visualizations, or system documentation.

Supported Diagram Types

Example Usage

"Create a sequence diagram showing the OAuth flow"
"Draw an ER diagram for a blog database"
"Make a flowchart of the CI/CD pipeline"
"Show me a Gantt chart for sprint planning"
"Create a C4 context diagram for our system"

Skill Structure

• [SKILL.md](SKILL.md) - Main skill file (concise overview)
• Reference Files:
• FLOWCHARTS.md - Flowchart syntax
• SEQUENCE.md - Sequence diagrams
• CLASS-ER.md - Class & ER diagrams
• STATE-JOURNEY.md - State & user journey
• DATA-CHARTS.md - Gantt, Pie, Timeline, Charts
• ARCHITECTURE.md - C4, Architecture, Block, Kanban
• ADVANCED.md - Configuration & styling
• CHEATSHEET.md - Quick reference

Did You Know Mermaid Can Do This?

sankey-beta

Visitors,Signed Up,4200
Visitors,Bounced,8500
Signed Up,Free Trial,3100
Signed Up,Churned,1100
Free Trial,Converted,1800
Free Trial,Churned,1300
Converted,Pro Plan,1200
Converted,Enterprise,600

quadrantChart
    title Feature Prioritization
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Schedule
    quadrant-3 Delegate
    quadrant-4 Eliminate
    Dark Mode: [0.2, 0.9]
    API v2: [0.7, 0.85]
    Bug Fixes: [0.15, 0.5]
    Refactor Auth: [0.9, 0.4]
    Update Docs: [0.3, 0.3]

xychart-beta
    title "Monthly Active Users (2024)"
    x-axis [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
    y-axis "Users (thousands)" 0 --> 150
    bar [23, 34, 45, 52, 67, 78, 89, 95, 108, 120, 135, 142]
    line [23, 34, 45, 52, 67, 78, 89, 95, 108, 120, 135, 142]

Advanced Configuration & Styling

Theming, configuration, custom styling, and troubleshooting for Mermaid diagrams.

---

Configuration

Init Directive

Configure diagrams using the init directive:

%%{init: { 'theme': 'dark' } }%%
flowchart LR
    A --> B

Multi-Line Configuration

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#ffffff'
  }
}}%%
flowchart LR
    A --> B --> C

---

Themes

Built-in Themes

Usage

%%{init: {'theme': 'forest'}}%%
flowchart LR
    A --> B --> C

---

Theme Variables

Core Variables

Typography

---

Custom Theme Example

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#2563eb',
    'secondaryColor': '#10b981',
    'tertiaryColor': '#f1f5f9',
    'lineColor': '#64748b',
    'textColor': '#1e293b',
    'fontSize': '16px',
    'fontFamily': 'Inter, sans-serif'
  }
}}%%
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Failure]

---

Diagram-Specific Variables

Flowchart

Sequence Diagram

State Diagram

Gantt Chart

---

Styling

Class-Based Styling

Define Classes

flowchart LR
    A[Start]:::success --> B[Process]:::info --> C[End]:::warning

    classDef success fill:#10b981,stroke:#059669,color:white
    classDef info fill:#3b82f6,stroke:#2563eb,color:white
    classDef warning fill:#f59e0b,stroke:#d97706,color:white

Apply to Multiple Nodes

flowchart LR
    A --> B --> C --> D
    class A,D success
    class B,C info

    classDef success fill:#10b981
    classDef info fill:#3b82f6

Default Class

flowchart LR
    A --> B --> C

    classDef default fill:#f8fafc,stroke:#cbd5e1

---

Individual Node Styling

flowchart LR
    A --> B --> C

    style A fill:#10b981,stroke:#059669,color:white
    style B fill:#3b82f6,stroke:#2563eb,color:white
    style C fill:#ef4444,stroke:#dc2626,color:white

Style Properties

---

Link Styling

Individual Links

flowchart LR
    A --> B --> C --> D

    linkStyle 0 stroke:green,stroke-width:2px
    linkStyle 1 stroke:blue,stroke-width:2px
    linkStyle 2 stroke:red,stroke-width:2px,stroke-dasharray:5

All Links

flowchart LR
    A --> B --> C

    linkStyle default stroke:gray,stroke-width:1px

---

Layout Engine

ELK Renderer

For complex diagrams (v9.4+):

%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart TB
    A --> B & C & D
    B & C & D --> E
    E --> F & G

Benefits:

• Better handling of complex layouts
• More predictable edge routing
• Improved subgraph positioning

---

Security Levels

Control what Mermaid can do:

%%{init: { 'securityLevel': 'loose' }}%%
flowchart LR
    A --> B
    click A href "https://example.com" _blank

---

Troubleshooting

Common Issues

Special Characters

Escape with HTML entities or quotes:

flowchart LR
    A["Node with #quot;quotes#quot;"]
    B["Arrow -> symbol"]
    C["Hash #35; symbol"]

HTML Entities

Long Labels

Use markdown strings:

flowchart LR
    A["`This is a very long
    label that wraps
    across multiple lines`"]

---

Debugging Tips

1. Check Syntax

• Verify diagram type declaration
• Check for unclosed brackets/quotes
• Ensure arrow syntax matches diagram type

2. Test Incrementally

• Start with minimal diagram
• Add elements one at a time
• Identify breaking change

3. Use Live Editor

Test at: https://mermaid.live

4. Platform Differences

• Check target platform support
• Some features are version-specific
• Export to PNG/SVG for guaranteed rendering

---

Arrow Syntax by Diagram Type

---

Frontmatter Configuration

Alternative to init directive:

---
title: My Diagram
config:
  theme: forest
  flowchart:
    defaultRenderer: elk
---

flowchart LR
    A --> B

---

Directive Reference

Diagram Directives

Common Init Options

%%{init: {
  'theme': 'default',
  'themeVariables': { ... },
  'flowchart': {
    'defaultRenderer': 'elk',
    'curve': 'basis',
    'padding': 15
  },
  'sequence': {
    'showSequenceNumbers': true,
    'actorMargin': 50,
    'boxMargin': 10
  },
  'gantt': {
    'barHeight': 20,
    'fontSize': 11,
    'sectionFontSize': 14
  }
}}%%

---

Accessibility

Alt Text

For screen readers, provide context before diagrams:

The following diagram shows the authentication flow:

sequenceDiagram User->>App: Login App->>Auth: Validate

ARIA Labels

When embedding in HTML:

<div class="mermaid" role="img" aria-label="Authentication flow diagram">
  sequenceDiagram
    User->>App: Login
</div>

---

Performance Tips

1. Limit complexity - Split large diagrams 2. Use ELK for complex layouts 3. Minimize styling - Class-based over inline 4. Cache renders when possible 5. Lazy load in documentation

---

Export Options

From Live Editor

• PNG (transparent or white background)
• SVG (scalable)
• Markdown

Programmatic

import mermaid from 'mermaid';

const svg = await mermaid.render('id', diagramText);

CLI

npx @mermaid-js/mermaid-cli -i input.md -o output.svg

Architecture Diagrams

Mermaid provides several diagram types for system architecture: Architecture diagrams, Block diagrams, C4 diagrams, and Kanban boards.

---

Architecture Diagrams

Cloud and CI/CD infrastructure visualization using icons and groups.

Basic Syntax

architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service server(server)[Server] in api

    db:L -- R:server

---

Components

Groups

Organize services logically:

group {id}({icon})[{title}]
group {id}({icon})[{title}] in {parent_id}

architecture-beta
    group cloud(cloud)[Cloud Infrastructure]
    group vpc(cloud)[VPC] in cloud
    group public(cloud)[Public Subnet] in vpc
    group private(cloud)[Private Subnet] in vpc

Services

Individual components:

service {id}({icon})[{title}]
service {id}({icon})[{title}] in {group_id}

architecture-beta
    group backend(cloud)[Backend]

    service api(server)[API Server] in backend
    service db(database)[PostgreSQL] in backend
    service cache(database)[Redis] in backend

Junctions

4-way connection points:

junction {id}
junction {id} in {group_id}

---

Edges

Connect components with directional flow:

{service}:{direction} {arrow} {direction}:{service}

Directions

Arrow Types

architecture-beta
    service a(server)[A]
    service b(server)[B]
    service c(server)[C]
    service d(server)[D]

    a:R --> L:b
    b:B --> T:c
    c:L <-- R:d

---

Icons

Default Icons

Iconify Icons

Access 200,000+ icons from iconify.design:

architecture-beta
    service aws(logos:aws)[AWS]
    service gcp(logos:google-cloud)[GCP]

---

Example: Microservices Architecture

architecture-beta
    group cloud(cloud)[AWS Cloud]

    group public(cloud)[Public] in cloud
    group private(cloud)[Private] in cloud

    service lb(server)[Load Balancer] in public
    service cdn(internet)[CloudFront] in public

    service api1(server)[API Server 1] in private
    service api2(server)[API Server 2] in private
    service db(database)[RDS PostgreSQL] in private
    service cache(database)[ElastiCache] in private
    service queue(server)[SQS] in private
    service worker(server)[Worker] in private

    junction junc in private

    cdn:B --> T:lb
    lb:B --> T:junc
    junc:L --> R:api1
    junc:R --> L:api2
    api1:B --> T:db
    api2:B --> T:db
    api1:R --> L:cache
    api2:L --> R:cache
    api1:B --> T:queue
    queue:R --> L:worker
    worker:B --> T:db

---

Block Diagrams

System component layouts with flexible positioning.

Basic Syntax

block-beta
    columns 3
    a b c
    d e f

---

Columns

Control layout width:

block-beta
    columns 4
    a b c d
    e f g h

Block Width (Spanning)

block-beta
    columns 3
    a:1 b:2
    c:3

Block Shapes

block-beta
    columns 4
    a["Rectangle"]
    b("Rounded")
    c(["Stadium"])
    d[("Database")]
    e(("Circle"))
    f{"Diamond"}
    g{{"Hexagon"}}

---

Nested Blocks

block-beta
    columns 2

    block:frontend
        columns 1
        UI["React App"]
        State["Redux Store"]
    end

    block:backend
        columns 1
        API["REST API"]
        WS["WebSocket"]
    end

    DB[("PostgreSQL")]
    Cache[("Redis")]

    frontend --> backend
    backend --> DB
    backend --> Cache

---

Connections

block-beta
    columns 3

    A["Client"] --> B["API Gateway"]
    B --> C["Service A"]
    B --> D["Service B"]
    C --> E[("Database")]
    D --> E

---

Styling

block-beta
    columns 3
    Frontend Backend Database

    classDef front fill:#4ade80,stroke:#166534
    classDef back fill:#60a5fa,stroke:#1d4ed8
    classDef data fill:#f472b6,stroke:#be185d

    class Frontend front
    class Backend back
    class Database data

---

Example: Three-Tier Architecture

block-beta
    columns 3

    block:presentation["Presentation Tier"]
        columns 1
        Web["Web App"]
        Mobile["Mobile App"]
    end

    space

    block:application["Application Tier"]
        columns 1
        API["API Gateway"]
        Auth["Auth Service"]
        Core["Core Service"]
    end

    space

    block:data["Data Tier"]
        columns 1
        DB[("PostgreSQL")]
        Cache[("Redis")]
        Queue["Message Queue"]
    end

    presentation --> application
    application --> data

    classDef tier fill:#f0f9ff,stroke:#0284c7
    class presentation,application,data tier

---

C4 Diagrams

Software architecture using the C4 model (Context, Container, Component, Code).

Diagram Types

---

C4Context (Level 1)

Shows system in context with users and external systems:

C4Context
    title System Context Diagram

    Person(user, "User", "A user of our system")
    Person(admin, "Admin", "System administrator")

    System(system, "Our System", "Main application")

    System_Ext(email, "Email Service", "SendGrid")
    System_Ext(payment, "Payment Gateway", "Stripe")

    Rel(user, system, "Uses")
    Rel(admin, system, "Manages")
    Rel(system, email, "Sends emails")
    Rel(system, payment, "Processes payments")

Elements

---

C4Container (Level 2)

Shows containers within the system:

C4Container
    title Container Diagram

    Person(user, "User", "End user")

    System_Boundary(system, "Our System") {
        Container(web, "Web App", "React", "User interface")
        Container(api, "API", "Node.js", "Business logic")
        ContainerDb(db, "Database", "PostgreSQL", "Stores data")
        ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async processing")
        Container(worker, "Worker", "Node.js", "Background jobs")
    }

    System_Ext(email, "Email Service", "SendGrid")

    Rel(user, web, "Uses", "HTTPS")
    Rel(web, api, "Calls", "REST/JSON")
    Rel(api, db, "Reads/Writes", "SQL")
    Rel(api, queue, "Publishes", "AMQP")
    Rel(queue, worker, "Consumes", "AMQP")
    Rel(worker, email, "Sends via", "HTTPS")

Container Elements

---

C4Component (Level 3)

Shows components within a container:

C4Component
    title Component Diagram - API

    Container_Boundary(api, "API Container") {
        Component(auth, "Auth Controller", "Express", "Handles authentication")
        Component(orders, "Orders Controller", "Express", "Order management")
        Component(authSvc, "Auth Service", "TypeScript", "Auth business logic")
        Component(orderSvc, "Order Service", "TypeScript", "Order business logic")
        Component(repo, "Repository", "TypeScript", "Data access")
    }

    ContainerDb(db, "Database", "PostgreSQL")
    Container_Ext(cache, "Cache", "Redis")

    Rel(auth, authSvc, "Uses")
    Rel(orders, orderSvc, "Uses")
    Rel(authSvc, repo, "Uses")
    Rel(orderSvc, repo, "Uses")
    Rel(repo, db, "Reads/Writes")
    Rel(authSvc, cache, "Caches sessions")

---

C4Dynamic

Shows runtime interactions:

C4Dynamic
    title Dynamic Diagram - Order Flow

    Person(user, "User")
    Container(web, "Web App", "React")
    Container(api, "API", "Node.js")
    ContainerDb(db, "Database", "PostgreSQL")
    Container(worker, "Worker", "Node.js")
    System_Ext(email, "Email", "SendGrid")

    Rel(user, web, "1. Places order")
    Rel(web, api, "2. POST /orders")
    Rel(api, db, "3. Insert order")
    Rel(api, web, "4. Order created")
    Rel(api, worker, "5. Queue email job")
    Rel(worker, email, "6. Send confirmation")

---

C4Deployment

Shows deployment to infrastructure:

C4Deployment
    title Deployment Diagram

    Deployment_Node(aws, "AWS", "Cloud") {
        Deployment_Node(vpc, "VPC", "Network") {
            Deployment_Node(eks, "EKS", "Kubernetes") {
                Container(api, "API", "Node.js")
                Container(worker, "Worker", "Node.js")
            }
            Deployment_Node(rds, "RDS", "Database") {
                ContainerDb(db, "PostgreSQL", "Database")
            }
        }
    }

    Rel(api, db, "SQL")

---

Relationships

---

Styling

C4Context
    Person(user, "User")
    System(system, "System")
    Rel(user, system, "Uses")

    UpdateElementStyle(user, $fontColor="blue", $bgColor="lightblue")
    UpdateRelStyle(user, system, $textColor="red", $lineColor="red")

---

Kanban Diagrams

Workflow boards for task management.

Basic Syntax

kanban
    Todo
        task1[Design API]
        task2[Write tests]
    In Progress
        task3[Implement auth]
    Done
        task4[Setup project]

---

Task Metadata

kanban
    Backlog
        task1[User authentication]
        @{ ticket: AUTH-123 }
        @{ assigned: john }
        @{ priority: High }

Metadata Keys

---

Configuration

---
config:
  kanban:
    ticketBaseUrl: 'https://jira.example.com/browse/#TICKET#'
---

---

Example: Sprint Board

kanban
    Backlog
        story1[User login]
        story2[Password reset]
        story3[OAuth integration]

    Todo
        task1[Design login form]
        task2[Setup JWT auth]

    In Progress
        task3[Implement login API]
        @{ assigned: alice }
        task4[Write login tests]
        @{ assigned: bob }

    Review
        task5[Database schema]
        @{ assigned: charlie }

    Done
        task6[Project setup]
        task7[CI/CD pipeline]

---

Packet Diagrams

Network protocol visualization.

Basic Syntax

packet-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"

Bit Ranges

Two syntaxes:

• Absolute: 0-15: "Field"
• Relative: +16: "Field" (16 bits from current position)

---

Example: TCP Packet

packet-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"
    64-95: "Acknowledgment Number"
    96-99: "Data Offset"
    100-105: "Reserved"
    106: "URG"
    107: "ACK"
    108: "PSH"
    109: "RST"
    110: "SYN"
    111: "FIN"
    112-127: "Window"
    128-143: "Checksum"
    144-159: "Urgent Pointer"
    160-191: "(Options)"
    192-255: "Data"

Example: UDP Packet

packet-beta
    title UDP Packet
    +16: "Source Port"
    +16: "Destination Port"
    +16: "Length"
    +16: "Checksum"
    +64: "Data"

---

Requirement Diagrams

System requirements and traceability.

Basic Syntax

requirementDiagram

    requirement user_login {
        id: REQ-001
        text: Users must be able to log in
        risk: low
        verifymethod: test
    }

    element login_page {
        type: ui_component
        docref: UI-001
    }

    login_page - satisfies -> user_login

Requirement Types

Relationships

---

Example: Feature Requirements

requirementDiagram

    requirement auth_system {
        id: REQ-100
        text: System shall provide user authentication
        risk: high
        verifymethod: test
    }

    functionalRequirement login {
        id: REQ-101
        text: Users can log in with email/password
        risk: medium
        verifymethod: test
    }

    functionalRequirement mfa {
        id: REQ-102
        text: System shall support MFA
        risk: high
        verifymethod: demonstration
    }

    element auth_service {
        type: service
        docref: SVC-001
    }

    element auth_tests {
        type: test_suite
        docref: TEST-001
    }

    auth_system - contains -> login
    auth_system - contains -> mfa
    auth_service - satisfies -> login
    auth_service - satisfies -> mfa
    auth_tests - verifies -> login
    auth_tests - verifies -> mfa

Mermaid Quick Reference Cheatsheet

---

Diagram Declarations

---

Flowchart

Direction

TB / TD   Top to Bottom
BT        Bottom to Top
LR        Left to Right
RL        Right to Left

Node Shapes

A[Rectangle]       B(Rounded)         C([Stadium])
D[[Subroutine]]    E[(Database)]      F((Circle))
G{Diamond}         H{{Hexagon}}       I[/Parallelogram/]
J(((Double)))

Edges

A --> B       Solid arrow
A --- B       Solid line
A -.-> B      Dotted arrow
A ==> B       Thick arrow
A --o B       Circle end
A --x B       Cross end
A <--> B      Bidirectional
A -->|text| B Labeled

Subgraph

flowchart TB
    subgraph Name
        A --> B
    end

---

Sequence Diagram

Messages

A->>B     Solid arrow (sync)
A-->>B    Dotted arrow (response)
A-xB      Failed message
A-)B      Async message

Activation

A->>+B: Request    Activate B
B-->>-A: Response  Deactivate B

Control Flow

alt Condition
    A->>B: If true
else
    A->>B: If false
end

opt Optional
    A->>B: Maybe
end

loop Every 30s
    A->>B: Repeat
end

par Parallel
    A->>B: Task 1
and
    A->>C: Task 2
end

Notes

Note right of A: Text
Note over A,B: Spanning note

---

Class Diagram

Visibility

+  Public
-  Private
#  Protected
~  Package

Relationships

A <|-- B    Inheritance
A *-- B     Composition
A o-- B     Aggregation
A --> B     Association
A ..> B     Dependency
A ..|> B    Realization

Cardinality

A "1" --> "*" B : has
A "0..1" --> "1..*" B

Annotations

class A {
    <<interface>>
    +method()
}

class B {
    <<enumeration>>
    VALUE1
    VALUE2
}

---

ER Diagram

Cardinality

||--||    One to one
||--o{    One to many
}o--o{    Many to many (optional)
}|--|{    Many to many (required)

Line Types

--    Identifying (solid)
..    Non-identifying (dashed)

Attributes

ENTITY {
    type name PK     Primary key
    type name FK     Foreign key
    type name UK     Unique key
    type name        Regular
}

---

State Diagram

Basic

[*] --> State1          Start
State1 --> State2       Transition
State2 --> [*]          End
State1 --> State1       Self-loop

Composite

state Parent {
    [*] --> Child1
    Child1 --> Child2
}

Choice

state check <<choice>>
A --> check
check --> B : condition1
check --> C : condition2

Fork/Join

state fork <<fork>>
state join <<join>>
[*] --> fork
fork --> A
fork --> B
A --> join
B --> join
join --> [*]

---

Gantt Chart

Task Syntax

Task name : [tags], [id], [start], [end/duration]

Completed   :done, t1, 2024-01-01, 7d
Active      :active, t2, after t1, 5d
Critical    :crit, t3, 2024-01-15, 3d
Milestone   :milestone, m1, 2024-01-20, 0d

Dependencies

after taskId
after t1 t2    After multiple

---

Pie Chart

pie showData
    title Chart Title
    "Label 1" : 42
    "Label 2" : 28
    "Label 3" : 30

---

Timeline

timeline
    title Title
    section Period
        Date : Event 1
             : Event 2

---

C4 Diagrams

Elements

Person(alias, "Label", "Description")
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")
Container(alias, "Label", "Tech", "Description")
ContainerDb(alias, "Label", "Tech", "Description")
Component(alias, "Label", "Tech", "Description")

Relationships

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label")

Boundaries

System_Boundary(alias, "Label") {
    Container(...)
}

---

Architecture Diagram

Groups

group id(icon)[Title]
group id(icon)[Title] in parent

Services

service id(icon)[Title]
service id(icon)[Title] in group

Edges

a:R --> L:b     Right of a to left of b
a:T --> B:b     Top to bottom
<-->            Bidirectional

Icons

cloud, database, disk, internet, server

---

Styling

Theme

%%{init: {'theme': 'dark'}}%%

Themes: default, dark, forest, neutral, base

Class Definition

flowchart LR
    A:::className --> B
    classDef className fill:#f00,stroke:#333,color:#fff

Individual Style

flowchart LR
    A --> B
    style A fill:#f00

Link Style

flowchart LR
    A --> B --> C
    linkStyle 0 stroke:red
    linkStyle default stroke:gray

---

Special Characters

---

Markdown in Labels

flowchart LR
    A["`**Bold** and *italic*`"]
    B["`Line 1
    Line 2`"]

---

Configuration

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'lineColor': '#64748b'
  }
}}%%

---

Quick Decision Guide

---

Platform Support

---

Resources

• Live Editor: https://mermaid.live
• Documentation: https://mermaid.js.org
• GitHub: https://github.com/mermaid-js/mermaid

Class & Entity Relationship Diagrams

Class diagrams model object-oriented structures. ER diagrams model database schemas and data relationships.

---

Class Diagrams

Basic Syntax

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }

---

Class Definition

Attributes and Methods

classDiagram
    class User {
        +String id
        +String email
        -String passwordHash
        +login() bool
        +logout() void
        #validatePassword(pwd) bool
        -hashPassword(pwd) String
    }

Visibility Modifiers

Return Types

classDiagram
    class Repository {
        +findById(id) Entity
        +findAll() List~Entity~
        +save(entity) void
        +delete(id) bool
    }

---

Relationships

Relationship Types

classDiagram
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends
    Dog *-- Leg : composition
    Dog o-- Collar : aggregation
    Dog --> Food : association
    Dog ..> Vet : dependency

Cardinality

classDiagram
    Customer "1" --> "*" Order : places
    Order "1" --> "1..*" LineItem : contains
    Order "0..1" --> "1" ShippingAddress : ships to

---

Annotations

classDiagram
    class IRepository {
        <<interface>>
        +find(id)
        +save(entity)
    }

    class OrderStatus {
        <<enumeration>>
        PENDING
        CONFIRMED
        SHIPPED
        DELIVERED
    }

    class UserService {
        <<service>>
        +createUser()
    }

    class BaseEntity {
        <<abstract>>
        +id
    }

---

Generic Types

classDiagram
    class Repository~T~ {
        +find(id) T
        +findAll() List~T~
        +save(entity: T) void
    }

    class UserRepository {
        +findByEmail(email) User
    }

    Repository~User~ <|-- UserRepository

---

Namespaces

classDiagram
    namespace Domain {
        class User
        class Order
        class Product
    }

    namespace Infrastructure {
        class UserRepository
        class OrderRepository
    }

    User "1" --> "*" Order
    UserRepository ..|> IUserRepository

---

Notes

classDiagram
    class Order
    note for Order "Aggregate root for order management"

    class OrderItem
    note for OrderItem "Value object - immutable"

---

Styling

classDiagram
    class Important
    class Normal

    style Important fill:#f9f,stroke:#333,stroke-width:4px

---

Example: Domain Model

classDiagram
    class Order {
        +OrderId id
        +CustomerId customerId
        +OrderStatus status
        +Money total
        +addItem(product, quantity)
        +removeItem(itemId)
        +submit()
        +cancel()
    }

    class OrderItem {
        +OrderItemId id
        +ProductId productId
        +Quantity quantity
        +Money unitPrice
        +getSubtotal() Money
    }

    class Customer {
        +CustomerId id
        +Email email
        +Name name
        +getOrders() Order[]
    }

    class OrderStatus {
        <<enumeration>>
        DRAFT
        SUBMITTED
        CONFIRMED
        SHIPPED
        DELIVERED
        CANCELLED
    }

    class Money {
        <<value object>>
        +Decimal amount
        +String currency
        +add(other) Money
        +subtract(other) Money
    }

    Customer "1" --> "*" Order : places
    Order "1" *-- "1..*" OrderItem : contains
    Order --> OrderStatus
    Order --> Money : total
    OrderItem --> Money : unitPrice

---

Entity Relationship Diagrams

Basic Syntax

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains

---

Relationship Notation (Crow's Foot)

Cardinality Symbols

Line Types

Common Patterns

erDiagram
    A ||--|| B : "one to one"
    C ||--o{ D : "one to many"
    E }o--o{ F : "many to many (optional)"
    G }|--|{ H : "many to many (required)"

---

Entity Attributes

Basic Attributes

erDiagram
    USER {
        uuid id
        string email
        string name
        timestamp created_at
    }

Attribute Modifiers

erDiagram
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }

    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total
        string status
    }

    USER ||--o{ ORDER : places

Attribute Comments

erDiagram
    USER {
        uuid id PK "Primary identifier"
        string email UK "Must be unique"
        string password_hash "BCrypt hashed"
        timestamp created_at "Auto-generated"
    }

---

Relationship Labels

erDiagram
    CUSTOMER ||--o{ ORDER : "places"
    ORDER ||--|{ LINE_ITEM : "contains"
    PRODUCT ||--o{ LINE_ITEM : "appears in"
    EMPLOYEE ||--o{ ORDER : "processes"

---

Example: E-Commerce Schema

erDiagram
    USER ||--o{ ORDER : places
    USER ||--o{ ADDRESS : has
    USER ||--o{ CART : has
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER ||--o| SHIPPING : "shipped via"
    ORDER }o--|| ADDRESS : "ships to"
    PRODUCT ||--o{ ORDER_ITEM : "ordered as"
    PRODUCT ||--o{ CART_ITEM : "added to"
    PRODUCT }o--|| CATEGORY : "belongs to"
    CART ||--|{ CART_ITEM : contains

    USER {
        uuid id PK
        string email UK
        string password_hash
        string name
        boolean is_active
        timestamp created_at
        timestamp updated_at
    }

    ADDRESS {
        uuid id PK
        uuid user_id FK
        string street
        string city
        string state
        string postal_code
        string country
        boolean is_default
    }

    PRODUCT {
        uuid id PK
        uuid category_id FK
        string sku UK
        string name
        text description
        decimal price
        integer stock_quantity
        boolean is_active
    }

    CATEGORY {
        uuid id PK
        uuid parent_id FK
        string name
        string slug UK
    }

    ORDER {
        uuid id PK
        uuid user_id FK
        uuid shipping_address_id FK
        string status
        decimal subtotal
        decimal tax
        decimal shipping_cost
        decimal total
        timestamp created_at
    }

    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        integer quantity
        decimal unit_price
        decimal subtotal
    }

    CART {
        uuid id PK
        uuid user_id FK UK
        timestamp updated_at
    }

    CART_ITEM {
        uuid id PK
        uuid cart_id FK
        uuid product_id FK
        integer quantity
    }

    SHIPPING {
        uuid id PK
        uuid order_id FK UK
        string carrier
        string tracking_number
        string status
        timestamp shipped_at
        timestamp delivered_at
    }

---

Example: Multi-Tenant SaaS

erDiagram
    ORGANIZATION ||--|{ TEAM : has
    ORGANIZATION ||--|{ USER_ORG : members
    USER ||--|{ USER_ORG : "belongs to"
    TEAM ||--|{ TEAM_MEMBER : members
    USER ||--|{ TEAM_MEMBER : "member of"
    ORGANIZATION ||--|{ PROJECT : owns
    PROJECT ||--|{ TASK : contains
    USER ||--o{ TASK : "assigned to"

    ORGANIZATION {
        uuid id PK
        string name
        string slug UK
        string plan
        timestamp created_at
    }

    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }

    USER_ORG {
        uuid id PK
        uuid user_id FK
        uuid org_id FK
        string role
    }

    TEAM {
        uuid id PK
        uuid org_id FK
        string name
    }

    TEAM_MEMBER {
        uuid id PK
        uuid team_id FK
        uuid user_id FK
        string role
    }

    PROJECT {
        uuid id PK
        uuid org_id FK
        string name
        string status
    }

    TASK {
        uuid id PK
        uuid project_id FK
        uuid assignee_id FK
        string title
        string status
        timestamp due_date
    }

Data Charts & Timelines

Mermaid supports various chart types for data visualization, project planning, and chronological representation.

---

Gantt Charts

Project scheduling and timeline visualization.

Basic Syntax

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Phase 1
    Task A           :a1, 2024-01-01, 30d
    Task B           :a2, after a1, 20d

    section Phase 2
    Task C           :2024-02-15, 15d

---

Configuration

Date Formats

Axis Format

Control how dates appear on the axis:

gantt
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    title Sprint Timeline

    section Sprint 1
    Task A : 2024-01-01, 14d

Common format codes:

• %Y - Year (2024)
• %m - Month (01-12)
• %b - Month abbr (Jan)
• %d - Day (01-31)
• %a - Weekday abbr (Mon)

---

Task Syntax

Task name : [tags], [id], [start], [end/duration]

Task Tags

gantt
    dateFormat YYYY-MM-DD

    section Tasks
    Completed task    :done, t1, 2024-01-01, 7d
    Active task       :active, t2, after t1, 7d
    Critical task     :crit, t3, after t2, 5d
    Future task       :t4, after t3, 7d
    Milestone         :milestone, m1, after t4, 0d

Dependencies

gantt
    dateFormat YYYY-MM-DD

    Task 1 :a, 2024-01-01, 7d
    Task 2 :b, after a, 5d
    Task 3 :c, after a b, 3d

---

Excluding Days

gantt
    dateFormat YYYY-MM-DD
    excludes weekends
    excludes 2024-12-25, 2024-12-26

    section Development
    Coding : 2024-12-16, 14d

Options:

• weekends - Exclude Sat/Sun
• Specific dates - 2024-12-25
• Weekdays - monday, tuesday, etc.

---

Sections

Group related tasks:

gantt
    title Product Launch
    dateFormat YYYY-MM-DD

    section Design
    Research         :des1, 2024-01-01, 14d
    Wireframes       :des2, after des1, 7d
    Mockups          :des3, after des2, 14d

    section Development
    Frontend         :dev1, after des3, 21d
    Backend          :dev2, after des3, 21d
    Integration      :dev3, after dev1 dev2, 7d

    section Launch
    Testing          :test, after dev3, 14d
    Deployment       :crit, deploy, after test, 3d
    Launch           :milestone, after deploy, 0d

---

Example: Sprint Planning

gantt
    title Sprint 15 (Jan 6-17)
    dateFormat YYYY-MM-DD
    excludes weekends

    section Backend
    API Design       :done, api, 2024-01-06, 2d
    Database Schema  :done, db, 2024-01-06, 2d
    API Implementation :active, impl, after api db, 5d
    Unit Tests       :test, after impl, 2d

    section Frontend
    Component Design :done, comp, 2024-01-06, 3d
    Implementation   :active, fe, after comp, 5d
    Integration      :int, after fe impl, 2d

    section QA
    Test Planning    :done, plan, 2024-01-06, 2d
    E2E Tests        :e2e, after int, 2d
    Bug Fixes        :crit, fix, after e2e, 1d

    section Release
    Code Review      :review, after fix, 1d
    Deploy Staging   :stage, after review, 1d
    Deploy Prod      :milestone, after stage, 0d

---

Pie Charts

Show proportional data distribution.

Basic Syntax

pie
    title Revenue by Region
    "North America" : 42
    "Europe" : 28
    "Asia Pacific" : 20
    "Other" : 10

With Data Labels

pie showData
    title Technology Stack Usage
    "JavaScript" : 45
    "Python" : 25
    "Go" : 15
    "Rust" : 10
    "Other" : 5

---

Example: Budget Allocation

pie showData
    title Q1 Budget Allocation
    "Engineering" : 45
    "Marketing" : 20
    "Sales" : 15
    "Operations" : 12
    "R&D" : 8

---

Timeline Diagrams

Chronological events and milestones.

Basic Syntax

timeline
    title Company History
    2020 : Founded
    2021 : Series A
    2022 : Product Launch
    2023 : Series B
    2024 : IPO

With Sections

timeline
    title Product Roadmap 2024

    section Q1
        January : MVP Release
                : Core Features Complete
        February : User Testing
        March : Public Beta

    section Q2
        April : Mobile App Beta
        May : API v2 Launch
        June : Enterprise Features

    section Q3
        July : International Expansion
        August : Partner Integrations
        September : Platform 2.0

    section Q4
        October : AI Features
        November : Analytics Dashboard
        December : Annual Review

---

Example: Project Milestones

timeline
    title Project Phoenix Timeline

    section Discovery
        Week 1-2 : Requirements Gathering
                 : Stakeholder Interviews
                 : Technical Assessment

    section Design
        Week 3-4 : Architecture Design
                 : API Specifications
                 : UI/UX Mockups

    section Development
        Week 5-8 : Sprint 1 - Core Features
        Week 9-12 : Sprint 2 - Advanced Features
        Week 13-14 : Integration & Testing

    section Launch
        Week 15 : Staging Deployment
               : UAT
        Week 16 : Production Release
               : Go-Live Support

---

Quadrant Charts

Four-quadrant analysis (effort/impact, priority matrices).

Basic Syntax

quadrantChart
    title Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Quick Wins
    quadrant-2 Major Projects
    quadrant-3 Fill-ins
    quadrant-4 Thankless Tasks

    Feature A: [0.3, 0.8]
    Feature B: [0.8, 0.9]
    Feature C: [0.2, 0.2]
    Feature D: [0.7, 0.3]

Configuration

• Coordinates: [x, y] where both are 0-1
• Quadrant 1: Upper-right
• Quadrant 2: Upper-left
• Quadrant 3: Lower-left
• Quadrant 4: Lower-right

---

Example: Technology Evaluation

quadrantChart
    title Technology Evaluation
    x-axis Low Risk --> High Risk
    y-axis Low Value --> High Value
    quadrant-1 Adopt Now
    quadrant-2 Evaluate Carefully
    quadrant-3 Avoid
    quadrant-4 Reassess

    Kubernetes: [0.3, 0.9]
    Serverless: [0.4, 0.8]
    GraphQL: [0.5, 0.7]
    Blockchain: [0.9, 0.4]
    AI/ML: [0.6, 0.85]
    Legacy Rewrite: [0.8, 0.5]

---

XY Charts

Line and bar charts for data trends.

Basic Syntax

xychart-beta
    title "Monthly Sales"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Revenue ($K)" 0 --> 100

    bar [52, 58, 63, 71, 82, 95]

Line Chart

xychart-beta
    title "User Growth"
    x-axis [Q1, Q2, Q3, Q4]
    y-axis "Users (thousands)" 0 --> 500

    line [100, 180, 290, 450]

Combined

xychart-beta
    title "Revenue vs Costs"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Amount ($K)" 0 --> 150

    bar "Revenue" [80, 95, 105, 120, 135, 150]
    line "Costs" [60, 65, 70, 75, 80, 85]

---

Sankey Diagrams

Flow and allocation visualization.

Basic Syntax

sankey-beta

Website, Signup, 100
Website, Bounce, 300
Signup, Trial, 80
Signup, Immediate Purchase, 20
Trial, Conversion, 40
Trial, Churn, 40

Example: Budget Flow

sankey-beta

Revenue, Engineering, 450
Revenue, Marketing, 200
Revenue, Sales, 150
Revenue, Operations, 120
Revenue, R&D, 80

Engineering, Salaries, 350
Engineering, Tools, 50
Engineering, Cloud, 50

Marketing, Digital, 120
Marketing, Events, 50
Marketing, Content, 30

---

Example: User Journey Flow

sankey-beta

Homepage, Products, 450
Homepage, About, 100
Homepage, Bounce, 450

Products, Cart, 200
Products, Exit, 250

Cart, Checkout, 150
Cart, Abandon, 50

Checkout, Purchase, 120
Checkout, Fail, 30

---

Treemap Diagrams

Hierarchical data with area representation.

Basic Syntax

treemap-beta

"Category A"
    "Item A1": 10
    "Item A2": 20

"Category B"
    "Item B1": 15
    "Item B2": 25

Example: Codebase Size

treemap-beta

"src"
    "components": 45
    "pages": 30
    "utils": 15
    "hooks": 10

"tests"
    "unit": 20
    "integration": 15
    "e2e": 10

"docs"
    "api": 8
    "guides": 12

---

Mindmaps

Hierarchical brainstorming and concept mapping.

Basic Syntax

mindmap
    root((Project))
        Frontend
            React
            TypeScript
            Tailwind
        Backend
            Node.js
            PostgreSQL
            Redis
        Infrastructure
            AWS
            Docker
            Kubernetes

Node Shapes

mindmap
    root((Circle))
        Square[Square]
        Rounded(Rounded)
        Bang))Bang((
        Cloud)Cloud(
        Hexagon{{Hexagon}}

---

Example: Architecture Decision

mindmap
    root((System Design))
        Frontend
            Framework
                React
                Vue
                Svelte
            State
                Redux
                Zustand
                Context
            Styling
                Tailwind
                CSS Modules
        Backend
            Language
                Node.js
                Go
                Python
            Database
                PostgreSQL
                MongoDB
                Redis
            API
                REST
                GraphQL
                gRPC
        Infrastructure
            Cloud
                AWS
                GCP
                Azure
            Containers
                Docker
                Kubernetes
            CI/CD
                GitHub Actions
                GitLab CI

---

Git Graphs

Branch and merge visualization.

Basic Syntax

gitGraph
    commit id: "Initial commit"
    branch develop
    checkout develop
    commit id: "Add feature A"
    commit id: "Add feature B"
    checkout main
    merge develop id: "Merge develop"
    commit id: "Hotfix"

Advanced Features

gitGraph
    commit id: "v1.0.0" tag: "v1.0.0"
    branch feature/auth
    checkout feature/auth
    commit id: "Add login"
    commit id: "Add logout"
    checkout main
    branch feature/api
    checkout feature/api
    commit id: "Add endpoints"
    checkout main
    merge feature/auth id: "Merge auth"
    merge feature/api id: "Merge api"
    commit id: "v1.1.0" tag: "v1.1.0"

Types

• commit - Normal commit
• commit type: HIGHLIGHT - Highlighted
• commit type: REVERSE - Reversed

---

Example: Git Flow

gitGraph
    commit id: "Init"

    branch develop
    checkout develop
    commit id: "Setup"

    branch feature/login
    checkout feature/login
    commit id: "Login UI"
    commit id: "Login API"
    checkout develop
    merge feature/login

    branch feature/dashboard
    checkout feature/dashboard
    commit id: "Dashboard"
    checkout develop
    merge feature/dashboard

    branch release/1.0
    checkout release/1.0
    commit id: "Bump version"
    checkout main
    merge release/1.0 tag: "v1.0.0"
    checkout develop
    merge release/1.0

    checkout main
    branch hotfix/1.0.1
    commit id: "Fix bug"
    checkout main
    merge hotfix/1.0.1 tag: "v1.0.1"
    checkout develop
    merge hotfix/1.0.1

Flowchart Diagrams

Flowcharts visualize processes, algorithms, and decision flows using nodes and edges.

---

Basic Syntax

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

---

Direction

flowchart TB
    A --> B --> C

---

Node Shapes

Standard Shapes

A[Rectangle]         Default box
B(Rounded)           Rounded corners
C([Stadium])         Pill shape
D[[Subroutine]]      Double vertical lines
E[(Database)]        Cylinder
F((Circle))          Circle
G{Diamond}           Decision/rhombus
H{{Hexagon}}         Hexagon
I[/Parallelogram/]   Slanted right
J[\Parallelogram\]   Slanted left
K[/Trapezoid\]       Trapezoid
L[\Trapezoid/]       Inverted trapezoid
M(((Double Circle))) Double circle

Extended Shapes (v11.3+)

New syntax using @{ shape: name }:

flowchart LR
    doc@{ shape: doc, label: "Document" }
    db@{ shape: cyl, label: "Database" }
    proc@{ shape: rect, label: "Process" }
    dec@{ shape: diamond, label: "Decision" }

Available extended shapes:

---

Edge Types

Basic Edges

A --> B       Solid arrow
A --- B       Solid line (no arrow)
A -.-> B      Dotted arrow
A -.- B       Dotted line
A ==> B       Thick arrow
A === B       Thick line

Arrow Ends

A --o B       Circle end
A --x B       Cross end
A o--o B      Circle both ends
A x--x B      Cross both ends
A <--> B      Arrows both ends

Edge Labels

flowchart LR
    A --> |label| B
    C -- text --> D
    E -->|"multi word"| F

Edge Length

Control edge length with extra dashes:

A --> B        Normal
A ---> B       Longer
A ----> B      Even longer

Edge IDs and Animation (v11+)

flowchart LR
    A e1@--> B e2@--> C
    e1@{ animate: true }
    e2@{ animate: true, animation-duration: "0.5s" }

---

Subgraphs

Group related nodes:

flowchart TB
    subgraph Frontend
        UI[React App]
        State[Redux Store]
    end

    subgraph Backend
        API[REST API]
        WS[WebSocket]
    end

    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI --> API
    UI --> WS
    API --> DB
    API --> Cache

Nested Subgraphs

flowchart TB
    subgraph Cloud
        subgraph VPC
            subgraph Public
                LB[Load Balancer]
            end
            subgraph Private
                App[App Server]
                DB[(Database)]
            end
        end
    end

    LB --> App --> DB

Subgraph Direction

flowchart LR
    subgraph TOP
        direction TB
        A --> B
    end
    subgraph BOTTOM
        direction TB
        C --> D
    end
    TOP --> BOTTOM

---

Multi-Target Edges

Connect multiple nodes:

flowchart LR
    A --> B & C --> D
    E & F --> G

---

Markdown in Labels

Use backticks for markdown:

flowchart LR
    A["`**Bold** and *italic*`"]
    B["`Multi
    line
    text`"]
    A --> B

---

Icons

FontAwesome icons (when enabled):

flowchart LR
    A[fa:fa-user User] --> B[fa:fa-database Database]
    B --> C[fa:fa-cog Settings]

---

Click Events

Links

flowchart LR
    A[GitHub] --> B[Docs]
    click A href "https://github.com" _blank
    click B href "https://docs.example.com"

Callbacks

flowchart LR
    A[Click Me] --> B
    click A call callback()

---

Styling

Inline Styles

flowchart LR
    A[Start]:::green --> B[Process]:::blue --> C[End]:::green

    classDef green fill:#10b981,stroke:#059669,color:white
    classDef blue fill:#3b82f6,stroke:#2563eb,color:white

Individual Node Style

flowchart LR
    A --> B --> C
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333

Link Styles

flowchart LR
    A --> B --> C
    linkStyle 0 stroke:red,stroke-width:2px
    linkStyle 1 stroke:blue,stroke-width:2px,stroke-dasharray:5

Default Styles

flowchart LR
    A --> B --> C
    linkStyle default stroke:gray,stroke-width:1px

---

Layout Engine

Use ELK for complex diagrams (v9.4+):

%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart TB
    A --> B & C & D
    B & C & D --> E

---

Examples

Microservices Architecture

flowchart LR
    subgraph Client
        Web[Web App]
        Mobile[Mobile App]
    end

    subgraph Gateway
        Kong[API Gateway]
        Auth[Auth Service]
    end

    subgraph Services
        Users[Users Service]
        Orders[Orders Service]
        Products[Products Service]
        Payments[Payments Service]
    end

    subgraph Data
        UsersDB[(Users DB)]
        OrdersDB[(Orders DB)]
        ProductsDB[(Products DB)]
        MQ[Message Queue]
    end

    Web & Mobile --> Kong
    Kong --> Auth
    Auth --> Users
    Kong --> Orders & Products & Payments
    Users --> UsersDB
    Orders --> OrdersDB
    Products --> ProductsDB
    Orders --> MQ
    Payments --> MQ

CI/CD Pipeline

flowchart LR
    subgraph Source
        Git[Git Push]
    end

    subgraph Build
        Lint[Lint]
        Test[Test]
        Build[Build]
    end

    subgraph Deploy
        Staging[Staging]
        Prod[Production]
    end

    Git --> Lint --> Test --> Build
    Build --> Staging
    Staging -->|approved| Prod

    style Prod fill:#10b981

Decision Tree

flowchart TD
    Start[User Request] --> Auth{Authenticated?}
    Auth -->|Yes| Perm{Has Permission?}
    Auth -->|No| Login[Redirect to Login]
    Perm -->|Yes| Process[Process Request]
    Perm -->|No| Denied[403 Forbidden]
    Process --> Success[200 OK]

    style Success fill:#10b981
    style Denied fill:#ef4444
    style Login fill:#f59e0b

Data Flow

flowchart LR
    Input[(Raw Data)] --> Transform[ETL Process]
    Transform --> Validate{Valid?}
    Validate -->|Yes| Store[(Data Warehouse)]
    Validate -->|No| Error[Error Queue]
    Store --> Analytics[Analytics Engine]
    Analytics --> Dashboard[Dashboard]
    Analytics --> Reports[Reports]

Sequence Diagrams

Sequence diagrams show interactions between participants over time. Ideal for API flows, protocols, and service communication.

---

Basic Syntax

sequenceDiagram
    Alice->>Bob: Hello Bob
    Bob-->>Alice: Hi Alice

---

Participants

Implicit Declaration

Participants appear in order of first message:

sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response

Explicit Declaration

Control order and add aliases:

sequenceDiagram
    participant C as Client
    participant A as API Gateway
    participant S as Service
    participant D as Database

    C->>A: Request
    A->>S: Forward
    S->>D: Query

Actors (Stick Figures)

sequenceDiagram
    actor User
    participant App as Application
    participant DB as Database

    User->>App: Login
    App->>DB: Validate

Create and Destroy

sequenceDiagram
    Alice->>Bob: Hello
    create participant Carl
    Alice->>Carl: Hi Carl
    destroy Carl
    Carl->>Alice: Goodbye

---

Message Types

sequenceDiagram
    A->>B: Sync request
    B-->>A: Response
    A-)C: Async message
    C--x A: Failed

---

Activation (Lifeline)

Show when participant is active:

Manual Activation

sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Results
    Server-->>-Client: Response

Explicit Activate/Deactivate

sequenceDiagram
    Client->>Server: Request
    activate Server
    Server->>Database: Query
    activate Database
    Database-->>Server: Results
    deactivate Database
    Server-->>Client: Response
    deactivate Server

Nested Activation

sequenceDiagram
    Client->>+Server: Request
    Server->>+Server: Validate
    Server-->>-Server: Valid
    Server->>+DB: Query
    DB-->>-Server: Data
    Server-->>-Client: Response

---

Control Flow

Alt (If/Else)

sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials

    alt Valid credentials
        API-->>Client: 200 OK + Token
    else Invalid credentials
        API-->>Client: 401 Unauthorized
    end

Opt (Optional)

sequenceDiagram
    Client->>API: Request
    API-->>Client: Response

    opt Cache result
        API->>Cache: Store response
    end

Loop

sequenceDiagram
    loop Every 30 seconds
        Client->>Server: Heartbeat
        Server-->>Client: ACK
    end

Par (Parallel)

sequenceDiagram
    par Fetch user data
        API->>UserService: Get user
    and Fetch orders
        API->>OrderService: Get orders
    and Fetch products
        API->>ProductService: Get products
    end
    API-->>Client: Aggregated response

Critical Section

sequenceDiagram
    critical Establish connection
        Client->>Server: Connect
    option Network timeout
        Client->>Client: Retry
    option Server unavailable
        Client->>Client: Use fallback
    end

Break (Early Exit)

sequenceDiagram
    Client->>API: Request
    API->>Auth: Validate token

    break Invalid token
        Auth-->>API: Invalid
        API-->>Client: 401 Unauthorized
    end

    API->>Service: Process
    Service-->>API: Result
    API-->>Client: 200 OK

---

Notes

Position

sequenceDiagram
    participant A
    participant B

    Note left of A: Left note
    Note right of B: Right note
    Note over A: Over single
    Note over A,B: Spanning note

With Messages

sequenceDiagram
    Client->>+API: POST /orders
    Note right of API: Validate request
    API->>DB: Insert order
    Note over API,DB: Transaction
    DB-->>API: Order ID
    API-->>-Client: 201 Created

---

Autonumbering

sequenceDiagram
    autonumber
    Client->>API: Login
    API->>Auth: Validate
    Auth-->>API: Token
    API-->>Client: Success

---

Background Highlighting

sequenceDiagram
    rect rgb(200, 220, 255)
        Note over Client,API: Authentication
        Client->>API: Login
        API-->>Client: Token
    end

    rect rgb(220, 255, 200)
        Note over Client,API: Data fetch
        Client->>API: Get data
        API-->>Client: Data
    end

---

Participant Boxes

Group participants visually:

sequenceDiagram
    box Blue Frontend
        participant U as User
        participant C as Client
    end
    box Green Backend
        participant A as API
        participant D as Database
    end

    U->>C: Click
    C->>A: Request
    A->>D: Query
    D-->>A: Data
    A-->>C: Response
    C-->>U: Display

---

Examples

OAuth 2.0 Authorization Code Flow

sequenceDiagram
    autonumber
    actor User
    participant Client as Client App
    participant Auth as Auth Server
    participant API as Resource API

    User->>Client: Click Login
    Client->>Auth: Authorization request
    Auth->>User: Login page
    User->>Auth: Credentials
    Auth-->>Client: Authorization code

    Client->>+Auth: Exchange code for token
    Note right of Auth: Validate code
    Auth-->>-Client: Access + Refresh tokens

    Client->>+API: Request + Access token
    API->>API: Validate token
    API-->>-Client: Protected resource
    Client-->>User: Display data

WebSocket Connection

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: HTTP Upgrade request
    S-->>C: 101 Switching Protocols

    rect rgb(230, 245, 255)
        Note over C,S: WebSocket connection established
        loop Bidirectional messaging
            C-)S: Send message
            S-)C: Push update
        end
    end

    C->>S: Close frame
    S-->>C: Close ACK

Retry with Exponential Backoff

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Request
    S--xC: 503 Service Unavailable

    loop Retry with backoff
        Note right of C: Wait 1s, 2s, 4s...
        C->>S: Retry request
        alt Success
            S-->>C: 200 OK
        else Still failing
            S--xC: 503
        end
    end

Saga Pattern (Distributed Transaction)

sequenceDiagram
    autonumber
    participant O as Order Service
    participant P as Payment Service
    participant I as Inventory Service
    participant S as Shipping Service

    O->>P: Reserve payment
    P-->>O: Payment reserved

    O->>I: Reserve inventory
    I-->>O: Inventory reserved

    O->>S: Schedule shipping
    S--xO: Shipping failed

    rect rgb(255, 220, 220)
        Note over O,S: Compensating transactions
        O->>I: Release inventory
        I-->>O: Released
        O->>P: Refund payment
        P-->>O: Refunded
    end

gRPC Streaming

sequenceDiagram
    participant C as Client
    participant S as Server

    Note over C,S: Unary RPC
    C->>S: Request
    S-->>C: Response

    Note over C,S: Server streaming
    C->>S: Request
    loop Stream responses
        S-)C: Response chunk
    end

    Note over C,S: Client streaming
    loop Stream requests
        C-)S: Request chunk
    end
    S-->>C: Final response

    Note over C,S: Bidirectional streaming
    par Client sends
        loop
            C-)S: Request
        end
    and Server sends
        loop
            S-)C: Response
        end
    end

State & User Journey Diagrams

State diagrams model state machines and lifecycles. User journey diagrams map user experiences across tasks.

---

State Diagrams

Basic Syntax

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Complete : finish
    Complete --> [*]

---

States

Simple States

stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Published
    Published --> [*]

State with Description

stateDiagram-v2
    state "Waiting for Payment" as WaitPay
    state "Processing Order" as Process

    [*] --> WaitPay
    WaitPay --> Process : payment_received
    Process --> [*]

---

Transitions

Basic Transitions

stateDiagram-v2
    A --> B
    B --> C : event
    C --> D : event [guard]
    D --> E : event / action

Self-Transitions

stateDiagram-v2
    Processing --> Processing : retry

---

Composite States

Nested states for complex behaviors:

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Working : start
        Working --> Idle : stop
    }

    Active --> Suspended : suspend
    Suspended --> Active : resume
    Active --> [*] : terminate

Deeply Nested

stateDiagram-v2
    [*] --> First

    state First {
        [*] --> Second

        state Second {
            [*] --> Third
            Third --> Third : loop
        }
    }

---

Choice (Decision Points)

stateDiagram-v2
    state check <<choice>>

    [*] --> Validate
    Validate --> check
    check --> Success : valid
    check --> Failure : invalid
    Success --> [*]
    Failure --> [*]

---

Fork and Join (Parallel States)

stateDiagram-v2
    state fork_state <<fork>>
    state join_state <<join>>

    [*] --> fork_state
    fork_state --> TaskA
    fork_state --> TaskB
    fork_state --> TaskC
    TaskA --> join_state
    TaskB --> join_state
    TaskC --> join_state
    join_state --> Complete
    Complete --> [*]

---

Concurrent States

States that execute in parallel:

stateDiagram-v2
    state Processing {
        [*] --> Validating
        Validating --> Valid
        --
        [*] --> Calculating
        Calculating --> Calculated
    }

---

Notes

stateDiagram-v2
    [*] --> Active
    Active --> Inactive

    note right of Active
        User is currently logged in
        and has an active session
    end note

    note left of Inactive : Session expired

---

Direction

Control layout direction:

stateDiagram-v2
    direction LR
    [*] --> A
    A --> B
    B --> C
    C --> [*]

Options: TB, BT, LR, RL

---

Styling

stateDiagram-v2
    [*] --> Active
    Active --> Error
    Error --> [*]

    classDef errorState fill:#ff0000,color:white
    class Error errorState

---

Example: Order Lifecycle

stateDiagram-v2
    [*] --> Draft

    Draft --> PendingPayment : checkout
    PendingPayment --> PaymentFailed : payment_failed
    PendingPayment --> Confirmed : payment_success
    PaymentFailed --> Draft : retry
    PaymentFailed --> Cancelled : abandon

    Confirmed --> Processing : start_fulfillment

    state Processing {
        [*] --> Picking
        Picking --> Packing : items_picked
        Packing --> ReadyToShip : packed
    }

    Processing --> Shipped : ship
    Shipped --> Delivered : delivery_confirmed
    Delivered --> [*]

    Draft --> Cancelled : cancel
    PendingPayment --> Cancelled : cancel
    Confirmed --> Cancelled : cancel
    Cancelled --> [*]

---

Example: Connection State Machine

stateDiagram-v2
    [*] --> Disconnected

    Disconnected --> Connecting : connect()
    Connecting --> Connected : connection_established
    Connecting --> Disconnected : connection_failed

    state Connected {
        [*] --> Idle
        Idle --> Sending : send()
        Sending --> Idle : send_complete
        Idle --> Receiving : data_received
        Receiving --> Idle : receive_complete
    }

    Connected --> Reconnecting : connection_lost
    Reconnecting --> Connected : reconnected
    Reconnecting --> Disconnected : max_retries_exceeded

    Connected --> Disconnecting : disconnect()
    Disconnecting --> Disconnected : disconnected

---

Example: Authentication Flow

stateDiagram-v2
    [*] --> Unauthenticated

    state Unauthenticated {
        [*] --> LoginForm
        LoginForm --> Validating : submit
        Validating --> LoginForm : invalid_credentials
    }

    Unauthenticated --> MFA : credentials_valid

    state MFA {
        [*] --> AwaitingCode
        AwaitingCode --> VerifyingCode : submit_code
        VerifyingCode --> AwaitingCode : code_invalid
    }

    MFA --> Authenticated : mfa_verified

    state Authenticated {
        [*] --> Active
        Active --> SessionWarning : approaching_timeout
        SessionWarning --> Active : user_activity
    }

    Authenticated --> Unauthenticated : logout
    Authenticated --> Unauthenticated : session_expired

---

User Journey Diagrams

Basic Syntax

journey
    title My Working Day
    section Morning
        Wake up: 5: Me
        Shower: 3: Me
        Breakfast: 4: Me, Family
    section Work
        Commute: 2: Me
        Meetings: 3: Me, Team
        Coding: 5: Me
    section Evening
        Dinner: 4: Me, Family
        Relax: 5: Me

---

Structure

Title

journey
    title User Onboarding Experience

Sections

Group related tasks:

journey
    title E-commerce Checkout
    section Discovery
        Browse products: 5: Customer
    section Selection
        Add to cart: 4: Customer
    section Checkout
        Enter payment: 3: Customer
    section Completion
        Receive confirmation: 5: Customer

Tasks

Format: Task name: score: actor1, actor2, ...

• Score: 1-5 (1 = negative, 5 = positive)
• Actors: Participants involved

---

Example: SaaS Onboarding

journey
    title SaaS Product Onboarding
    section Awareness
        See ad: 4: Prospect
        Visit website: 4: Prospect
        Read features: 3: Prospect
    section Signup
        Click signup: 5: Prospect
        Fill form: 2: Prospect
        Verify email: 3: User
    section First Use
        Complete tutorial: 4: User
        Create first project: 5: User
        Invite team member: 3: User
    section Conversion
        Hit free tier limit: 2: User
        View pricing: 3: User
        Enter payment: 2: User
        Upgrade complete: 5: Customer

---

Example: Support Ticket Journey

journey
    title Customer Support Experience
    section Issue Discovery
        Encounter problem: 1: Customer
        Search help docs: 3: Customer
        Cannot find solution: 2: Customer
    section Contact Support
        Find contact form: 3: Customer
        Describe issue: 4: Customer
        Submit ticket: 4: Customer
    section Resolution
        Receive acknowledgment: 4: Customer, Support
        First response: 5: Customer, Support
        Follow-up questions: 3: Customer, Support
        Issue resolved: 5: Customer, Support
    section Post-Resolution
        Receive survey: 3: Customer
        Leave feedback: 4: Customer

---

Example: Mobile App First Launch

journey
    title Mobile App First Launch Experience
    section Download
        Discover app: 4: User
        Read reviews: 4: User
        Download app: 5: User
    section Onboarding
        Open app: 5: User
        View splash screen: 3: User
        Skip/watch intro: 4: User
        Grant permissions: 2: User
    section Account Setup
        Choose signup method: 4: User
        Complete profile: 3: User
        Set preferences: 4: User
    section First Session
        View main screen: 5: User
        Complete first action: 5: User
        Receive achievement: 5: User
    section Retention
        Receive push notification: 3: User
        Return next day: 4: User

---

Use Cases

When to Use User Journey

1. UX Research - Map current user experience 2. Identify Pain Points - Find low-score areas 3. Design Improvements - Plan better experiences 4. Stakeholder Communication - Visualize user perspective 5. Service Design - Map multi-touchpoint experiences

Tips

• Keep scores realistic (not all 5s)
• Include multiple actors when relevant
• Use sections to group related activities
• Focus on emotional experience, not just tasks
• Identify opportunities at low-score points