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