tools-mermaid

What this skill does

# Mermaid Diagrams

## Overview
Mermaid is a markdown-based diagramming tool that renders in GitHub, GitLab, Notion, and documentation sites. Use this skill to create visual diagrams in markdown files.

## When to Use
- Documenting system architecture
- Visualizing API flows and sequences
- Creating database ER diagrams
- Illustrating state machines
- Project timelines and Gantt charts
- Git branch strategies

## Basic Syntax

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

## Flowcharts

### Direction
```
flowchart TB    %% Top to Bottom
flowchart BT    %% Bottom to Top
flowchart LR    %% Left to Right
flowchart RL    %% Right to Left
```

### Node Shapes
```mermaid
flowchart LR
    A[Rectangle]
    B(Rounded)
    C([Stadium])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G>Flag]
    H{Diamond}
    I{{Hexagon}}
    J[/Parallelogram/]
    K[\Parallelogram Alt\]
    L[/Trapezoid\]
```

### Connections
```mermaid
flowchart LR
    A --> B                 %% Arrow
    A --- B                 %% Line
    A -.-> B                %% Dotted arrow
    A ==> B                 %% Thick arrow
    A --text--> B           %% Arrow with text
    A -->|text| B           %% Alt text syntax
    A <--> B                %% Bidirectional
```

### Subgraphs
```mermaid
flowchart TB
    subgraph Frontend
        A[React App]
        B[Next.js]
    end
    subgraph Backend
        C[API Server]
        D[(Database)]
    end
    A --> C
    B --> C
    C --> D
```

### Styling
```mermaid
flowchart LR
    A[Start]:::green --> B[Process]:::blue --> C[End]:::red
    
    classDef green fill:#9f6,stroke:#333
    classDef blue fill:#69f,stroke:#333
    classDef red fill:#f66,stroke:#333
```

## Sequence Diagrams

### Basic Sequence
```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    
    U->>A: POST /login
    A->>D: Query user
    D-->>A: User data
    A-->>U: JWT token
```

### Arrow Types
```
->>     Solid arrow
-->>    Dotted arrow
-x      Solid cross (async)
--x     Dotted cross
-)      Open arrow
--)     Dotted open arrow
```

### Activations & Notes
```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    
    C->>+S: Request
    Note right of S: Processing...
    S-->>-C: Response
    
    Note over C,S: Connection established
```

### Loops & Conditionals
```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    
    loop Every 30s
        C->>S: Heartbeat
    end
    
    alt Success
        S-->>C: 200 OK
    else Error
        S-->>C: 500 Error
    end
    
    opt Optional Step
        C->>S: Analytics
    end
```

## Entity Relationship Diagrams

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    PRODUCT {
        int id PK
        string name
        decimal price
    }
```

### Relationship Types
```
||--||    One to one
||--o{    One to many
}o--o{    Many to many
||--|{    One to one or many
```

## State Diagrams

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Draft: Request Changes
    Review --> Approved: Approve
    Approved --> Published: Publish
    Published --> [*]
    
    state Review {
        [*] --> Pending
        Pending --> InProgress: Assign
        InProgress --> Complete: Finish
        Complete --> [*]
    }
```

### Transitions & Notes
```mermaid
stateDiagram-v2
    [*] --> Active
    Active --> Inactive: timeout
    Inactive --> Active: wake
    Active --> [*]: terminate
    
    note right of Active: Processing requests
    note left of Inactive: Sleeping
```

## Class Diagrams

```mermaid
classDiagram
    class User {
        +int id
        +string email
        +string name
        +login()
        +logout()
    }
    class Order {
        +int id
        +decimal total
        +string status
        +calculate()
        +submit()
    }
    class Product {
        +int id
        +string name
        +decimal price
    }
    
    User "1" --> "*" Order: places
    Order "*" --> "*" Product: contains
```

### Visibility & Relationships
```
+   Public
-   Private
#   Protected
~   Package

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

## Gantt Charts

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    
    section Planning
    Requirements    :a1, 2024-01-01, 7d
    Design          :a2, after a1, 5d
    
    section Development
    Backend API     :b1, after a2, 14d
    Frontend        :b2, after a2, 14d
    Integration     :b3, after b1, 7d
    
    section Testing
    QA Testing      :c1, after b3, 7d
    UAT             :c2, after c1, 5d
    
    section Launch
    Deployment      :milestone, after c2, 0d
```

## Git Graphs

```mermaid
gitGraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Feature A"
    commit id: "Feature B"
    checkout main
    merge develop id: "Release 1.0"
    branch hotfix
    commit id: "Fix bug"
    checkout main
    merge hotfix id: "Patch 1.0.1"
```

## Pie Charts

```mermaid
pie showData
    title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 10
    "Edge" : 4
    "Other" : 2
```

## Mindmaps

```mermaid
mindmap
    root((Project))
        Frontend
            React
            TypeScript
            Tailwind
        Backend
            Node.js
            PostgreSQL
            Redis
        DevOps
            Docker
            Kubernetes
            CI/CD
```

## Timeline

```mermaid
timeline
    title Product Roadmap
    section Q1
        January : Feature A : Feature B
        February : Feature C
        March : Release 1.0
    section Q2
        April : Feature D
        May : Feature E : Feature F
        June : Release 2.0
```

## Common Patterns

### API Flow
```mermaid
sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant A as Auth Service
    participant S as Service
    participant D as Database
    
    C->>G: Request + Token
    G->>A: Validate Token
    A-->>G: Valid
    G->>S: Forward Request
    S->>D: Query
    D-->>S: Data
    S-->>G: Response
    G-->>C: Response
```

### Microservices Architecture
```mermaid
flowchart TB
    subgraph Client
        Web[Web App]
        Mobile[Mobile App]
    end
    
    subgraph Gateway
        AG[API Gateway]
        LB[Load Balancer]
    end
    
    subgraph Services
        US[User Service]
        OS[Order Service]
        PS[Product Service]
        NS[Notification Service]
    end
    
    subgraph Data
        UD[(User DB)]
        OD[(Order DB)]
        PD[(Product DB)]
        MQ[Message Queue]
    end
    
    Web --> LB
    Mobile --> LB
    LB --> AG
    AG --> US & OS & PS
    US --> UD
    OS --> OD
    PS --> PD
    OS --> MQ
    MQ --> NS
```

### CI/CD Pipeline
```mermaid
flowchart LR
    subgraph Source
        GH[GitHub]
    end
    
    subgraph CI
        Build[Build]
        Test[Test]
        Lint[Lint]
    end
    
    subgraph CD
        Stage[Staging]
        Prod[Production]
    end
    
    GH -->|push| Build
    Build --> Test & Lint
    Test & Lint -->|pass| Stage
    Stage -->|approve| Prod
```

## Tips

- Use `%%` for comments
- Keep diagrams focused (split large ones)
- Test rendering in GitHub/target platform
- Use meaningful IDs for nodes
- Leverage subgraphs for organization

## Rendering

| Platform | Support |
|----------|---------|
| GitHub | ✅ Native in `.md` files |
| GitLab | ✅ Native in `.md` files |
| Notion | ✅ Cod