Interactive Architecture Diagrams

Build single-file, drop-in HTML pages that let workshop attendees, clients, or new team members click through how a system works — step by step, with animated data packets flowing between nodes, payload details on the side panel, and toggleable modes (offline/online, dev/prod, v1/v2). Battle-tested on the Eskadra Bielik RAG workshop; reuse the design system everywhere else.

This skill produces diagrams in a dark, didactic-first aesthetic — nodes are bounded, wires are gentle quadratic curves, packets glow only on the active step. No "AI slop" rainbow gradients. The CSS tokens are exposed in assets/css-tokens.css if you want to rebrand.

When to reach for this skill

The differentiator is interactivity + sequenced data flow. If the value is "click through it and watch what happens", this skill applies. If the output needs to be a static image, a slide, or inline markdown, this is the wrong tool.

The mental model

Every diagram has four things:

1. Nodes — services, datastores, users, queues, external systems. Each has a role (color) and metadata (tech stack, port, deployment target).
2. Flows — named scenarios the user can pick (e.g. RAG Query, Direct Query, Ingest, Auth). Each flow is an ordered list of steps.
3. Steps — {from, to, route, payload, desc, chips}. Each step lights up one wire and one target node.
4. Modes — orthogonal toggle (offline/online, dev/prod, v1/v2). Modes can:
   • hide/show entire nodes (e.g. Seed only exists offline)
   • rename a node (Qdrant → BigQuery)
   • swap payload bodies, ports, auth headers, latency chips

Modes are NOT alternative flows. Flows describe scenarios ("user asks a question"); modes describe deployment shape ("on Docker" vs "on Cloud Run").

Workflow when invoked

Step 1 — Capture intent

If the user has uploaded a SOLUTION.md, README, OpenAPI spec, or any architecture description, read it first before asking questions. Extract:

• Service names + tech stack + ports
• Deployment modes (if any)
• Named endpoints/operations and what they do (these become flows)
• For each operation, the chain of internal service calls (these become steps)

Then ask ONLY the gaps. Don't ask things already in the doc.

If there's no doc, ask the user briefly:

• "What system are we drawing?"
• "What are the main flows you want to show? (e.g. login, search, checkout)"
• "Any mode toggles? (offline/online, dev/prod, v1/v2)"
• "Who's the audience? Workshop attendees? Engineers? Clients?"

Step 2 — Plan the topology on paper first

Before writing code, sketch on paper (literally in your head or a scratch file) WHICH services exist, WHERE they sit relative to each other, and WHICH flows connect WHICH nodes. Avoid wire crossings — this is the single biggest readability win. See references/flow-design-patterns.md for layout heuristics.

Quick rules:

• Orchestrator/API gateway in the middle, dependencies fanning out
• User on the far left (entry point), datastores on the right (exit), services in between
• Read-only services above, write-heavy services below (intuitive: data flows down into them)
• Optional/one-shot services (seed jobs, cron) tucked in a corner

Step 3 — Build from the template

Copy assets/template.html to the working directory. The template is a fully working drop-in: dark theme, side panel, player controls (play/pause/step), keyboard shortcuts, animated SVG packets, mode toggle. You only edit two regions:

1. The nodes block in HTML — one .node div per service with data-id, data-role, style="left/top", label, tech, port.
2. The flows object in JS — one entry per scenario, each with an ordered steps[] array.

Don't reinvent the CSS, the player, the SVG wire renderer, or the side panel — they all work.

Step 4 — Validate before showing the user

After generating, do this self-check:

• Open the file mentally: does every flow's step sequence make narrative sense? (Step 1 sets up, last step delivers a result to the user.)
• Do wires cross unnecessarily? If yes, reposition nodes (try moving the late-arriving dependency away from the early ones).
• Are there flows where a single node is the to of two consecutive steps? That's fine if it's a loop, but check the description explains why.
• Mode swap: pick the most different node between modes (usually the database) and verify ALL its mode-dependent fields are filled in (label, tech, port, payload, chips).
• Did you generate the companion architecture.md? (Required — see Step 6.)

If puppeteer is available in the environment, take a screenshot to spot-check layout. Code in references/screenshot.js.

Step 5 — Output the files

Always two files:

• architecture.html — the interactive diagram
• architecture.md — text description (components, flows step-by-step, mode differences, scenarios for the workshop)

Save to the current working directory. Platform-specific overrides:

• Claude.ai — use /mnt/user-data/outputs/ instead
• Claude Code / Gemini CLI / OpenCode / Copilot CLI — save to the current working directory (default)

Both should be self-sufficient — someone can read the markdown without opening the HTML, and vice versa.

Step 6 — Present the output

Tell the user where the files were saved and how to open them (open architecture.html on macOS, xdg-open architecture.html on Linux, or just open in browser). If present_files is available (Claude.ai), call it to display the HTML first, then the markdown.

File reference