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

Identify diagram type — Is this a flow, architecture, sequence, or data model?
Choose format — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)
Draft minimal version — Core elements only, no decoration
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)