# Architecture Map

> Build a living, interactive HTML map of a project's architecture that lives inside the repo, opens via file://, and grows while you plan. Use to get a realistic overview of an existing platform, see what data flows between parts, and preview the impact of a feature/refactor before building it. Reuses the architecture-audit engine to gather verified nodes/edges. SKIP for a one-off static diagram o…

- **Type:** Skill
- **Install:** `agentstack add skill-martinplarsen-claude-architecture-skills-architecture-map`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MartinPLarsen](https://agentstack.voostack.com/s/martinplarsen)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MartinPLarsen](https://github.com/MartinPLarsen)
- **Source:** https://github.com/MartinPLarsen/claude-architecture-skills/tree/main/architecture-map

## Install

```sh
agentstack add skill-martinplarsen-claude-architecture-skills-architecture-map
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
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 `/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.)
5. 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.)
6. 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](https://github.com/MartinPLarsen)
- **Source:** [MartinPLarsen/claude-architecture-skills](https://github.com/MartinPLarsen/claude-architecture-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-martinplarsen-claude-architecture-skills-architecture-map
- Seller: https://agentstack.voostack.com/s/martinplarsen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.