Architecture Diagram

Architecture Diagrams (rask)

Build single-file, drop-in HTML pages that visualize how an RA system works. One skill, two modes:

• Interactive (assets/template.html) — let workshop attendees, reviewers, or new team members click through a system: animated data packets flow node-to-node, a side panel shows each step's payload, and mode toggles swap dev/prod · local/cloud · v1/v2 in place. The didactic, "watch what happens" diagram.
• Static (assets/static-template.html) — a polished dark boxes-and-arrows topology snapshot with grouping boundaries (cloud region, Kubernetes cluster, security group, micro-frontend zone). The export-it-to-a-deck diagram.

Both ship a built-in export toolbar (⋯ → 📋 Copy / 🖼️ PNG / 📄 PDF) so any diagram lands cleanly in Slack, a doc, or a PDF report.

RA house style — go wide and generous. Default to a wide canvas and spread nodes across the full width; size nodes large enough to read label + tech + port at a glance. The upstream layout skews small and narrow — deliberately push nodes apart, widen the canvas, and scale up. A diagram that fills the screen reads better in a workshop and exports to a crisper PNG/PDF. Cramped is the #1 failure mode here; when unsure, make it bigger.

Step 0 — Pick the mode

First decision; everything else follows.

The differentiator: interactivity + sequenced flow → interactive; a still picture to embed → static; inline in a .md → Mermaid. When in doubt and the value is "step through it and watch", default to interactive — it can still export a static PNG/PDF of any step.

The mental model

Interactive diagrams have four things:

1. Nodes — services, datastores, users, queues, jobs. Each has a role (color) and metadata (tech stack, port, deploy target).
2. Flows — named scenarios the viewer picks (HTR Ingest, RAG Query, GitOps Deploy, Auth). Each flow is an ordered list of steps.
3. Steps — {from, to, color, title, route, payload, desc, chips}. Each lights up one wire + one target node. color and title are required.
4. Modes — an orthogonal toggle (dev/prod, local/cloud, v1/v2) that swaps node labels, ports, payloads, or visibility in place. Modes are deployment shape, not alternative scenarios — flows are the scenarios.

Static diagrams have nodes + arrows + boundaries (no steps, no modes): hand-place SVG boxes inside grouping containers and draw labeled arrows between them. See references/static-and-boundaries.md.

Workflow when invoked

1. Capture intent

If the user uploaded a SOLUTION.md, README, OpenAPI spec, turbo.json, k8s manifests, or an Argo Workflow YAML, read it first. Extract service names + tech + ports, deploy modes, named operations (→ flows), and the chain of internal calls per operation (→ steps). Then ask only the gaps:

• What system are we drawing, and who's the audience?
• (Interactive) Which flows? Any mode toggle (dev/prod, local/cloud)?
• (Static) Which groupings matter — cluster, namespace, region, MF zone?

2. Plan the topology first

Sketch which nodes exist, where they sit, and which flows connect them before writing code. Avoid wire crossings — the single biggest readability win. Heuristics: user on the far left (entry), datastores on the right (exit), the orchestrator/gateway in the middle; read-heavy services above, write-heavy below; one-shot jobs (seed, cron, Argo steps) tucked in a corner. Plan for a wide spread — use the whole canvas, not the middle third. See references/flow-design-patterns.md.

3. Build from the template

