/architecture-diagram

name: architecture-diagram
version: 1.3.0
description: "Build interactive, click-through architecture diagrams for software systems — a self-contained single HTML file with animated step-by-step flows, mode toggles (dev/prod, offline/online, v1/v2), dark/light theme, and a side panel with payload details, plus a companion markdown description. Use when the user wants to visualize or design a system: architecture diagram, service map, data flow, RAG/agentic flow, microservices topology, integration diagram, CI/CD or data/ETL pipeline, multi-agent system, or onboarding diagram — or to design a new service's flows before building. Natural-language triggers: 'I'm building X, what should the flow look like', 'pokaż jak działa system', 'diagram architektury', 'wizualizacja systemu', 'klikany diagram'. Do NOT use for static diagrams that belong inline (Mermaid/PlantUML), slide decks, or printable/PDF handouts — this produces interactive HTML for browser consumption."
license: MIT

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

| Situation | Use this skill? | |---|---| | "Show me how the auth flow works" (interactive, for a workshop) | **Yes** | | "Design the RAG pipeline before we build it" (planning new service) | **Yes** | | "Map our microservices and how they communicate" | **Yes** | | "Visualize the CI/CD pipeline for onboarding docs" | **Yes** | | "Show the data flow through our ETL pipeline" | **Yes** | | "Draw an agentic multi-agent system with tool calls" | **Yes** | | "Build me an architecture mockup we can iterate on with the team" | **Yes** | | "Draw a sequence diagram for the PR" (static, goes in markdown) | No — a Mermaid sequence diagram inline is simpler | | "Add a diagram to a slide deck or PDF" (static, not interactive) | No — this produces interactive HTML, not images or slides | | "I just need a static boxes-and-arrows topology" (no flows/steps) | No — a Mermaid flowchart is enough |

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 — a missing `color` leaves the wire uncolored, a missing `title` leaves the panel header blank.) 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. 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. 2. **`.modepick` buttons** — mode toggle labels (or remove if single-mode). 3. **`.flowtabs`** — one `.flowtab` per scenario; `data-flow` must match a `flows` key. 4. **`.node` divs** in `.stage` — one per service: `data-id`, `data-role`, `style="left/top"`, label, tech, port. 5. **The `flows` object in JS** — one entry per scenario, each with an ordered `steps[]` array.

Conditional: update the `.legend` only if your roles differ from the de