mermaid-diagram-generator

What this skill does

# Mermaid Diagram Generator Skill

## Purpose

This skill automatically converts text descriptions of system architectures, module specifications, workflow documentation, and design concepts into valid Mermaid diagram syntax. It enables clear visual communication of complex systems, ensuring diagrams are production-ready and embeddable in markdown documentation.

## When to Use This Skill

- **Architecture Visualization**: Convert architecture descriptions into flowcharts or block diagrams
- **Module Relationships**: Create diagrams showing how brick modules connect via their studs (public contracts)
- **Workflow Documentation**: Visualize workflow states, decisions, and transitions (DDD phases, investigation stages)
- **System Design**: Display system components, data flow, and interactions
- **Sequence Diagrams**: Show agent interactions, request/response patterns, or call sequences
- **Class Hierarchies**: Document module structure and class relationships
- **State Machines**: Model workflow states and valid transitions
- **Entity Relationships**: Display data model structures and relationships
- **Timeline Planning**: Create Gantt charts for project phases or milestones

## Supported Diagram Types

### 1. Flowcharts (Default)

Best for: workflow sequences, decision trees, process flows, module relationships

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
    C --> E[End]
    D --> E
```

### 2. Sequence Diagrams

Best for: agent interactions, API calls, multi-step processes, request/response patterns

```mermaid
sequenceDiagram
    participant User
    participant API
    participant Service
    User->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>User: Result
```

### 3. Class Diagrams

Best for: module structure, inheritance hierarchies, data models, component relationships

```mermaid
classDiagram
    class Brick {
        +String responsibility
        +PublicContract studs
    }
    class Module {
        +init()
        +process()
    }
    Brick <|-- Module
```

### 4. State Diagrams

Best for: workflow states, state machines, workflow phases, condition-based transitions

```mermaid
stateDiagram-v2
    [*] --> Planning
    Planning --> Design
    Design --> Implementation
    Implementation --> Testing
    Testing --> [*]
```

### 5. Entity Relationship Diagrams

Best for: data models, database schemas, entity relationships

```mermaid
erDiagram
    MODULE ||--o{ FUNCTION : exports
    MODULE ||--o{ DEPENDENCY : requires
    FUNCTION }o--|| CONTRACT : implements
```

### 6. Gantt Charts

Best for: project timelines, workflow phases, milestone planning

```mermaid
gantt
    title Project Timeline
    section Phase 1
    Planning :p1, 0, 30d
    Design :p2, after p1, 20d
    section Phase 2
    Implementation :p3, after p2, 40d
    Testing :p4, after p3, 25d
```

## Step-by-Step Generation Process

### Step 1: Understand the Source Material

1. Read the architecture description, spec, or workflow document
2. Identify the main entities or nodes
3. Determine how they relate or flow
4. Choose the appropriate diagram type

### Step 2: Identify Diagram Type

| Source Material                         | Best Diagram Type          |
| --------------------------------------- | -------------------------- |
| Workflow steps, process flow            | Flowchart                  |
| Module relationships, brick connections | Flowchart or Class Diagram |
| Agent interactions, call sequences      | Sequence Diagram           |
| States and transitions                  | State Diagram              |
| Data models, entities                   | Class Diagram or ERD       |
| Database schema                         | ERD                        |
| Project timeline                        | Gantt Chart                |
| Complex hierarchies                     | Class Diagram              |

### Step 3: Extract Entities and Relationships

1. List all nodes/entities from the source
2. Identify connections between them
3. Determine connection types (data flow, inheritance, calling, etc.)
4. Note any decision points or conditions

### Step 4: Generate Mermaid Syntax

1. Use appropriate Mermaid diagram declaration
2. Create nodes with descriptive labels
3. Draw connections with proper syntax
4. Add styling if needed for clarity
5. Ensure valid Mermaid syntax

### Step 5: Validate and Enhance

1. Ensure all entities are included
2. Verify connections are accurate
3. Add styling for important elements
4. Make diagram readable and not cluttered
5. Test syntax for validity

### Step 6: Document and Embed

1. Add title and description
2. Include explanation of diagram
3. Provide legend if needed
4. Embed in markdown with proper formatting

## Usage Examples

### Example 1: Architecture Description to Flowchart

**Input:**

```
The authentication module handles JWT token validation. When a request arrives,
it first checks if a token exists. If not, it returns unauthorized. If it does,
it validates the token signature. If valid, it extracts the payload and continues.
If invalid, it returns forbidden. The payload is passed to the authorization
module for role-based access control.
```

**Output:**

```mermaid
flowchart TD
    A[Request Arrives] --> B{Token Exists?}
    B -->|No| C[Return Unauthorized]
    B -->|Yes| D{Token Valid?}
    D -->|No| E[Return Forbidden]
    D -->|Yes| F[Extract Payload]
    F --> G[Check Role-Based Access]
    G --> H{Authorized?}
    H -->|No| I[Return Access Denied]
    H -->|Yes| J[Allow Request]
    C --> K[End]
    E --> K
    I --> K
    J --> K
```

### Example 2: Module Spec to Class Diagram

**Input:**

```
Module: authentication
- Exports: validate_token, TokenPayload, AuthError
- Classes: TokenPayload (user_id, role, expires_at), AuthError (message, code)
- Functions: validate_token(token, secret) -> TokenPayload
- Internal: JWT (PyJWT library), Models (TokenPayload)
```

**Output:**

```mermaid
classDiagram
    class AuthenticationModule {
        +validate_token(token, secret)
        +TokenPayload
        +AuthError
    }
    class TokenPayload {
        +String user_id
        +String role
        +DateTime expires_at
        +to_dict()
    }
    class AuthError {
        +String message
        +Integer code
        +__str__()
    }
    AuthenticationModule -- TokenPayload
    AuthenticationModule -- AuthError
```

### Example 3: Workflow to State Diagram

**Input:**

```
DDD Workflow: Phase 0 (Planning) -> Phase 1 (Documentation) ->
Approval Gate -> Phase 2 (Code Planning) -> Phase 3 (Implementation) ->
Phase 4 (Testing & Cleanup) -> Complete
```

**Output:**

```mermaid
stateDiagram-v2
    [*] --> Planning
    Planning --> Documentation
    Documentation --> ApprovalGate
    ApprovalGate --> CodePlanning
    CodePlanning --> Implementation
    Implementation --> Testing
    Testing --> [*]
```

### Example 4: Agent Interaction to Sequence Diagram

**Input:**

```
The prompt-writer agent clarifies requirements from the user. It then sends
the clarified requirements to the architect agent. The architect creates a
specification and sends it to the builder agent. The builder implements code
and sends it to the reviewer. The reviewer checks quality and sends feedback
back to the builder if issues are found, or to the user if complete.
```

**Output:**

```mermaid
sequenceDiagram
    actor User
    participant PromptWriter
    participant Architect
    participant Builder
    participant Reviewer

    User->>PromptWriter: Request Feature
    PromptWriter->>Architect: Clarified Requirements
    Architect->>Builder: Specification
    Builder->>Reviewer: Implementation
    Reviewer-->>Builder: Issues Found
    Builder->>Reviewer: Fixed Implementation
    Reviewer-->>User: Complete & Approved
```

### Example 5: System Architecture to Flowchart

**Input:**

```
Client requests flow through API Gateway to Services. Services can be
Authentication