/architecture-diagram

name: architecture-diagram
version: 1.5.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 — `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