Code to Diagram

Generate production-quality diagrams from source code via Mermaid.js, rendered to SVG/PNG with mmdc.

Environment

Executor required: This skill needs the diagram executor (Chromium + Node.js + mmdc pre-installed). If mmdc is not available, install first:

npm install -g @mermaid-js/mermaid-cli

Puppeteer config for headless environments — create at /tmp/puppeteer-config.json if missing:

{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}

Workflow

Analyze — Read the codebase to understand structure (glob, grep, read)
Plan — Decide diagram type(s) based on user request and code patterns
Generate — Write .mmd file with Mermaid syntax
Render — Run mmdc to produce SVG and PNG
Verify — Read the output image and check correctness

Diagram Type Selection

User Intent	Diagram Type	Mermaid Keyword
System overview, module layout	Architecture	`graph TD` + `subgraph`
Database tables, ORM models	ER Diagram	`erDiagram`
API flow, request lifecycle	Sequence Diagram	`sequenceDiagram`
Inheritance, interfaces	Class Diagram	`classDiagram`
Business logic, conditionals	Flowchart	`flowchart TD`
Task states, lifecycle	State Diagram	`stateDiagram-v2`
Import/dependency tree	Dependency Graph	`graph LR`
Timeline, project phases	Gantt Chart	`gantt`

Analysis Strategy

Do NOT read every file. Use progressive analysis:

Step 1 — Directory scan: glob("**/*.py") or glob("**/*.ts") to understand module structure.

Step 2 — Entry points:

Python: main.py, app.py, __init__.py, pyproject.toml
Node.js: package.json, index.ts, app.ts
Java: pom.xml, Application.java

Step 3 — Targeted reads by diagram type:

ER → ORM models (models.py, schema.prisma, *.entity.ts)
Architecture → Router registrations, dependency injection, config
Sequence → Specific endpoint handler + service call chain
Class → Class definitions via grep("class ")

Step 4 — GitHub repos:

git clone --depth 1 <url> /tmp/repo-name

Then apply the same progressive scan.

Rendering

# SVG (transparent background, good for docs)
mmdc -i diagram.mmd -o diagram.svg -b transparent -p /tmp/puppeteer-config.json

# PNG (white background, 2x scale for sharpness)
mmdc -i diagram.mmd -o diagram.png -b white -s 2 -p /tmp/puppeteer-config.json

Always generate both formats. Use -s 2 for PNG (sharp at any zoom level).

Mermaid Syntax Reference

For detailed patterns and examples per diagram type, see references/mermaid-patterns.md.

Key rules:

Short IDs, descriptive labels: DB[("PostgreSQL 16")]
Use subgraph for logical grouping in architecture diagrams
Limit ER diagrams to ~10 entities — split by domain if larger
participant aliases in sequence diagrams for short names
Quote labels with special chars: A["Node (v1)"]
Max ~20 nodes per diagram — split into multiple if larger

Output Conventions

Write .mmd source + rendered files to workspace
Descriptive names: architecture.mmd, er-diagram.png, api-sequence.svg
Multiple diagrams → create diagrams/ folder with index

Quality Checklist

All entities/modules from the code are represented
Relationships and data flow directions are correct
Labels readable, not truncated or overlapping
No Mermaid syntax errors
Output image visually verified

code-to-diagram