/diagram

allowed-tools: Read, Write, Bash(fd:*), Bash(rg:*), Bash(mmdc:*), Bash(gdate:*), Agent
name: "Diagram"
description: "Generate architecture and flow diagrams with ASCII art and Mermaid"
author: "wcygan"
tags: ["tool"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N`
• Project files: !`fd -t f -e ts -e js -e rs -e go -e java -e py . | head -20`
• Main entry points: !`fd "^(main|index|app)\\.(ts|js|rs|go|java|py)$" . | head -10`
• Package info: !`fd "^(package\\.json|Cargo\\.toml|go\\.mod|pom\\.xml|requirements\\.txt)$" . | head -5`
• Mermaid CLI available: !`which mmdc > /dev/null && echo "yes" || echo "no"`

Your task

PROCEDURE generate_diagram():

STEP 1: Parse request parameters

• Extract diagram type from $ARGUMENTS (default: architecture)
• Valid types: architecture, flow, sequence, class, entity, component
• Extract scope/focus area if provided
• FOR complex analysis: think hard about the optimal diagram structure

STEP 2: Analyze codebase structure

• IF scope provided:
• Focus analysis on specific area: !`fd -t f "$SCOPE" . | head -20`
• ELSE:
• Scan project structure: !`fd -t f -e ts -e js -e rs -e go -e java -e py . | wc -l`
• Identify main components: !`fd -t d -d 2 . | head -20`

STEP 3: Gather relevant information

FOR diagram_type: CASE "architecture":

• Find service boundaries: !`fd -t d "(service|module|component)" . | head -10`
• Identify databases: !`rg -i "(postgres|mysql|mongo|redis)" --type-add 'config:*.{yml,yaml,json,env}' -t config`
• Locate API layers: !`rg "@(Controller|Route|Api)" -t ts -t js -t java`

CASE "flow":

• Trace request flow: !`rg "(router|route|endpoint)" -A 2`
• Find middleware: !`rg "middleware|interceptor|filter" -l`

CASE "class":

• Extract classes: !`rg "^\\s*(export\\s+)?class\\s+\\w+" -o`
• Find inheritance: !`rg "extends|implements" -B 1`

CASE "sequence":

• Identify actors: !`rg "(client|server|service|api)" -i`
• Map interactions: !`rg "(call|request|response|emit)" -A 2`

STEP 4: Generate diagram

• Choose appropriate format (ASCII for simplicity, Mermaid for complexity)
• FOR complex diagrams: Use sub-agents for parallel analysis
• Structure output with clear component boundaries
• Add directional flows and relationships
• Apply consistent color themes and icons (see Visual Design Guidelines)

STEP 5: Export diagram (if mmdc available)

• Save Mermaid diagram to temp file: /tmp/diagram-$SESSION_ID.mmd
• IF mmdc available AND user requests image:
• Generate PNG: mmdc -i /tmp/diagram-$SESSION_ID.mmd -o diagram.png
• Generate SVG: mmdc -i /tmp/diagram-$SESSION_ID.mmd -o diagram.svg
• Report output location

STEP 6: Enhance with documentation

• Add component descriptions
• Document key relationships
• Include architectural decisions
• Provide usage notes

Diagram Examples

Architecture Diagram (ASCII)

┌─────────────────────────────────────────────────────────────┐
│                      Frontend (React/Fresh)                  │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Browser   │  │   Mobile App │  │   CLI Client    │   │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘   │
└─────────┼─────────────────┼──────────────────┼─────────────┘
          │                 │                  │
          └─────────────────┴──────────────────┘
                            │
                  ┌─────────▼─────────┐
                  │   Load Balancer   │
                  │    (HAProxy)      │
                  └─────────┬─────────┘
                            │
        ┌───────────────────┴───────────────────┐
        │                                       │
┌───────▼────────┐                    ┌────────▼────────┐
│   API Gateway  │                    │  Static Assets  │
│  (Kong/Envoy)  │                    │     (CDN)       │
└───────┬────────┘                    └─────────────────┘
        │
┌───────┴────────────────────────────────────┐
│              Microservices                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │   Auth   │  │  Orders  │  │ Payments │ │
│  │ Service  │  │ Service  │  │ Service  │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘ │
└───────┼─────────────┼─────────────┼───────┘
        │             │             │
        └─────────────┴─────────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
┌────────▼────────┐      ┌─────────▼────────┐
│    PostgreSQL   │      │   Message Queue  │
│   (Primary DB)  │      │    (RabbitMQ)    │
└─────────────────┘      └──────────────────┘

Flow Diagram (Mermaid)

flowchart TD
    A[User Request] --> B{Authenticated?}
    B -->|No| C[Login Page]
    B -->|Yes| D[Load Dashboard]
    
    C --> E[Enter Credentials]
    E --> F{Valid?}
    F -->|No| C
    F -->|Yes| G[Generate Token]
    G --> D
    
    D --> H[Fetch User Data]
    H --> I[Render Dashboard]
    I --> J{User Action}
    
    J -->|View Reports| K[Load Reports]
    J -->|Edit Profile| L[Profile Form]
    J -->|Logout| M[Clear Session]
    
    K --> N[Query Database]
    N --> O[Format Data]
    O --> P[Display Charts]

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant A as Auth Service
    participant D as Database
    participant Q as Queue
    
    C->>G: POST /api/login
    G->>A: Validate credentials
    A->>D: Check user exists
    D-->>A: User data
    
    alt Valid credentials
        A->>A: Generate JWT
        A-->>G: Token + User info
        G-->>C: 200 OK + Token
    else Invalid credentials
        A-->>G: 401 Unauthorized
        G-->>C: 401 Unauthorized
    end
    
    C->>G: GET /api/data (Token)
    G->>G: Validate token
    G->>Q: Log access event
    G-->>C: Return data

Class Diagram

classDiagram
    class User {
        +String id
        +String email
        +String name