architecture-diagram-skillSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: architecture-diagram
version: 1.4.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 "—".) A step with `from === to` renders as a loop above that 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, **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. 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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.