mermaid

What this skill does

# Mermaid Diagrams

Create professional diagrams using Mermaid syntax for documentation, design discussions, and system architecture planning. This skill covers three primary diagram types:

- **Sequence Diagrams**: Show temporal interactions and message flows between actors, services, or processes
- **Architecture Diagrams**: Visualize relationships between services and resources in cloud or CI/CD deployments
- **Flowchart Diagrams**: Illustrate processes, decision trees, algorithms, and workflow logic

## 🚀 Automatic Validation Workflow

**IMPORTANT**: All diagrams generated by this skill are automatically validated with mermaid-cli. This ensures error-free diagrams that render correctly every time.

### Mandatory Workflow Steps

When creating diagrams, ALWAYS follow this exact workflow:

1. **Generate Diagram Content** (based on user requirements)
2. **AUTOMATICALLY VALIDATE** using mermaid-cli (mandatory step)
3. **APPLY SELF-HEALING FIXES** if validation fails (automatic)
4. **CONFIRM VALIDATION SUCCESS** before presenting to user
5. **DELIVER VALIDATED DIAGRAM** to user

**NEVER skip validation or present unvalidated diagrams to users.**

## Sequence Diagrams

Sequence diagrams are interaction diagrams that show how processes operate with one another and in what order. They visualize temporal interactions between participants, making them ideal for documenting API flows, system integrations, user interactions, and distributed system communications.

### Quick Instructions

1. Define participants: Use `actor` (humans) or `participant` with type attributes
2. Add messages: `->>` (sync), `-->>` (response), `-)` (async)
3. Show activations: Append `+`/`-` to arrows (`A->>+B`, `B-->>-A`)
4. Control structures: `alt`/`else`, `loop`, `par`, `critical` for complex flows

**→ For detailed syntax, see [references/sequence-diagrams.md](references/sequence-diagrams.md)**

### 🔍 Automatic Validation Process

After generating any sequence diagram, you MUST:

1. **Create temp files:**
   ```bash
   echo "YOUR_SEQUENCE_DIAGRAM_HERE" > /tmp/mermaid_validate.mmd
   ```

2. **Run enhanced validation (your bash script approach):**
   ```bash
   mmdc -i /tmp/mermaid_validate.mmd -o /tmp/mermaid_validate.svg 2>/tmp/mermaid_validate.err
   rc=$?
   if [ $rc -ne 0 ]; then
     echo "🛑 mmdc failed (exit code $rc)."; cat /tmp/mermaid_validate.err; exit 1
   fi

   # Check SVG for error markers that mmdc might miss
   if grep -q -i 'Syntax error in graph\|mermaidError\|errorText\|Parse error' /tmp/mermaid_validate.svg; then
     echo "🛑 Mermaid syntax error found in output SVG"
     exit 1
   fi

   # Verify SVG actually contains diagram content (not just error text)
   if ! grep -q '<svg.*width.*height' /tmp/mermaid_validate.svg; then
     echo "🛑 SVG output appears invalid or empty"
     exit 1
   fi

   echo "✅ Diagram appears valid"
   ```

3. **If validation fails, apply fixes:**
   - Check participant syntax: ensure `participant` or `actor` keywords used correctly
   - Verify arrow syntax: `->>`, `-->>`, `-)` patterns are correct
   - Validate control structures: `alt`, `loop`, `par` blocks are properly closed
   - Review error details in `/tmp/mermaid_validate.err` for specific issues

4. **Re-validate until successful:** (repeat step 2)

5. **Cleanup and confirm:**
   ```bash
   rm -f /tmp/mermaid_validate.mmd /tmp/mermaid_validate.svg /tmp/mermaid_validate.err
   ```

**VALIDATION MUST PASS BEFORE PRESENTING TO USER!**

### ⚠️ CRITICAL: Key Syntax Differences

**NEVER MIX THESE SYNTAXES!** Each diagram type has completely different keywords. Mixing them will break your diagram.

**Sequence Diagrams:**
```mermaid
sequenceDiagram
    actor User
    participant API@{ "type": "control" }
    participant DB@{ "type": "database" }
```
- Use `actor` for humans (stick figure icon)
- Use `participant` with type attributes for systems
- ✓ Use: `participant`, `actor`
- ✗ NEVER use: `service`, `database`, `group`

