Diagram

--- name: Diagram description: Generate diagrams from descriptions with Mermaid, PlantUML, or ASCII for architecture, flows, sequences, and data models. ---

Principle

Diagrams should clarify, not complicate. Start simple, add detail only when needed. A 5-box flowchart beats a 50-node sprawl.

When User Describes a System or Flow

1. Identify diagram type — Is this a flow, architecture, sequence, or data model?
2. Choose format — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)
3. Draft minimal version — Core elements only, no decoration
4. Iterate — Add detail based on feedback

Diagram Types

| Type | Use For | Format | |------|---------|--------| | Flowchart | Processes, decisions, workflows | Mermaid flowchart | | Sequence | API calls, interactions, protocols | Mermaid sequenceDiagram | | Architecture | System components, infrastructure | Mermaid flowchart or C4 | | ER/Data model | Database schemas, relationships | Mermaid erDiagram | | Class | Object structure, inheritance | Mermaid classDiagram | | State | Lifecycles, status transitions | Mermaid stateDiagram-v2 | | Timeline | Project phases, history | Mermaid timeline | | Mindmap | Brainstorming, concept mapping | Mermaid mindmap |

Output Methods

| Method | When | |--------|------| | Mermaid code block | User can render (docs, GitHub, Notion) | | Render to PNG/SVG | User needs image file | | ASCII inline | Quick sketch in chat | | HTML + Mermaid.js | Interactive viewing |

Rendering Mermaid to Image

# Using mmdc (mermaid-cli)
npx -y @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b transparent

# Or via browser tool
# Write HTML with Mermaid, screenshot the rendered diagram

Mermaid Quick Reference

Flowchart:

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

Sequence:

sequenceDiagram
    User->>API: Request
    API->>DB: Query
    DB-->>API: Result
    API-->>User: Response

ER Diagram:

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains

Style Guidelines

• Left-to-right (LR) for processes, top-to-bottom (TB) for hierarchies
• Max 10-15 nodes per diagram, split if larger
• Consistent naming — all caps for systems, lowercase for actions
• Subgraphs to group related components
• Color sparingly — highlight critical paths only

Common Requests

| Request | Interpret As | |---------|--------------| | "Draw my API flow" | Sequence diagram: client → API → services | | "Show the architecture" | Flowchart with subgraphs for components | | "Database schema" | ER diagram with relationships | | "How the auth works" | Sequence or flowchart depending on complexity | | "User journey" | Flowchart with decision points |

Anti-Patterns

• ❌ Too many nodes (split into multiple diagrams)
• ❌ Decorative icons without meaning
• ❌ Mixing abstraction levels (database tables next to business concepts)
• ❌ Arrows in all directions (confuses flow)
• ❌ Labels too long (use short names, add legend if needed)