Copy the chosen template into the working directory and edit only the marked regions (each template's top EDIT THESE THINGS comment is authoritative). Don't reinvent the player, the SVG wire renderer, the side panel, the export toolbar, or the boundary primitives — they all work. Fill node lists from references/ra-stack-library.md (RA services) and references/component-library.md (generic services). After editing, search the file for {{ / [PROJECT NAME] to catch stray placeholders.

4. Validate before showing the user

• Does every flow's step sequence make narrative sense (step 1 sets up, last step delivers a result)?
• Is the canvas using the full width? If nodes cluster in the middle third, spread them out — wide beats cramped. Keep ≥12% horizontal gap between adjacent nodes.
• Do wires cross unnecessarily? Reposition nodes.
• (Modes) Pick the most-different node between modes (usually the datastore) and verify every mode-dependent field is filled (label, tech, port, payload, chips).
• (Static) Are legends/labels outside boundary boxes, and are arrows masked behind boxes (see static reference)?
• If puppeteer is available, screenshot to spot-check layout — references/screenshot.js.

5. Output the files

• Interactive → architecture.html and a companion architecture.md (components, flows step-by-step, mode differences) so the diagram is legible without opening the HTML.
• Static → architecture.html (the .md companion is optional for a pure snapshot).
• Save to the current working directory (on Claude.ai use /mnt/user-data/outputs/). Tell the user how to open it (xdg-open architecture.html) and that the ⋯ toolbar exports PNG/PDF.

RA stack bias

This skill is tuned for the rask platform. Reach for these node identities and groupings first — full copy-paste snippets (roles, icons, ports, mode-aware fields) are in references/ra-stack-library.md:

Cross-app communication (micro-frontends): when drawing the frontend, model the composition seam explicitly — events up, props down, shared bus, URL-as-state — and namespace remotes by team (@rask/web, @rask/viewer). See the repo's micro-frontends and turborepo skills for the underlying patterns.

Modes that fit RA: dev/prod, local/cloud-run, docker/k8s, v1/v2. A mode is only a mode if it swaps the same topology's labels/ports/payloads — if it changes which services exist or which protocols are used, it's a second system: build two diagrams.

Node roles & colors

Six roles, hardcoded as CSS variables. Pick one per node. Keep the count ≤ 6 — past that the legend becomes a colorblind nightmare. If two datastores differ (Redis + Postgres), use vector for both and distinguish by icon/label, not a 7th color.

Re-skin via assets/css-tokens.css (light theme + muted/corporate palettes).

Boundaries & grouping (mined from the static path)

Flat node lists can't show "these run inside the cluster" or "this is a separate security zone." The static template ships four boundary primitives — use them to capture RA topology nuance:

• Cloud region / Kubernetes cluster — large dashed rx=12 container (amber). Label top-left, outside the inner nodes.
• Security group / NetworkPolicy — dashed rx=8 (rose), transparent fill.
• Micro-frontend zone — a boundary around a team's host + remotes to show the composition seam.
• Message bus / event connector — a thin labeled bar (orange) in the gap between services (NATS / Dapr).

Full SVG recipes (z-order, masking arrows behind translucent boxes, spacing math, legend placement, summary cards) are in references/static-and-boundaries.md.

Export (both modes)

Every generated diagram has a collapsed ⋯ toolbar (top-right) → Copy (high-DPI PNG to clipboard), PNG (download), PDF (one-page, dark theme preserved). It uses pinned, SRI-hashed html2canvas + jsPDF from jsDelivr.

Caveats to tell the user: clipboard needs a user gesture + secure context (https / file:// / localhost); offline, the export buttons no-op (CDN unreachable) but the diagram still renders; PDF is a rasterized PNG (not selectable text). The interactive diagram exports a snapshot of the current step — set the step/mode/theme first, then export.

Conventions (quick reference)

• Payloads (interactive side panel): realistic but trimmed — show the shape, omit boring fields. 4-space indent. If a step differs by mode, use payloadDev/payloadProd (or your mode keys); otherwise one payload.
• Chips: ≤3 short metadata badges per step. Latency (~150ms, 5-30s) auto-gets a stopwatch icon; size/count (768 dim, 38 loaded) a database icon.
• Naming: flow keys snake_case (htr_ingest, rag_query); flow display "Title Case (METHOD /route)"; node data-id short snake_case (orch, ray, nats); mode keys snake_case (dev/prod).

Common pitfalls

• </script> in a payload breaks the page. A payload template literal containing </script> (or </style>) closes the main script block. Escape as <\/script>.
• Don't script template edits by anchoring on bare tag names. Edit the regions by hand. Several tags recur (there are two <style> blocks; title/header text appears in both the head and the body), so a build script doing text.index("<header>") or a regex like <header>…</header> can match the wrong occurrence and silently delete the <style> block — leaving an unstyled, dead page. If you must automate, anchor on the unique {{…}} placeholders or class selectors (.stage, .flowtabs, .legend), not on tag names.
• Cramped / narrow diagrams. The most common complaint. There's no hard node cap — the only number is a ≥12% horizontal-gap spacing rule (not a node count). Spread nodes across the full width, scale them up, and split a sprawling system into per-area diagrams ("ingest" vs "serving") rather than squeezing everything in.
• Too many flows. >6 flows clutter the tab bar; 3–6 is the sweet spot. Group read vs write flows into separate files if needed.
• Modes that aren't modes. If the toggle changes which services exist or the protocol, it's a second system — build two diagrams.
• Source node looks dead. If a step's source renders dimmed instead of active-from, the participant logic regressed — see references/flow-design-patterns.md → "Visual states".
• Wire crossings come from node placement, not code — swap node positions to fix.
• Static: arrows show through boxes. Component fills are translucent, so draw arrows first, then an opaque backing rect under each box (the static reference documents this masking trick) and keep legends outside boundary boxes.
• Wrong tool. If it must live inline in a markdown file, a Mermaid flowchart is simpler — this skill produces standalone HTML.

File reference

Built on MIT-licensed work (konraddzbik/architecture-diagram-skill for the interactive engine; Cocoon-AI/architecture-diagram-generator for the static/export path), combined and RA-tuned. See LICENSE.