**Architecture Diagrams:**
```mermaid
architecture-beta
    service api(server)[API]
    database db(database)[Database]
    group backend(cloud)[Backend]
```
- Use `service` for components
- Use `database` as a keyword (NOT participant!)
- Use `group` for organizing services
- ✓ Use: `service`, `database`, `group`
- ✗ NEVER use: `participant`, `actor`

### Minimal Example

```mermaid
sequenceDiagram
    actor User
    participant API@{ "type": "control" }
    participant DB@{ "type": "database" }

    User->>+API: Request data
    API->>+DB: Query
    DB-->>-API: Result
    API-->>-User: Response
```

### Guidelines

- Limit to 5-7 participants per diagram for clarity
- Use activations (`+`/`-`) to show processing periods
- Apply control structures (`alt`, `loop`, `par`) for complex flows

**→ See [references/sequence-diagrams.md](references/sequence-diagrams.md) for detailed patterns and best practices**

---

## Architecture Diagrams

Architecture diagrams show relationships between services and resources commonly found within cloud or CI/CD deployments. Services (nodes) are connected by edges, and related services can be placed within groups to illustrate organization.

### Quick Instructions

1. Start with `architecture-beta` keyword
2. Define groups: `group {id}({icon})[{label}]`
3. Add services: `service {id}({icon})[{label}] in {group}`
4. Connect edges: `{id}:{T|B|L|R} -- {T|B|L|R}:{id}`
5. Add arrows: `-->` (single) or `<-->` (bidirectional)

**CRITICAL Syntax Rules:**
- **IDs**: Use simple alphanumeric (e.g., `api`, `db1`, `auth_service`) - NO spaces or special chars
- **Labels**: AVOID special characters that break parsing:
  - ❌ NO hyphens (`Gen-AI`, `Cross-Account`)
  - ❌ NO colons (`AWS Account: prod`)
  - ❌ NO special punctuation
  - ✓ Use spaces: `[Gen AI]` instead of `[Gen-AI]`
  - ✓ Use simple words: `[Cross Account IAM Role]` instead of `[Cross-Account IAM Role]`

**Default icons**: `cloud`, `database`, `disk`, `internet`, `server`

**→ For extended icons and advanced features, see [references/architecture-diagrams.md](references/architecture-diagrams.md)**

### 🔍 Automatic Validation Process

After generating any architecture diagram, you MUST:

1. **Create temp files:**
   ```bash
   echo "YOUR_ARCHITECTURE_DIAGRAM_HERE" > /tmp/mermaid_validate.mmd
   ```

2. **Run enhanced validation (your bash script approach):**
   ```bash
   mmdc -i /tmp/mermaid_validate.mmd -o /tmp/mermaid_validate.svg 2>/tmp/mermaid_validate.err
   rc=$?
   if [ $rc -ne 0 ]; then
     echo "🛑 mmdc failed (exit code $rc)."; cat /tmp/mermaid_validate.err; exit 1
   fi

   # Check SVG for error markers that mmdc might miss
   if grep -q -i 'Syntax error in graph\|mermaidError\|errorText\|Parse error' /tmp/mermaid_validate.svg; then
     echo "🛑 Mermaid syntax error found in output SVG"
     exit 1
   fi

   # Verify SVG actually contains diagram content (not just error text)
   if ! grep -q '<svg.*width.*height' /tmp/mermaid_validate.svg; then
     echo "🛑 SVG output appears invalid or empty"
     exit 1
   fi

   echo "✅ Diagram appears valid"
   ```

3. **If validation fails, apply automatic fixes:**
   - **Fix hyphens in labels**: `[Gen-AI]` → `[Gen AI]`
   - **Remove colons**: `[API:prod]` → `[API Prod]`
   - **Remove special characters**: keep only alphanumeric, spaces, underscores
   - **Fix IDs**: ensure no spaces in service/group IDs (use underscores)
   - Review error details in `/tmp/mermaid_validate.err` for specific issues

4. **Re-validate until successful:** (repeat step 2)

5. **Cleanup and confirm:**
   ```bash
   rm -f /tmp/mermaid_validate.mmd /tmp/mermaid_validate.svg /tmp/mermaid_validate.err
   ```

**VALIDATION MUST PASS BEFORE PRESENTING TO USER!**

### Minimal Example

```mermaid
architecture-beta
    group stg_aitools(cloud)[AWS Stg AI Tools]
    group stg_genai(cloud)[AWS Stg Gen AI]

    service litellm(server)[LiteLLM Service] in stg_aitools
    service rds(database)[RDS PostgreSQL] in stg_aitools
    service redis(disk)[Redis Cache]