Architecture Map

Architecture Map

Produce / update <repo>/architecture-map/ — an interactive HTML-card + SVG viewer of the architecture (the Claude Design template), backed by a single data file the agent owns.

Family

Pipeline: architecture-audit (verified nodes/edges) → architecture-map (this — the interactive map) → architecture-grill (grow the map live while grilling a plan) → architecture-cleanup (mark dead/removable code red on the map) → architecture-improve (amber optimisation proposals). This skill maps how parts connect and what flows between them; dead-code / orphan detection lives in architecture-cleanup, not here.

When NOT to use

SKIP for a one-off static diagram or a text architecture summary — run architecture-audit directly. Reach for THIS skill only when you want a persistent, clickable map you revisit and plan on.

Two modes (same artifact)

• Kortlæg — audit an existing repo, fill the map.
• Planlæg — open the map, add proposed nodes/edges while discussing a change.

Procedure

A. Gather the data (Kortlæg)

1. Run the architecture-audit skill's Map phase (Phase 0 scout + Phase 1 parallel readers). You want the structured per-subsystem result, not the Markdown doc — each reader returns components (id, label, status, role, files path:line) and A --> B: label edges.
2. Transform that into the map data contract (references/map-schema.md): subsystems, nodes, edges. Set source: "audit" and stamp generatedAt with the current ISO time. For each node, write the node-card fields so a non-technical reader gets it:
   • label = a descriptive plain-language name (what it does), NOT the raw function name.
   • tech = the technical identifier (function / endpoint / file).
   • engine = the motor category (llm, image, db, … — see references/map-schema.md for the canonical 14-key enum; don't restate it here) + optional engineLabel for the specific name (e.g. "OpenRouter · Claude Sonnet 4.6").
   • input / processing / output = plain language. Derive input from the node's incoming edges, output from its outgoing edges, processing from role.
3. Write it as a temp fresh JSON: /tmp/arch-fresh.json.

B. Scaffold / update the folder

4. If <repo>/architecture-map/ does not exist, create it and copy the viewer assets:

   mkdir -p <repo>/architecture-map
   cp <SKILL_DIR>/assets/index.html <SKILL_DIR>/assets/elk.bundled.js <repo>/architecture-map/
   

   (The viewer renders nodes as HTML cards + SVG edges — the Claude Design template — and uses ELK for auto-layout. elk.bundled.js is the only bundled dependency; the viewer also pulls IBM Plex from Google Fonts and silently falls back to system fonts offline.)
5. Write/merge the data with the helper (preserves notes + proposed across re-audits):

   node <SKILL_DIR>/merge-map.mjs <repo>/architecture-map/map.js /tmp/arch-fresh.json > /tmp/map.js && mv /tmp/map.js <repo>/architecture-map/map.js
   

   (First run: map.js is absent, the helper treats existing as empty.)
6. Tell the user the open command: open <repo>/architecture-map/index.html. To preview the bare viewer before real data exists, copy the sample: cp <SKILL_DIR>/assets/sample-map.js <repo>/architecture-map/map.js. Opening index.html with no map.js shows a friendly empty-state instead of crashing.

C. Planlæg (grow during planning)

• When discussing a feature/refactor, edit map.js directly: add nodes/edges with proposed: true and status: "proposed", or add notes to existing nodes. Re-running Kortlæg later will NOT wipe these — merge-map.mjs keeps them by id/key.

Verification

• After write, confirm window.MAP_DATA is present and the JSON parses by round-tripping through the helper: node <SKILL_DIR>/merge-map.mjs <repo>/architecture-map/map.js /tmp/arch-fresh.json >/dev/null && echo OK.
• Confirm every node has an engine from the category enum and plain-language input/processing/output (the viewer falls back to other ⚙️ + role if missing).
• Open index.html, confirm nodes render (icon + motor badge) and the console is clean.

Notes

• file:// only (no server). Data lives in map.js (a window.MAP_DATA = {…} wrapper) because browsers block fetch() of JSON over file://.
• Never hand-edit the vendored elk.bundled.js. The look (cards, colours, panel, edges) lives entirely in index.html — edit there to evolve the design template.
• <SKILL_DIR> = this skill's canonical dir skills/architecture-map/.