---

name: mermaid-diagrams description: | Generate Mermaid diagrams in markdown. Triggers on: diagrams, charts, visualizations, flowcharts, sequence diagrams, architecture diagrams, ER diagrams, state machines, Gantt charts, mindmaps, C4, class diagrams, git graphs.

Use when: user asks for visual representations of code, systems, processes, data structures, database schemas, workflows, or API flows. Proactively suggest diagrams when explaining complex systems.

Mermaid Diagrams

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

Quick Start

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

Quick Decision Tree

CopyWhat 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

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

API Request Flow

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

Database Schema

CopyerDiagram
    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

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

Syntax Quick Reference

Flowchart Nodes

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

Flowchart Edges

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

Sequence Arrows

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

ER Cardinality

Copy||--||   # 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

• Live Editor: https://mermaid.live
• Docs: https://mermaid.js.org