---
name: mermaid
description: Generate diagrams using Mermaid syntax. Use this skill when creating architecture diagrams, sequence diagrams, ER diagrams, flowcharts, or any visual documentation in markdown files.
---

# Mermaid Diagram Skill

## When to Use This Skill

- Documenting system architecture or component relationships
- Visualizing API request/response flows
- Creating database schema diagrams from models
- Illustrating state machines or workflows
- Adding visual documentation to markdown files

## Overview

Mermaid is a JavaScript-based diagramming tool that renders markdown-like syntax into diagrams. GitHub, GitLab, and many markdown editors render Mermaid blocks natively.

**No installation required** for GitHub rendering - just use fenced code blocks with `mermaid` language identifier.

## Prerequisites

### Option 1: GitHub/GitLab (Recommended)
No setup needed. Wrap diagrams in triple backticks with `mermaid` language:

~~~markdown
```mermaid
flowchart LR
    A --> B
```
~~~

### Option 2: Mermaid CLI (Local Rendering)
```bash
npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg
```

### Option 3: VS Code Extension
Install "Markdown Preview Mermaid Support" extension for live preview.

## Flowchart Diagrams

Use for architecture, decision trees, and process flows.

### Basic Syntax
```mermaid
flowchart TD
    A[Rectangle] --> B(Rounded)
    B --> C{Diamond}
    C -->|Yes| D[Result 1]
    C -->|No| E[Result 2]
```

### Direction Options
- `TD` or `TB` - Top to bottom
- `LR` - Left to right
- `BT` - Bottom to top
- `RL` - Right to left

### Architecture Example
```mermaid
flowchart TD
    subgraph Client
        UI[React App]
    end
    subgraph Server
        API[Express API]
        Auth[Auth Service]
    end
    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI -->|HTTP| API
    API --> Auth
    API --> DB
    API --> Cache
```

## Sequence Diagrams

Use for API flows, authentication sequences, and message passing.

### Basic Syntax
```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: POST /api/users
    S->>DB: INSERT user
    DB-->>S: OK
    S-->>C: 201 Created
```

### Arrow Types
- `->>` Solid line with arrowhead
- `-->>` Dotted line with arrowhead
- `-x` Solid line with X (async)
- `--x` Dotted line with X

### With Loops and Conditionals
```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    participant Auth as Auth Service

    U->>A: Login request
    A->>Auth: Validate credentials

    alt Valid credentials
        Auth-->>A: Token
        A-->>U: 200 OK + Token
    else Invalid
        Auth-->>A: Error
        A-->>U: 401 Unauthorized
    end

    loop Every 15 minutes
        U->>A: Refresh token
        A-->>U: New token
    end
```

## ER Diagrams

Use for database schemas and entity relationships.

### Basic Syntax
```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
```

### Cardinality Notation
- `||` - Exactly one
- `o|` - Zero or one
- `}|` - One or more
- `}o` - Zero or more

### With Attributes
```mermaid
erDiagram
    USER {
        int id PK
        string email UK
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    USER ||--o{ ORDER : places
```

## Class Diagrams

Use for object models and component relationships.

### Basic Syntax
```mermaid
classDiagram
    class User {
        +int id
        +string email
        +login()
        +logout()
    }
    class Order {
        +int id
        +decimal total
        +submit()
    }
    User "1" --> "*" Order : places
```

### Relationship Types
- `<|--` Inheritance
- `*--` Composition
- `o--` Aggregation
- `-->` Association
- `..>` Dependency

## State Diagrams

Use for state machines and workflow states.

### Basic Syntax
```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Approved : approve
    Review --> Draft : reject
    Approved --> Published : publish
    Published --> [*]
```

### With Nested States
```mermaid
stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : start
        Processing --> Idle : complete
    }

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

## Best Practices

1. **Keep diagrams focused** - One concept per diagram, split complex systems into multiple diagrams
2. **Use meaningful labels** - `API` not `A`, `Database` not `DB` (unless space-constrained)
3. **Add subgraphs** for grouping related components in flowcharts
4. **Use aliases** in sequence diagrams (`participant C as Client`) for readability
5. **Include cardinality** in ER diagrams - relationships are ambiguous without it
6. **Test rendering** on GitHub before committing - some syntax varies between versions
7. **Link to details** - Diagrams show structure; link to docs for implementation details

## Reference Documentation

- **Official Docs:** https://mermaid.js.org/
- **Live Editor:** https://mermaid.live/
- **GitHub Support:** https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
- **Syntax Reference:** https://mermaid.js.org/syntax/flowchart.html
