/excalidraw-architecture

name: excalidraw-architecture
description: Trigger when the user asks for an architecture diagram, says "draw the system", "update the architecture diagram", "give me an excalidraw of this codebase", or "/excalidraw-architecture". Generates or updates an Excalidraw JSON file at docs/architecture.excalidraw by reading the codebase's key entry points.

Excalidraw Architecture

Produce an architecture diagram of the current project as an Excalidraw file (`docs/architecture.excalidraw`). The diagram shows services, entry points, data stores, and the edges between them — the kind of whiteboard sketch you'd draw in a design review.

Inspired by Bilgin Ibryam's Medium post on "Architecture diagrams as code with Claude Code + Excalidraw" — credit: [@bibryam](https://medium.com/@bibryam). This skill is a lightweight reimplementation for OpenClaw-style repos.

When to use

• New contributor asks "what does this repo look like?"
• User wants to update a stale architecture diagram after a refactor
• User says "draw me the system", "excalidraw the backend", "/excalidraw-architecture"
• Preparing a design doc and needs a canonical diagram

Instructions

1. **Survey the codebase.** Use Glob and Grep to identify:

• Entry points: `main.*`, `index.*`, `server.*`, `api/**/route.*`, `cmd/*/main.go`, `package.json` "scripts" field, `Dockerfile` `CMD`.
• Data stores: mentions of `postgres`, `redis`, `convex`, `sqlite`, `s3`, `mongodb`, `prisma`.
• External services: Stripe, OpenAI, Anthropic, Twilio, SendGrid, webhook handlers.
• Internal modules: top-level folders under `src/`, `app/`, `lib/`, `agents/`.

Read at most 3-5 key files to confirm how the pieces connect — don't try to read the whole repo. 2. **Sketch the model mentally.** List nodes (rectangles) and edges (arrows with labels like "HTTP", "SQL", "pub/sub"). Group related nodes into clusters. 3. **Generate the Excalidraw JSON.** The file format is standard Excalidraw:

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

Each element needs at minimum: `id`, `type` (`rectangle` / `arrow` / `text` / `ellipse`), `x`, `y`, `width`, `height`, `angle: 0`, `strokeColor`, `backgroundColor`, `fillStyle`, `strokeWidth`, `roughness`, `opacity`, `seed`, `versionNonce`, `isDeleted: false`, `groupIds: []`, `boundElements`, `updated`, `link: null`, `locked: false`. For text elements add `text`, `fontSize`, `fontFamily`, `textAlign`, `verticalAlign`. For arrows add `points`, `startBinding`, `endBinding`. Use integer pixel coordinates on a ~20px grid. Arrange nodes left-to-right by data flow. 4. **Do not hand-forge exotic fields you're unsure about.** If a field is optional and you're not confident, omit it — Excalidraw is forgiving on load. When in doubt, open the resulting file in the Excalidraw web app and confirm it renders; fix any errors it reports. 5. **Write the file** to `docs/architecture.excalidraw` using the Write tool. If the directory doesn't exist, create it first with `mkdir -p docs`. 6. **Offer to open it.** Suggest the user run:

   open docs/architecture.excalidraw   # macOS — opens in Excalidraw desktop app if installed

Or drag-drop into [excalidraw.com](https://excalidraw.com). 7. **Update vs regenerate.** If `docs/architecture.excalidraw` already exists, read it first. If the existing layout still fits, only add/move the nodes that changed. If the shape of the system has changed significantly, tell the user and regenerate from scratch.

Style guidelines

• Rectangles for services, ellipses for datastores, small rectangles with dashed stroke for external SaaS.
• Arrows labelled with the protocol (`HTTP`, `gRPC`, `SQL`, `webhook`).
• Max ~15 nodes. If the system is bigger, produce a top-level diagram and suggest follow-up per-subsystem diagrams.
• Leave a title text element at the top: `<repo name> — architecture (generated <date>)`.

Example invocations

• `/excalidraw-architecture`
• "Draw the architecture of this repo"
• "Update docs/architecture.excalidraw — I just added a Redis queue"
• "Give me an excalidraw diagram of how the OpenClaw gateway talks to agents"