excalidraw

name	excalidraw
description	Generate Excalidraw architecture diagrams (.excalidraw JSON files) from your codebase. Produces hand-drawn-style C4 context and container diagrams, sequence diagrams for key flows, ER diagrams from database schemas, and module dependency graphs. Use when you need whiteboard-style sketches that read as a thinking artifact rather than a polished spec — ideal for design docs, onboarding, and slide decks. Complements the `diagram` skill (which produces Mermaid).
version	1.0.0
category	docs
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project codebase and generate Excalidraw architecture diagrams as .excalidraw JSON files.

INPUT: $ARGUMENTS

Accepted arguments:

• No arguments: generate all applicable diagram types.
• c4: generate C4 Context and Container diagrams only.
• sequence: generate sequence diagrams for key flows only.
• er: generate ER diagram from database schema only.
• deps or dependency: generate module dependency graph only.
• A specific flow description (e.g., "user login flow"): generate a sequence diagram for that flow only.

============================================================ PHASE 1: CODEBASE ANALYSIS

Step 1.1 — Tech Stack and Architecture Detection

Scan config files to determine: project type (web app, API, mobile, CLI, library, monorepo), primary language/framework, database(s), external services (auth, payment, email, storage), message queues, caching layers, and API gateway config.

Step 1.2 — Service and Module Mapping

For monorepos/microservices: read docker-compose.yml or K8s manifests for service definitions, map inter-service communication, identify external deps per service.

For monoliths: read directory structure to identify modules/domains, trace import statements to map module dependencies, identify layer boundaries.

Step 1.3 — Database Schema Extraction

