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

| 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", 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:
5. hide/show entire nodes (e.g. Seed only exists offline)
6. rename a node (Qdrant → BigQuery)
7. 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

| File | When to read | |---|---| | assets/template.html | Always. This is the starting point you copy and modify. | | assets/css-tokens.css | If user asks to restyle (e.g. light theme, different brand colors). Standalone tokens you can splice into existing CSS. | | references/flow-design-patterns.md | When planning a new system from scratch. Heuristics for node placement, naming flows, sequencing steps, choosing modes. | | references/component-library.md | When building the nodes list. Copy-paste node snippets for User/API/DB/Queue/Cache/LLM/Cron/External/etc. with proper roles and icons. | | references/screenshot.js | When you want to spot-check the result before showing the user. Run with node if puppeteer-core is installed. | | examples/rag-eskadra-bielik.json | Reference example: a real RAG system with 5 flows and offline/online modes. Read for inspiration on payload formatting and chip choices. | | examples/auth-oauth2.json | Reference example: an OAuth2 + session flow with dev/prod modes. Shows redirect flows and external IdP nodes. | | examples/event-driven.json | Reference example: event-driven microservices with Kafka, showing async fan-out flows. | | examples/cicd-pipeline.json | Reference example: CI/CD pipeline with GitHub Actions, staging/prod modes, rollback flow. | | examples/agentic-tool-calling.json | Reference example: agentic AI system with tool calling, single-agent vs multi-agent mode