excalidraw-architecture

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. 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.
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"