architecture-diagram

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: architecture-diagram
description: This skill should be used when a system design needs a diagram — "draw the architecture", "diagram this system", "show the components", "make an architecture/infrastructure/topology diagram", or visualizing boxes-and-arrows, data flow, regions, or failure paths for a design. It generates a self-contained dark-theme HTML + SVG diagram (with PNG/PDF export). Use it whenever the `system-design` orchestrator or a building block reaches the "draw it" step, even if the user doesn't say "diagram".
---

# Architecture Diagram

Turn a stabilized design — a list of components and the connections between them —
into a polished, self-contained **HTML + SVG** diagram. Components are boxes,
arrows are communication/data flow, dashed boundaries are regions or trust zones.
This is the diagramming engine for the whole plugin; the orchestrator and building
blocks hand off here when it's time to draw.

> Self-contained by design: one HTML file with inline SVG and CSS, a system
> monospace font (no web-font fetch), and **no dependency to render** — it draws
> fully offline. The *only* external calls are two pinned, SRI-protected CDN
> scripts that power the **optional** PNG/PDF export; remove them and the diagram
> still renders — only the export buttons are lost.

## When to reach for this
At step 3 (high-level design) and step 6 (deep-dive) of the reasoning loop, and
any time a design is clear enough to draw: the component list and their
connections are known. Also for failure-path diagrams (step 5) — showing a
degradation flow is part of the design.

## When NOT to
Before the design has stabilized — don't draw boxes that aren't yet justified
(that's failure mode #7). A quick ASCII sketch in the conversation is fine for
early thinking; render with this skill once the components have earned their place.

## How to build a diagram

1. **Gather the spec** from the design: the list of components (each with a type),
   the directed connections (with protocol/label), and any region/boundary
   groupings. The `system-design` design-doc already produces this.
2. **Copy the template** `assets/template.html` to a working file. It carries the
   dark theme, grid background, fonts, the export toolbar, and the summary-card
   layout — keep those intact.
3. **Map each component to a semantic type** (color) using the table below.
4. **Place boxes and draw arrows** following the layout/spacing rules in
   `references/design-system.md` (draw arrows before boxes so they sit behind;
   mask arrows behind semi-transparent fills; keep ≥40px vertical gaps; legends
   go outside boundary boxes).
5. **Label the flow** — number arrows to show request order; use dashed arrows for
   async/replication/fallback; dashed boundaries for regions and security groups.
6. **Fill the summary cards** with the key decisions/trade-offs (ties to the
   design doc), update the title/footer.
7. **Open it**: `open <file>.html` to view; the toolbar exports PNG/PDF.

## Semantic colors (map components to types)

These align with how the building blocks think about a system.

| Component type | Fill (rgba) | Stroke | Used for |
|---|---|---|---|
| Frontend / client | `rgba(8,51,68,0.4)` | `#22d3ee` | web/mobile clients, edge |
| Backend / service | `rgba(6,78,59,0.4)` | `#34d399` | app/API services, workers |
| Database / store | `rgba(76,29,149,0.4)` | `#a78bfa` | SQL/NoSQL, object store |
| Cache | `rgba(8,51,68,0.4)` | `#38bdf8` | Redis/Memcached, CDN cache |
| Message bus / queue | `rgba(251,146,60,0.3)` | `#fb923c` | Kafka, SQS, queues, streams |
| Cloud / managed | `rgba(120,53,15,0.3)` | `#fbbf24` | managed services, regions |
| Security / auth | `rgba(136,19,55,0.4)` | `#fb7185` | gateways, auth, firewalls |
| External / generic | `rgba(30,41,59,0.5)` | `#94a3b8` | third parties, DNS |

Full styling, arrow markers, masking, spacing, and legend rules are in
`references/design-system.md`.

## Output rules
- One self-contained `.html` file: