Generate architecture diagrams as .excalidraw files from codebase analysis, with optional PNG/SVG export. Use when the user asks to create architecture diagrams, system diagrams, visualize codebase structure, generate excalidraw files, export excalidraw diagrams to PNG or SVG, or convert .excalidraw files to image formats.
Generate architecture diagrams as .excalidraw files directly from codebase analysis, with optional export to PNG and SVG.
User just asks:
"Generate an architecture diagram for this project"
"Create an excalidraw diagram of the system"
"Visualize this codebase as an excalidraw file"
The AI will:
.excalidraw JSON with dynamic IDs and labelsNo prerequisites: Works without existing diagrams, Terraform, or specific file types.
Diamond arrow connections are broken in raw Excalidraw JSON. Use styled rectangles instead:
| Semantic Meaning | Rectangle Style |
|---|---|
| Orchestrator/Hub | Coral (#ffa8a8/#c92a2a) + strokeWidth: 3 |
| Decision Point | Orange (#ffd8a8/#e8590c) + dashed stroke |
The label property does NOT work in raw JSON. Every labeled shape needs:
// 1. Shape with boundElements reference
{
"id": "my-box",
"type": "rectangle",
"boundElements": [{ "type": "text", "id": "my-box-text" }]
}
// 2. Separate text element with containerId
{
"id": "my-box-text",
"type": "text",
"containerId": "my-box",
"strokeColor": "#1e1e2e", // ALWAYS near-black — never inherit shape color
"text": "My Label"
}
All type: "text" elements must use "strokeColor": "#1e1e2e".
Never copy the parent shape's stroke color — colored text is hard to read.
For 90-degree corners (not curved):
{
"type": "arrow",
"roughness": 0, // Clean lines
"roundness": null, // Sharp corners
"elbowed": true // 90-degree mode
}
Arrows must start/end at shape edges, not centers:
| Edge | Formula |
|---|---|
| Top | (x + width/2, y) |
| Bottom | (x + width/2, y + height) |
| Left | (x, y + height/2) |
| Right | (x + width, y + height/2) |
Detailed arrow routing: See references/arrows.md
| Type | Use For |
|---|---|
rectangle | Services, databases, containers, orchestrators |
ellipse | Users, external systems, start/end points |
text | Labels inside shapes, titles, annotations |
arrow | Data flow, connections, dependencies |
line | Grouping boundaries, separators |
Full JSON format: See references/json-format.md
Use fontFamily in all text elements. Recommended: 3 (Code / Cascadia) for a clean, readable look.
| Value | Font | Use When |
|---|---|---|
| 1 | Virgil | Hand-drawn look |
| 2 | Helvetica | Clean sans-serif for formal diagrams |
| 3 | Code (Cascadia) | ✅ Recommended default — clean monospace, highly readable |
| 5 | Excalifont | Excalidraw's new default font (v0.17+) |
| 6 | Nunito | Rounded sans-serif (was value 5 in older excalidraw) |
| 7 | Lilita One | Bold display font |
| 8 | Comic Shanns | Comic-style monospace |
| 9 | Liberation Sans | Open-source sans-serif |
| 10 | Assistant | Clean sans-serif with Hebrew support |
| 100 | Xiaolai | CJK hand-drawn (automatic fallback for CJK text) |
⚠️ fontFamily 5 changed in v0.17+: It used to be Nunito — now it's Excalifont. Nunito moved to
6. Always use Virgil (1) for maximum compatibility across excalidraw versions.
Discover components by looking for:
| Codebase Type | What to Look For |
|---|---|
| Monorepo | packages/*/package.json, workspace configs |
| Microservices | docker-compose.yml, k8s manifests |
| IaC | Terraform/Pulumi resource definitions |
| Backend API | Route definitions, controllers, DB models |
| Frontend | Component hierarchy, API calls |
Use tools:
Glob → **/package.json, **/Dockerfile, **/*.tfGrep → app.get, @Controller, CREATE TABLERead → README, config files, entry pointsVertical flow (most common):
Row 1: Users/Entry points (y: 100)
Row 2: Frontend/Gateway (y: 230)
Row 3: Orchestration (y: 380)
Row 4: Services (y: 530)
Row 5: Data layer (y: 680)
Columns: x = 100, 300, 500, 700, 900
Element size: 160-200px x 80-90px
Other patterns: See references/examples.md
For each component:
idboundElements referencing textcontainerIdColor palettes: See references/colors.md
For each relationship:
points arrayArrow patterns: See references/arrows.md
For logical groupings:
strokeStyle: "dashed"Run validation before writing. Save to docs/ or user-specified path.
Validation checklist: See references/validation.md
After writing the .excalidraw file, ask the user if they want PNG, SVG, or both exports.
Preferred method: Node.js CLI (no browser required):
node .claude/skills/excalidraw/lib/export.cjs diagram.excalidraw diagram.png
One-time setup: cd .claude/skills/excalidraw/lib && npm install
Fallback: Playwright MCP tools (browser_navigate, browser_run_code, browser_close) if Node.js CLI is unavailable.
Full export procedure: See references/export.md
Straight down:
{ "points": [[0, 0], [0, 110]], "x": 590, "y": 290 }
L-shape (left then down):
{ "points": [[0, 0], [-325, 0], [-325, 125]], "x": 525, "y": 420 }
U-turn (callback):
{ "points": [[0, 0], [50, 0], [50, -125], [20, -125]], "x": 710, "y": 440 }
Arrow width/height = bounding box of points:
points [[0,0], [-440,0], [-440,70]] → width=440, height=70
Multiple arrows from same edge - stagger positions:
5 arrows: 20%, 35%, 50%, 65%, 80% across edge width
| Component | Background | Stroke |
|---|---|---|
| Frontend | #a5d8ff | #1971c2 |
| Backend/API | #d0bfff | #7048e8 |
| Database | #b2f2bb | #2f9e44 |
| Storage | #ffec99 | #f08c00 |
| AI/ML | #e599f7 | #9c36b5 |
| External APIs | #ffc9c9 | #e03131 |
| Orchestration | #ffa8a8 | #c92a2a |
| Message Queue | #fff3bf | #fab005 |
| Cache | #ffe8cc | #fd7e14 |
| Users | #e7f5ff | #1971c2 |
Cloud-specific palettes: See references/colors.md
Before writing file:
elbowed: true, roundness: nullFull validation algorithm: See references/validation.md
| Issue | Fix |
|---|---|
| Labels don't appear | Use TWO elements (shape + text), not label property |
| Arrows curved | Add elbowed: true, roundness: null, roughness: 0 |
| Arrows floating | Calculate x,y from shape edge, not center |
| Arrows overlapping | Stagger start positions across edge |
Detailed bug fixes: See references/validation.md
| File | Contents |
|---|---|
references/json-format.md | Element types, required properties, text bindings |
references/arrows.md | Routing algorithm, patterns, bindings, staggering |
references/colors.md | Default, AWS, Azure, GCP, K8s palettes |
references/examples.md | Complete JSON examples, layout patterns |
references/validation.md | Checklists, validation algorithm, bug fixes |
references/export.md | PNG/SVG export procedure via Playwright |
docs/architecture/ or user-specifiedsystem-architecture.excalidrawsystem-architecture.svg and/or system-architecture.png in same directory.excalidraw in https://excalidraw.com or VS Code extension; .svg and .png can be viewed directly or embedded in documentation