---
name: mermaid-diagrams
description: >
  Create clear, consistent Mermaid diagrams for architecture, data flow, sequence,
  and state diagrams. Invoked during design and documentation phases. Use when any
  visual representation of system structure or behavior is needed.
---

# Mermaid Diagrams Skill

Create diagrams using Mermaid syntax that are clear, consistent, and version-control friendly.

## Diagram Types and When to Use Them

### Architecture / Component Diagram → `graph TD` or `graph LR`
Use for: System overviews, component relationships, dependency maps

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Core Service]
    D --> E[(Database)]
    D --> F[Message Queue]
    F --> G[Worker Service]
```

### Sequence Diagram → `sequenceDiagram`
Use for: API flows, request/response patterns, multi-component interactions

```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /resource
    A->>D: INSERT
    D-->>A: OK
    A-->>U: 201 Created
```

### Data Flow → `flowchart LR`
Use for: ETL pipelines, data transformation steps, processing flows

```mermaid
flowchart LR
    A[Raw Data] --> B[Validate]
    B --> C{Valid?}
    C -->|Yes| D[Transform]
    C -->|No| E[Error Log]
    D --> F[Load]
    F --> G[(Warehouse)]
```

### State Diagram → `stateDiagram-v2`
Use for: Ticket workflows, entity lifecycles, state machines

```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress: assign
    InProgress --> Review: submit
    Review --> Done: approve
    Review --> InProgress: reject
    Done --> [*]
```

### Entity Relationship → `erDiagram`
Use for: Database schemas, data models

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

## Style Guidelines

1. **Labels are mandatory.** Every node and edge should have a descriptive label.
2. **Left-to-right for flows, top-to-bottom for hierarchies.** `LR` for data/process flows, `TD` for org/component charts.
3. **Group related components** with subgraphs:
   ```mermaid
   graph TD
       subgraph Backend
           A[API] --> B[Service]
       end
       subgraph Data
           C[(DB)] --> D[Cache]
       end
       B --> C
   ```
4. **Color sparingly.** Use it to highlight boundaries (e.g., internal vs external) not for decoration.
5. **Keep it readable.** If a diagram has more than 15 nodes, split into multiple diagrams with a high-level overview linking to details.
6. **Always include a text description** below the diagram for accessibility and for contexts where Mermaid doesn't render.

## Rules

- Every design document must have at least one architecture diagram
- Every diagram must have an accompanying text description
- Diagrams are documentation — keep them updated when the system changes
- If a diagram is too complex to read, the system might be too complex to build — flag it