Scan for schema definitions in: schema.prisma, *.entity.ts (TypeORM/MikroORM), models/*.js (Sequelize), models.py (Django), db/schema.rb (Rails), models/*.py (SQLAlchemy), schema.ts (Drizzle), migrations/*.sql, *.model.ts (Mongoose).

Extract: table/collection names, columns with types, primary/foreign keys, relationships (1:1, 1:N, M:N), indexes, and enums.

Step 1.4 — Key Flow Identification

Identify the most important flows to diagram:

• Authentication flow (login, signup, token refresh)
• Primary business flow (main use case)
• Data write flow (create/update through layers)
• API request lifecycle (middleware, validation, handler, response)
• Background job flow (if applicable)

For each flow, trace: entry point, middleware, service layer, data access, external calls, and response construction.

============================================================ PHASE 2: EXCALIDRAW FILE FORMAT

Each .excalidraw file is a single JSON document with this top-level shape:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [],
  "appState": {
    "gridSize": 20,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

Every element MUST include: id (random nanoid-like string), type, x, y, width, height, angle (default 0), strokeColor, backgroundColor, fillStyle (hachure | cross-hatch | solid), strokeWidth (1 thin, 2 bold, 4 extra-bold), strokeStyle (solid | dashed | dotted), roughness (0 smooth, 1 normal, 2 cartoonist), opacity (0–100), groupIds ([]), frameId (null), roundness (null or { "type": 3 } for rounded rectangles), seed (random int), version (1), versionNonce (random int), isDeleted (false), boundElements (null or array), updated (epoch ms), link (null), locked (false).

Type-specific extras:

• rectangle / ellipse / diamond: no extra required fields beyond the base. Use roundness: { "type": 3 } for rounded rectangles.
• text: text (string), fontSize (16/20/28/36), fontFamily (1 = Virgil hand-drawn, 2 = Helvetica, 3 = Cascadia mono — prefer 1 for sketch feel), textAlign (left|center|right), verticalAlign (top|middle|bottom), baseline (fontSize * 0.85 rounded), containerId (null or the id of a shape it labels), originalText (same as text), lineHeight (1.25).
• arrow / line: points (array of [x,y] offsets from element origin, first is [0,0]), lastCommittedPoint (null), startBinding and endBinding (null or { "elementId": "<id>", "focus": 0, "gap": 8 } to attach to shapes), startArrowhead (null or "arrow"), endArrowhead ("arrow"), elbowed (false).

Color palette — use the Excalidraw default-ish set so files open cleanly:

• Stroke: #1e1e1e (default), #2f9e44 (success/db), #e03131 (external/danger), #1971c2 (api/services), #f08c00 (queue/cache).
• Background fills: #ffffff (none), #b2f2bb (db), #ffc9c9 (external), #a5d8ff (service), #ffec99 (queue/cache).
• Default fillStyle: "hachure" for that hand-drawn shading.

Layout rules (avoid overlap and produce a readable canvas):

• Pick a grid: 240px column step, 140px row step.
• Label text elements should be centered inside their container — set containerId and place x/y/width/height to match.
• Arrows must reference both endpoints via startBinding/endBinding so they reflow if a shape moves.
• Add each shape's id to the other endpoint's boundElements array as { "id": "<arrowId>", "type": "arrow" }.

============================================================ PHASE 3: DIAGRAM GENERATION

Step 3.1 — C4 Context Diagram (docs/diagrams/excalidraw/c4-context.excalidraw)

Center the System under test as a rounded rectangle with a bold label. Place users/actors as ellipses on the left, external systems as rectangles with strokeStyle: "dashed" on the right. Arrows labeled with the relationship verb ("uses", "sends events to"). Keep it under 12 shapes.

Step 3.2 — C4 Container Diagram (docs/diagrams/excalidraw/c4-container.excalidraw)

Inside a large dashed rectangle representing the system boundary, draw each container (web app, API, worker, db, cache, queue) as a labeled rounded rectangle. Use the color palette above. Annotate arrows with protocol (HTTPS, SQL, AMQP, gRPC).

Step 3.3 — Sequence Diagrams (docs/diagrams/excalidraw/sequence-<flow>.excalidraw)

Lay participants out as labeled rectangles along the top edge (x stepped by 200, y = 40). Drop a vertical dashed line beneath each as the lifeline. Messages are horizontal arrows between lifelines, stepping y by 80 per message. Always generate the auth flow if auth exists, plus the primary business flow.

Step 3.4 — ER Diagram (docs/diagrams/excalidraw/er-diagram.excalidraw)

Each table is a rounded rectangle with two text rows: bold table name (fontSize 20) on top, then a multi-line column list (fontSize 16) listing name: type with (PK) / (FK) markers. Relationships are arrows with cardinality labels (1, 0..1, *).

Step 3.5 — Module Dependency Graph (docs/diagrams/excalidraw/dependency-graph.excalidraw)

Top-down layout: entry points (routes/controllers) at the top, data stores at the bottom, external systems on the sides. Use background-fill color to encode the layer (api / domain / data / external). Highlight circular dependencies with red dashed arrows.

============================================================ PHASE 4: OUTPUT AND ORGANIZATION

Create docs/diagrams/excalidraw/ if it does not exist. Skip diagram types with no underlying data (no ER if no database).

For every .excalidraw file, also write a sibling .md file with the same stem containing: heading, brief explanation of the diagram, and a fenced link [Open in Excalidraw](./<file>.excalidraw). The .excalidraw file can be opened directly at https://excalidraw.com (File → Open) or via the VS Code Excalidraw extension.

Generate docs/diagrams/excalidraw/README.md listing every diagram with a one-line description and a link to both the JSON file and the explanation.

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing each .excalidraw file, validate:

1. The file is valid JSON (jq empty <file> exits 0). If jq is unavailable, parse with node -e "JSON.parse(require('fs').readFileSync('<file>','utf8'))".
2. type === "excalidraw", version === 2, elements is a non-empty array.
3. Every element has all required base fields listed in Phase 2.
4. Every arrow's startBinding.elementId and endBinding.elementId resolve to an existing element id.
5. No two non-arrow shapes overlap by more than 50% of either's bounding box.
6. No element has x or y greater than 4000 or less than -2000 (keeps the canvas reasonable).

If validation fails, regenerate only the offending file and re-validate. Stop after 2 iterations and report which file is still failing.

============================================================ OUTPUT

Excalidraw Diagrams Generated

System Profile

• Type: [monolith / microservices / monorepo]
• Services: [count]
• Database Tables: [count]
• External Systems: [count]

Diagrams Created

Diagram	File	Elements
C4 Context	docs/diagrams/excalidraw/c4-context.excalidraw	N
C4 Container	docs/diagrams/excalidraw/c4-container.excalidraw	N
Sequence: Auth	docs/diagrams/excalidraw/sequence-auth.excalidraw	N
ER Diagram	docs/diagrams/excalidraw/er-diagram.excalidraw	N
Dependencies	docs/diagrams/excalidraw/dependency-graph.excalidraw	N

How to View

• Drag any .excalidraw file onto https://excalidraw.com
• Or install the pomdtr.excalidraw-editor VS Code extension and open in-editor

Observations

• [Circular dependencies detected]
• [Isolated modules with no connections]
• [Missing relationships that could not be determined]

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists at ~/.claude/projects/<project>/. If found, append to skill-telemetry.md:

### /excalidraw — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / 2 max
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Skip silently if the memory directory does not exist.

============================================================ DO NOT

• Do NOT fabricate components, services, or tables. Only diagram what exists.
• Do NOT include internal implementation details in C4 Context diagrams.
• Do NOT generate diagrams for types with no data (no ER if no database).
• Do NOT include sensitive info (credentials, internal URLs, IPs) in diagrams.
• Do NOT overwrite existing .excalidraw files without reading them first.
• Do NOT emit broken arrow bindings — every binding must reference an element that exists in the same file.
• Do NOT use fontFamily outside 1, 2, or 3. Other values render as boxes.

NEXT STEPS:

After generating diagrams:

• "Run /diagram to also produce Mermaid versions for inline rendering in Markdown."
• "Run /document to check overall documentation health."
• "Run /adr to create ADRs explaining architectural decisions shown in the diagrams."
• "Run /onboarding to include these diagrams in the developer onboarding guide."