konraddzbik/architecture-diagram-skill/architecture-diagram

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 a side panel, and toggleable modes (offline/online, dev/prod, v1/v2). The aesthetic is dark and didactic-first: bounded nodes, gentle quadratic wires, packets that glow only on the active step — no rainbow gradients. Rebrand via the CSS tokens in assets/css-tokens.css.

When to reach for this skill

The differentiator is interactivity + sequenced data flow: if the value is "click through it and watch what happens", use this skill; if you need a static image, a slide, or an inline diagram, use Mermaid instead.

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, color, title, route, payload, desc, chips}. Each step lights up one wire and one target node. (color and title are required — color must be a CSS variable name like --c-orch, anything else falls back to the brand accent; a missing title shows "—". Color it by the non-orchestrator endpoint: flow-design-patterns.md → "Wire color logic".) A step with from === to renders as a loop on that node — above it, or below for a top-row node (internal work such as "CI → CI: build").
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 — or described the system in their message — read it first. 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 that can't be reasonably defaulted. If the system, its main flows and its modes (or lack of them) are known — or the user said not to ask — proceed, and list your assumptions in architecture.md. Defaults: audience = engineers, language = the request's.

Only for a vague request ("diagram our backend") ask briefly: what system, which main flows, any mode toggles (offline/online, dev/prod, v1/v2), who the audience is.

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. It's a fully working drop-in: dark theme, side panel, player controls (play/pause/step), keyboard shortcuts, animated SVG packets, mode toggle. Edit only these regions (the template's top EDIT THESE THINGS comment is the authoritative list):

1. `<title>` + `<h1>` — replace {{SYSTEM_NAME}} and the header text. For a Polish (or other non-English) diagram also set <html lang="pl">.
2. `.modepick` buttons — mode toggle labels (or remove the whole .modepick if single-mode; the panel badge and O key adapt). Three or more modes are fine — O cycles through them.
3. `.flowtabs` — one .flowtab per scenario; data-flow must match a flows key. Tab order = keyboard digits 1–9; nothing else to keep in sync.
4. `.node` divs in .stage — one per service: data-id, data-role, style="left/top", label, tech, port. Place them on the grid in references/flow-design-patterns.md (left 2/26/52/78%, top 8/38/70%, ≥ 24% apart in a row) — fixed 150px tiles overlap or clip otherwise.
5. The `flows` object in JS — one entry per scenario, each with an ordered steps[] array. Set state.mode / state.flow to the keys you want shown first (an unknown key falls back to the first button and logs a warning).

Always edit the .legend: one item per role you use, labelled with what that color means in your system (e.g. compute → "Worker"); delete the rest. Recolor :root CSS variables only for a restyle. After editing, search the file for {{[A-Z] (regex) — a correctly filled file has zero matches.

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 5.)

Then run every check in references/validation.md the environment allows: the static check (needs only node); then, with puppeteer-core + Chrome, node <skill-dir>/references/screenshot.js architecture.html /tmp/arch-preview from the user's project (<skill-dir> = this SKILL.md's folder; exit 1 = page error, 2 = lint warnings — non-zero means fix the HTML) and read the canvas PNGs for overlapping or cut-off tiles; without either, window.archValidate() in the browser console ([] = clean).

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

The `examples/*.json` files are planning specs, not drop-in code — JSON outlines you translate into the template's HTML nodes + inline JS flows object. See references/flow-design-patterns.md → "Example JSON → template mapping" for the field-by-field translation.

Quick reference — node roles and colors

Hardcoded in CSS variables in template.html. Pick one per node:

Roles are color groups, not literal meanings; the legend labels say what each color means in your diagram. Don't invent more (Postgres + Redis are both vector, told apart by icon and label) — past seven the legend becomes a colorblind nightmare. An 8th role needs a --c-<role> in the dark :root and body.light blocks, a .node[data-role] rule, an ahMap entry + <marker>, and a legend item.

Visual states — what the viewer sees on each step

This is the most important didactic mechanic in the diagram. Understand it before modifying the JS or CSS, or you'll break the "click a flow tab, see the whole path" intuition.

When a user picks a flow tab and lands on step N, every node and wire is classified into one of these states: