Architecture Map

Architecture Map

Produce / update /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.

1. 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.

1. Write it as a temp fresh JSON: /tmp/arch-fresh.json.

B. Scaffold / update the folder

1. If /architecture-map/ does not exist, create it and copy the viewer assets:

``bash mkdir -p /architecture-map cp /assets/index.html /assets/elk.bundled.js /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.)

1. Write/merge the data with the helper (preserves notes + proposed across re-audits):

``bash node /merge-map.mjs /architecture-map/map.js /tmp/arch-fresh.json > /tmp/map.js && mv /tmp/map.js /architecture-map/map.js ` (First run: map.js` is absent, the helper treats existing as empty.)

1. Tell the user the open command: open /architecture-map/index.html.

To preview the bare viewer before real data exists, copy the sample: cp /assets/sample-map.js /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 /merge-map.mjs /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.

• ` = this skill's canonical dir skills/architecture-map/`.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MartinPLarsen
• Source: MartinPLarsen/claude-architecture-skills
• License: MIT

Install and usage instructions live in the source repository linked above.