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-cliPuppeteer 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
.mmdfile with Mermaid syntax - Render — Run
mmdcto 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-nameThen 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.jsonAlways 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
subgraphfor logical grouping in architecture diagrams - Limit ER diagrams to ~10 entities — split by domain if larger
participantaliases 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
.mmdsource + 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