architecture-map

# Architecture map

Turn a repository into a place you can walk around: an isometric city where every building is a real subsystem sized by its real weight, every line is a call path that exists in the code, and every moving dot is a payload the app actually ships.

## The one rule

**Prose, groups and flows are authored. Counts, coverage and geometry are measured.**

No scanner can say what a subsystem is *for*, and no human can keep file counts honest. Every good property of this page falls out of that line — including the fact that it does not rot, because "unmapped files" is only meaningful once a human has claimed the rest.

Do not try to generate the authored half mechanically. Read the code and write about it. That is the work, and it is why this is a skill rather than a codegen script.

## Before you start

Read `references/authoring.md`. It has the voice, the archetype vocabulary, and worked examples of good and bad node prose. Read `references/geometry.md` only if you need to hand-tune footprints or edge routes.

## Step 1 — Detect

Answer these from the repo. Do not ask.

| Question | Where to look |

|---|---|

| Framework and router | `package.json`, `app/` vs `pages/` vs `src/routes/`, `vite.config`, `next.config`, `remix.config` |

| Design tokens | global stylesheet for `--*` custom properties; `tailwind.config`; any `tokens`/`theme` module |

| Dark mode mechanism | `.dark` class, `[data-theme]`, or `prefers-color-scheme` |

| Test runner | `package.json` scripts, `vitest.config`, `jest.config` |

| Package manager | lockfile |

| Monorepo | `workspaces`, `pnpm-workspace.yaml`, `turbo.json` |

| Existing map | the map folder's `snapshot.json`; if present, this is an **update** |

Then run the proposer to get a first read of the shape. It lives beside this file, not in the repo you are mapping, so resolve its path first:

> **`SKILL_DIR`** — the absolute path of the directory containing *this > SKILL.md*, which your harness reported when it loaded this file. It differs > per tool (`~/.claude/skills/architecture-map`, > `~/.codex/skills/architecture-map`, `~/.agents/skills/architecture-map`, a > plugin cache, or a project-local `.claude/skills/…`). Substitute the literal > path; do not rely on an environment variable.

```bash

node "$SKILL_DIR/scripts/propose-coverage.mjs" --root . --target 22

```

It returns directory clusters with file counts and line totals, plus suggested groups. Treat it as a draft, not an answer — it knows where code *is*, not what it *does*.

## Step 4 — Author the graph

This is the real work. Write the map folder's `map.md`: frontmatter, then the groups, the nodes, the edges, the flows, the intro and the coverage globs, each as a section, in the shapes `$SKILL_DIR/assets/core/types.ts` defines for `Group`, `ArchNode`, `ArchEdge` and `ArchFlow`.

**Groups** — 4–7 neighborhoods, named the way the team talks: "Entry & control", "The pixel pipeline", "Outside world". Not "utils" and "lib".

**Nodes** — aim for 15–25. For each, *read the actual files* and write:

- `whatItDoes` — one or two sentences, plain language, no jargon

- `howItsBuilt` — the interesting decision, not a dependency list

- `role` — a short noun phrase for the flow captions: "the session gate"

- `files` — real paths a reader can open

```ts

const { archetype, params } = deriveArchetype(measure)

const height = deriveHeight(measure)

const footprints = packLayout(inputs, GROUPS.map((g) => g.id))

```

Keep a hand-written footprint if a human already tuned one — the merge prefers the authored value.

**Edges** — real call and data paths only. If you cannot point at the code that makes the call, do not draw the line. Add `via` waypoints when a route would otherwise cut through a building.

**Flows** — 3–6, each an ordered list of edge ids with a payload name. These are the page's verbs and the first thing a newcomer presses. Find them by tracing real paths: sign-in, the main create/read loop, the expensive background job.

## Step 6 — Verify, then be honest

Then tell the user plainly:

> The geometry and measurements are correct — they are derived. **The prose is > a first draft.** I read the code, but "what this subsystem does" is where a > single pass is weakest. Edit the map folder's `map.md` and regenerate the viewer; nothing else needs to > change.

Do not leave mediocre writing behind a confident-looking map without saying so.

## Updating an existing map

If `snapshot.json` exists, this is an update. **Never clobber authored content.**

## Scale

Past ~25 buildings the map stops being readable. The proposer folds the smallest siblings into a parent node that owns the wider glob — the partition stays total, only the drawing simplifies. If a repo genuinely needs more, map one package at a time rather than shrinking everything.

## What not to do

- Do not draw an edge you cannot trace to a call in the code.

- Do not set prose in the mono face. Monospace is for codes and paths.

- Do not import a host repo's `Button` or `Dropdown` — the map ships its own.

- Do not hand-write file counts. That is what the scanner is for.

- Do not invent flows that sound good. A flow nobody can follow in the source is a lie the page tells confidently.

# Portable core

Pure, dependency-free, and framework-agnostic. Copy verbatim — these files are the same in every repo the map is installed into.

| File | Role |

