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)
1---2name: diagram3description: Generate diagrams from descriptions with Mermaid, PlantUML, or ASCII for architecture, flows, sequences, and data models.4---5
6## Principle
7
8Diagrams should **clarify, not complicate**. Start simple, add detail only when needed. A 5-box flowchart beats a 50-node sprawl.
9
10## When User Describes a System or Flow
11
121. **Identify diagram type** — Is this a flow, architecture, sequence, or data model?
132. **Choose format** — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)
143. **Draft minimal version** — Core elements only, no decoration
154. **Iterate** — Add detail based on feedback
16
17## Diagram Types
18
19| Type | Use For | Format |
20|------|---------|--------|
21| Flowchart | Processes, decisions, workflows | Mermaid `flowchart` |
22| Sequence | API calls, interactions, protocols | Mermaid `sequenceDiagram` |
23| Architecture | System components, infrastructure | Mermaid `flowchart` or `C4` |
24| ER/Data model | Database schemas, relationships | Mermaid `erDiagram` |
25| Class | Object structure, inheritance | Mermaid `classDiagram` |
26| State | Lifecycles, status transitions | Mermaid `stateDiagram-v2` |
27| Timeline | Project phases, history | Mermaid `timeline` |
28| Mindmap | Brainstorming, concept mapping | Mermaid `mindmap` |
29
30## Output Methods
31
32| Method | When |
33|--------|------|
34| Mermaid code block | User can render (docs, GitHub, Notion) |
35| Render to PNG/SVG | User needs image file |
36| ASCII inline | Quick sketch in chat |
37| HTML + Mermaid.js | Interactive viewing |
38
39### Rendering Mermaid to Image
40
41```bash
42# Using mmdc (mermaid-cli)
43npx -y @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b transparent
44
45# Or via browser tool
46# Write HTML with Mermaid, screenshot the rendered diagram
47```
48
49## Mermaid Quick Reference
50
51**Flowchart:**
52```mermaid
53flowchart LR
54 A[Start] --> B{Decision}
55 B -->|Yes| C[Action]
56 B -->|No| D[End]
57```
58
59**Sequence:**
60```mermaid
61sequenceDiagram
62 User->>API: Request
63 API->>DB: Query
64 DB-->>API: Result
65 API-->>User: Response
66```
67
68**ER Diagram:**
69```mermaid
70erDiagram
71 USER ||--o{ ORDER : places
72 ORDER ||--|{ ITEM : contains
73```
74
75## Style Guidelines
76
77- **Left-to-right (LR)** for processes, **top-to-bottom (TB)** for hierarchies
78- **Max 10-15 nodes** per diagram, split if larger
79- **Consistent naming** — all caps for systems, lowercase for actions
80- **Subgraphs** to group related components
81- **Color sparingly** — highlight critical paths only
82
83## Common Requests
84
85| Request | Interpret As |
86|---------|--------------|
87| "Draw my API flow" | Sequence diagram: client → API → services |
88| "Show the architecture" | Flowchart with subgraphs for components |
89| "Database schema" | ER diagram with relationships |
90| "How the auth works" | Sequence or flowchart depending on complexity |
91| "User journey" | Flowchart with decision points |
92
93## Anti-Patterns
94
95- ❌ Too many nodes (split into multiple diagrams)
96- ❌ Decorative icons without meaning
97- ❌ Mixing abstraction levels (database tables next to business concepts)
98- ❌ Arrows in all directions (confuses flow)
99- ❌ Labels too long (use short names, add legend if needed)
modbender