--- name: architecture-canvas description: > Turn any system architecture into an interactive, pannable/zoomable canvas diagram (dark by default with a light switcher, JetBrains Mono, plane-coloured bands, click-to-isolate focus, PNG export) — the "architecture canvas" style — and optionally publish it to artifact.cafe for review. Use whenever the user asks for an architecture diagram, system overview, "canvas" of a codebase or platform, a visual map of services/layers/planes, or wants a diagram "in the architecture-canvas style" — whether the input is a codebase to explore, an architecture doc, or a verbal description. Prefer this over hand-writing SVG/HTML diagrams or Mermaid when the result should be an explorable, publishable artifact. --- # Architecture Canvas Produce an interactive architecture diagram as a single self-contained `index.html`: a canvas viewer where drag or two-finger scroll pans and pinch zooms, plus click-to-isolate focus with a readout panel, keyboard shortcuts, shareable view URLs, a dark/light switcher, and 2× PNG export. Ordinary vertical scrolling must never change the canvas scale. You never write viewer code — you author a **scene** (pure data: planes, bands, boxes, edges, labels) and the bundled scripts assemble and check it. The pipeline: ``` understand the architecture → write scene.js → validate → build → (publish) ``` ## Step 1 — Understand the architecture first The diagram is only as good as the analysis. Before any drawing, produce a short **architecture brief** (in your working notes, or shown to the user if they should confirm it): - **Planes/layers** (4–7), in causal top-to-bottom order — who acts, through what surface, on what abstractions, executed where. Name each plane and its one-line role. - **Components** (15–25 total): for each — its plane, whether it's an *owned abstraction* (dashed) or *swappable infra / app surface* (solid), 1–2 facts, and the one non-obvious thing about it (this becomes the italic footnote). - **Flows** (10–20 meaningful edges): the main pipeline, plus feedback loops and cross-cutting flows. - **The thesis**: a 3–5 word pipeline strapline (e.g. `browse → price → order → fulfil → learn`) and a one-sentence subtitle. Where the architecture comes from depends on what you're given: - **A codebase** — explore it (package layout, entry points, deploy configs, existing docs/READMEs). Spawn an Explore agent for large repos. - **An architecture doc** — read it, but verify surprising claims against the code when both exist. - **A description** — use it as-is; ask only if the layering is genuinely ambiguous. ## Step 2 — Author the scene Read `references/scene-format.md` (data model, coordinate math, layout recipe) and skim `examples/shoply-scene.js` (the canonical example scene). Then write a `scene.js` next to your intended output defining the nine constants: `W, H, PLANES, BANDS, BOXES, EDGES, TEXTS, SWATCHES, CHIPS`. Layout mechanically, top to bottom, using the recipe's numbers — title block at the top, ~5 bands (merge related planes into a neutral multi-column band rather than stacking 7 thin ones), generous boxes that fill their band's width, edges routed orthogonally with long feedback flows in the side gutters, footnotes at the bottom, then set `H`. Write `scene.js` inside the artifact folder (next to the future `index.html`) so nothing strays outside the publishable directory, and write its comments about *this* architecture — don't carry over the example's Shoply-specific commentary. ## Step 3 — Validate, then build ```bash node /scripts/validate.js scene.js ``` Fix every ERROR (dangling ids, boxes outside bands, overlaps, text overflow) and take WARNings seriously — they're usually real. Re-run until clean, then: ```bash node /scripts/build.js --scene scene.js --out /index.html \ --title "Acme — platform architecture" \ --kicker "ACME — PLATFORM ARCHITECTURE" \ --sub "ingest → process → serve" \ --slug acme-architecture ``` `--sub` is the plate strapline (small HTML, `` for the stage names). Output into its own folder with `index.html` at the root — that folder is the publishable artifact. If browser tooling is available (Playwright MCP, `open`), load the file once and screenshot it — check nothing collides and the story reads top-to-bottom. Don't skip validation in favour of eyeballing; do both when you can. ## Step 4 — Publish to artifact.cafe (when the user wants it shared) If the user asked to publish/share/review the canvas, invoke the `artifact-cafe` skill and follow it — it handles login/workspace choice, `--title`/`--notes`, and returns the review URL. Point it at the folder containing `index.html`. If the user didn't ask, offer it as a follow-up instead of publishing unprompted. ## Quality bar - Ownership semantics stay honest: dashed = owned abstraction, solid = swappable infra or app surface. This distinction is the diagram's argument. - Adjacent columns get well-separated hues; every plane colour comes from the recommended list in the reference. - Readout `about` text is written for a newcomer — one crisp sentence per box. - The diagram is an orientation map, not an inventory: fewer, better boxes.