|---|---|

| `iso.ts` | The 2:1 dimetric projection, Manhattan edge routing, polyline arithmetic, scene bounds |

| `archetypes.ts` | Building shapes: box faces, slab stacks, fin rows, port and chip anchors |

| `layout.ts` | Height, archetype and footprint **derived** from the measurement, plus the district packer |

| `types.ts` | The graph schema — the contract the authored table fills in |

| `districts.ts` | Neighborhood plots, derived from their members' bounding box |

| `routes.ts` | Every edge as a drawn line, with arc lengths precomputed |

| `scene.ts` | Paint-ordered scene, floor grid, camera fit and zoom |

| `program.ts` | A flow turned into a beat timeline: dwell, travel, dwell, loop |

Nothing here touches the DOM, so all of it is unit-testable without a renderer.

# Authoring the graph

The measured half takes care of itself. This is about the half that does not.

## Voice

Write like someone explaining the system to a new colleague at a whiteboard — concrete, unhurried, and willing to say why. The reader is technical but has never seen this repo.

**Say what a thing does before what it is made of.** "Turns a collection of photos into an MP4, entirely in the browser" beats "React component using WebCodecs".

**Name the interesting decision.** The `howItsBuilt` field is not a dependency list — it is the one choice a reader would otherwise wonder about.

> Good: "Encoding happens on the main thread on purpose: `VideoEncoder` holds > GPU resources a worker cannot share, and the copy cost of shuttling frames > across a worker boundary is larger than the parallelism buys." > > Bad: "Built with WebCodecs, React and TypeScript."

**No filler.** "Handles various utilities and helper functions" describes nothing. If a module resists description, that is a finding about the module — say what it actually contains.

**Prose is prose.** Sentences go in the body face. The mono face is for codes, file paths and chips. A paragraph of monospace is a punishment.

## Fields, and what belongs in them

| Field | Length | What it is for |

|---|---|---|

| `name` | 1–3 words | What the team calls it out loud |

| `code` | 2 letters | The roof chip at rest. Unique |

| `role` | a noun phrase | Reads inside a flow caption: "at Auth & allowlist — *the session gate*" |

| `whatItDoes` | 1–2 sentences | Plain language, no jargon |

| `howItsBuilt` | 1–2 sentences | The decision worth knowing |

| `files` | 3–6 paths | Real, openable, representative — not exhaustive |

| `stack` | names | Libraries and services. Names, not versions |

Mark a word with `[[double brackets]]` to have the panel highlight it. Use it once or twice per node, on the term a reader would search for.

## The archetype vocabulary

Shapes carry meaning. `deriveArchetype` picks by default; override only when the derivation is clearly wrong about a module you know well.

- **fin-row** — a collection whose *count* is the point. Nine asset editors, twenty route handlers. Reads as a comb.

- **tower** — a deep, single-purpose pile. One big file doing one hard thing.

- **slab-stack** — something that accreted in layers. Big, old, load-bearing.

- **cube** — an ordinary subsystem. Most things.

- **low-slab** — a plate on the floor. Small libraries, and the outside-world services that are not code in this repo at all.

## Groups

Four to seven, named the way people talk. "Entry & control", "The pixel pipeline", "Server & data", "Outside world". Never "utils", "lib", "misc" — those are directory names, not places.

Order matters: the legend lists groups in order and the map packs them in that order, so reading down the rail walks you across the city. Put the entry point first and the outside world last.

## Edges

An edge is a claim that A calls B, or data moves from A to B. **If you cannot point at the line of code that makes it happen, do not draw it.** A plausible arrow is worse than a missing one, because the map's whole authority is that everything on it is real.

- `call` — a function call, a request, a route dispatch

- `data` — something is written or read

- `support` — wiring that matters but is not the story. Drawn thin

- `retry` — an error or fallback path. Drawn dashed

Add `via` waypoints when the default elbow would cut through a building. One waypoint usually fixes it; see `geometry.md`.

## Flows

Three to six. A flow is an ordered list of edge ids, plus one payload noun. These are what a newcomer presses first, and what the page is *for*.

Find them by tracing real paths through the code:

- how someone gets in (sign-in → session → first screen)

- the main loop (create → edit → save → read back)

- the expensive one (the background job, the export, the pipeline)

- the one that surprises people (the retry path, the cache warm)

Name them as verbs from the user's side — "Export", "Sign in", "Media in" — not as component names.

The payload is the thing that travels: "session cookie", "H.264 frames", "config patch". It appears beside the flow in the rail and in every step caption, so it should be a noun someone could point at.

## Worked example

```ts

{

id: 'auth',

code: 'AU',

name: 'Auth & allowlist',

role: 'the session gate',

group: 'entry',

whatItDoes:

'Decides who gets in. Sign-in is [[Google OAuth]] only, and every request ' +

'for a gated route is checked before the page is built.',

howItsBuilt:

'The allowlist is its own module rather than a helper inside the auth ' +

'config, because it is policy rather than wiring — a pure rule about ' +

'strings, worth testing without standing up the whole framework.',

files: ['src/auth.ts', 'src/proxy.ts', 'src/lib/allowlist.ts'],

stack: ['next-auth v5', 'Google provider', 'JWT sessions'],

}

```

