mermaid-diagram-specialist

What this skill does

# Mermaid Diagram Specialist

## Overview

**Purpose**: Expert in creating comprehensive Mermaid diagrams for
documentation, architecture visualization, and process mapping

**Category**: Tech **Primary Users**: tech-writer, architecture-validator,
product-technical, tech-lead

## When to Use This Skill

- Creating architecture documentation
- Visualizing workflows and processes
- Documenting data models (ERDs)
- Explaining sequence flows
- Creating state machines
- Documenting component relationships
- Creating decision trees
- Visualizing user journeys

## Prerequisites

**Required:**

- Understanding of the system/process to document
- Access to technical specifications
- Knowledge of diagram type needed

**Optional:**

- Design system colors for consistency
- Existing documentation to reference

## Input

**What the skill needs:**

- Process/system description
- Entities and relationships (for ERDs)
- Component interactions (for sequence diagrams)
- Architecture layers (for C4 diagrams)
- States and transitions (for state diagrams)

## Workflow

### Step 1: Diagram Type Selection

**Objective**: Choose appropriate diagram type for requirements

**Available Diagram Types:**

1. **Flowchart**: Decision flows, algorithms, processes
2. **Sequence Diagram**: API interactions, message flows
3. **ERD**: Database schemas, entity relationships
4. **Class Diagram**: Object-oriented design
5. **State Diagram**: State machines, lifecycle
6. **Gantt Chart**: Project timelines, schedules
7. **C4 Diagram**: Architecture at different levels
8. **Pie/Bar Charts**: Data visualization
9. **Git Graph**: Version control flows
10. **User Journey**: User experience flows

**Decision Matrix:**

- Process with decisions → **Flowchart**
- API/system interactions → **Sequence Diagram**
- Database structure → **ERD**
- System architecture → **C4 Diagram**
- Object relationships → **Class Diagram**
- State transitions → **State Diagram**
- Project timeline → **Gantt Chart**

**Validation:**

- [ ] Diagram type matches content
- [ ] Complexity appropriate
- [ ] Audience considered
- [ ] Purpose clear

**Output**: Selected diagram type

### Step 2: Flowchart Creation

**Objective**: Create process and decision flow diagrams

**Syntax:**

```mermaid
flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success[/Success Response/]
    Success --> End([End])
```

**Node Shapes:**

- `[Rectangle]` - Process step
- `([Rounded])` - Start/End
- `{Diamond}` - Decision
- `[/Parallelogram/]` - Input/Output
- `[(Database)]` - Data storage
- `((Circle))` - Connector

**Direction Options:**

- `TD` - Top to Down
- `LR` - Left to Right
- `BT` - Bottom to Top
- `RL` - Right to Left

**Example - Booking Flow:**

```mermaid
flowchart TD
    Start([User Initiates Booking]) --> CheckDates[Check Date Availability]
    CheckDates --> Available{Dates Available?}
    Available -->|No| ShowError[/Show Unavailable Message/]
    ShowError --> End([End])
    Available -->|Yes| CreateBooking[Create Pending Booking]
    CreateBooking --> Payment[Process Payment]
    Payment --> PaymentSuccess{Payment Success?}
    PaymentSuccess -->|No| CancelBooking[Cancel Booking]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[Confirm Booking]
    ConfirmBooking --> SendEmail[/Send Confirmation Email/]
    SendEmail --> SaveDB[(Save to Database)]
    SaveDB --> Success[/Show Success/]
    Success --> End
```

**Validation:**

- [ ] All paths covered
- [ ] Decision points clear
- [ ] Start and end defined
- [ ] Flow direction logical

**Output**: Process flowchart

### Step 3: Sequence Diagram Creation

**Objective**: Document API interactions and message flows

**Syntax:**

```mermaid
sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB
    participant Payment

    User->>Frontend: Click "Book"
    Frontend->>API: POST /api/bookings
    API->>DB: Check availability
    DB-->>API: Available
    API->>Payment: Process payment
    Payment-->>API: Payment successful
    API->>DB: Create booking
    DB-->>API: Booking created
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation
```

**Participant Types:**

- `actor` - Human user
- `participant` - System/Service
- `database` - Database

**Arrow Types:**

- `->` - Solid line (synchronous)
- `-->` - Dotted line (response)
- `->>` - Solid arrow (async message)
- `-->>` - Dotted arrow (async response)

**Example - Authentication Flow:**

```mermaid
sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Clerk
    participant DB

    User->>Frontend: Enter credentials
    Frontend->>Clerk: Login request
    Clerk->>Clerk: Validate credentials
    alt Credentials valid
        Clerk-->>Frontend: JWT token
        Frontend->>API: Request with token
        API->>Clerk: Verify token
        Clerk-->>API: Token valid
        API->>DB: Fetch user data
        DB-->>API: User data
        API-->>Frontend: User session
        Frontend-->>User: Logged in
    else Credentials invalid
        Clerk-->>Frontend: Auth error
        Frontend-->>User: Show error
    end
```

**Validation:**

- [ ] All participants identified
- [ ] Message flow logical
- [ ] Return messages shown
- [ ] Alt/loop blocks used correctly

**Output**: Sequence diagram

### Step 4: ERD Creation

**Objective**: Document database schema and relationships

**Syntax:**

```mermaid
erDiagram
    USER ||--o{ BOOKING : creates
    ACCOMMODATION ||--o{ BOOKING : "booked for"
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        enum status
    }
    ACCOMMODATION {
        uuid id PK
        string name
        text description
        decimal price_per_night
    }
```

**Relationship Types:**

- `||--||` - One to one
- `||--o{` - One to many
- `}o--o{` - Many to many
- `||--o|` - One to zero or one

**Cardinality Symbols:**

- `||` - Exactly one
- `o|` - Zero or one
- `}o` - Zero or more
- `}|` - One or more

**Example - Full Hospeda ERD:**

```mermaid
erDiagram
    USER ||--o{ BOOKING : creates
    USER ||--o{ REVIEW : writes
    USER ||--o{ ACCOMMODATION : owns
    ACCOMMODATION ||--o{ BOOKING : "has bookings"
    ACCOMMODATION ||--o{ REVIEW : "has reviews"
    ACCOMMODATION }o--o{ AMENITY : includes
    BOOKING ||--|| PAYMENT : "has payment"

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

    ACCOMMODATION {
        uuid id PK
        uuid owner_id FK
        string name
        text description
        decimal price_per_night
        int max_guests
        enum status
    }

    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        int guests
        enum status
        decimal total_price
    }

    REVIEW {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        int rating
        text comment
        timestamp created_at
    }

    PAYMENT {
        uuid id PK
        uuid booking_id FK
        string mercadopago_id UK
        decimal amount
        enum status
        timestamp processed_at
    }

    AMENITY {
        uuid id PK
        string name
        string icon
    }
```

**Validation:**

- [ ] All entities defined
- [ ] Relationships accurate
- [ ] Cardinality correct
- [ ] Primary/Foreign keys marked

**Output**: ERD diagram

### Step 5: C4 Architecture Diagrams

**Objective**: Document system architecture at different levels

**Context Level** (System in environment):

```mermaid
C4Contex