Diagram

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

Output Methods

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

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)