Note what it does *not* say: no file counts (measured), no footprint (packed), no height (derived).

# Mounting the map

The map is one default-exported React component taking one `ArchitectureData` prop. Everything below is about getting a route to render it.

## Next.js — App Router

```

src/app/~/architecture/page.tsx

```

```tsx

import ArchitectureMap from '@/architecture/components/ArchitectureMap'

import '@/architecture/components/keyframes.css'

import { ARCHITECTURE } from '@/architecture/graph'

export const metadata = {

title: 'Architecture',

robots: { index: false, follow: false },

}

export default function Page() {

return <ArchitectureMap data={ARCHITECTURE} />

}

```

The `~` is a literal directory segment, not a route group — it sorts internal tools away from real routes and reads as "not part of the product".

Note the components are client components (`'use client'` is already on them); the page itself can stay a server component.

## Next.js — Pages Router

`src/pages/~/architecture.tsx`, same body, with `next/head` for the robots tag.

## Vite / React SPA

Add a route in whatever router the app uses:

```tsx

<Route path="/~/architecture" element={<ArchitectureMap data={ARCHITECTURE} />} />

```

Import `keyframes.css` in the app entry. `'use client'` directives are inert here and harmless.

## Remix / React Router

`app/routes/~.architecture.tsx`, exporting the component as default. Load the graph module directly — it is static data, so no loader is needed.

## Astro

Wrap in a client island, because the map is fully interactive:

```astro

---

import ArchitectureMap from '../architecture/components/ArchitectureMap'

import { ARCHITECTURE } from '../architecture/graph'

---

<ArchitectureMap client:only="react" data={ARCHITECTURE} />

```

## Anything else, or no web app at all

If the repo has no React app to host a page — a Go service, a Python library, a CLI — the honest output is a standalone page. Bundle the components with esbuild into a single HTML file and commit it as `architecture.html`:

```bash

npx esbuild entry.tsx --bundle --minify --format=iife --outfile=bundle.js

```

The measurement script still runs in CI, so the drift counter keeps working; only the mounting changes. Say clearly that this is what you did and why.

## The stylesheet

`keyframes.css` defines the dash march along the active flow edge and the reduced-motion override. It must be imported exactly once, anywhere in the app's CSS graph. Everything else is inline styles from `theme.ts`, so there is no build-tool configuration to get wrong.

# Geometry

Only needed when the derived layout is wrong and you want to hand-tune it.

## The projection

A 2:1 dimetric isometric. One grid step along `gx` moves half a tile right and half a tile-height down; one step along `gy` mirrors it leftward; `z` lifts straight up.

```

toScreen(gx, gy, z) = { x: (gx - gy) * 24, y: (gx + gy) * 12 - z * 14 }

```

Integer grid coordinates are the authoring format. Fractions are legal everywhere — slab insets, fin pitches, edge lanes on half-cell offsets.

## Paint order

Buildings render in ascending `depthKey = gx + w + gy + d`. Footprints never overlap, so the rule is sufficient: a building can only occlude one whose front corner sits strictly behind its own.

Layer order on the canvas, and why:

1. **Floor grid** — under everything

2. **District plates** — with the floor, so a plot never covers what stands on it

3. **Edges** — under the buildings, so a payload reaching a facade disappears *into* the module. That is what reads as "entering"

4. **Buildings** — back to front

5. **Flags and step numbers** — last, because a marker a tower can bury is no marker

## Fixing an edge that cuts through a building

Edges route Manhattan-style: `gx` first, then `gy`, with an elbow inserted where they differ on both axes. To flip which way the elbow bends, supply the other corner as a waypoint:

```ts

{ id: 'auth-to-dash', from: 'auth', to: 'dashboard', via: [{ gx: 4, gy: -2 }] }

```

Waypoints are in grid space, and half-cell offsets are useful for running two edges in parallel lanes rather than on top of each other.

## Fixing a footprint

`packLayout` is deterministic shelf packing: it fills a row left to right until the next building would pass the target width, then starts a row behind it. Districts are packed the same way one scale up, in `GROUPS` order.

To override, write the footprint into the node and skip the merge for it. Rules to respect:

- Footprints must not overlap — the district derivation and the painter's algorithm both assume it

- Leave at least one cell between buildings, or their strokes touch

- A district's plate is derived from its members' bounding box plus padding, so moving a building moves the plot automatically

## Sizes

Height is a log ladder on lines of code, clamped 1–6: a module ten times bigger is not ten times taller, or one subsystem becomes a skyscraper next to a village. Footprint comes from archetype — a fin-row is as wide as it has fins, a tower is 2×2 regardless of how tall it is.