System Atlas: Build Interactive Isometric Architecture Maps

System Atlas turns a single data file into two artefacts: a self-contained interactive isometric map of your architecture, and a generated text twin that lists decisions, structures, flows, and open questions by ID. It is for teams still shaping a system, where vocabulary and decisions are moving and you expect more than one round of feedback. If you need a static diagram for a pull request, reach for the architecture-diagram or excalidraw skill instead.

What it does

Atlas is a data-driven documentation pattern. You maintain data.mjs, which describes structures, flows, chapters, decisions, and questions. The build script renders that data into atlas.html, an explorable map with progressive disclosure, and SYSTEM.md, a text twin that mirrors the same content. The map supports hover to read, click to pin, going inside a structure for steps, moving data packets you can inspect, and chapters that reveal the system a few structures at a time. The text twin carries the decisions table, every structure, the flows, and the open questions by ID.

Both views rebuild from the same source. That is the point: you edit one file, rebuild, and republish at the same URL. The atlas sits beside a hand-written glossary (CONTEXT.md) and architecture decision records (adr/).

Use it when someone says "make an atlas", "map the system", "make the architecture explorable", "visualize the codebase so we can talk about it", or "a diagram I can click around". It also fits when an architecture discussion is generating a pile of open questions that need tracking across feedback rounds, or when you need to update an existing atlas after decisions change. It is a poor fit for static one-off diagrams, finished systems that only need a README, or a single diagram for a PR.

Before you start

You need Node.js, any recent version. The build uses only node:fs, node:path, and node:url, so there is no npm install step. You also need a static server for verification; the source names npx serve and python3 -m http.server as examples.

The skill is optional and installed on demand. Its path is optional-skills/creative/system-atlas. It is version 1.0.0, authored by Harshyt Goel and adapted by Nous Research, under the MIT licence. Supported platforms are linux and macos.

How to run

Start by creating an atlas home and copying the template, build script, and example data file into it. Then fill in the data and run the build.

mkdir -p <atlas home>/atlas
cp <skill>/assets/{template.html,build.mjs} <atlas home>/atlas/
cp <skill>/assets/data.example.mjs <atlas home>/atlas/data.mjs   # then fill it in
node <atlas home>/atlas/build.mjs   # writes ../SYSTEM.md and ../atlas.html

Every field of the data file is documented in assets/data.example.mjs. Read that file before you start editing; it is the reference for the shape of structures, flows, chapters, decisions, and questions.

Quick reference

The atlas has a small set of files with clear ownership. Only one of them is yours to edit.

File	Role	Edit it?
atlas/data.mjs	Single source of truth: structures, flows, chapters, decisions, questions, prose	Yes
atlas/template.html + atlas/build.mjs	Renderer + generator	Presentation only
atlas.html	Built atlas; republish at the same URL after every rebuild	No (generated)
SYSTEM.md	Built text twin	No (generated)
CONTEXT.md	Glossary, one line per noun	By hand
adr/	Hard-to-reverse decisions	By hand
research/	Deep-dive evidence	Append-only

Procedure

Follow the order. Each step was earned by a correction the first time round, so skipping ahead tends to produce boxes that do not map to anything real.

1. Read the inputs before drawing. Read the vision doc, the repo's existing surfaces, and whatever prior art the user allows. Ask first, because they may forbid a branch or a source. If you will build on a framework, read its docs before drawing. For long docs, hand them to a subagent via delegate_task with your specific design questions and have it return a primer with gotchas and a "what it does not give us" list.
2. Discuss before drawing. Propose the structure in chat, mapped to the runtime's real primitives. Ask only the questions you cannot derive from the repo. Take defaults for the rest and say which defaults you took.
3. First atlas: the whole system. Copy assets/ into the atlas home, rename data.example.mjs to data.mjs, fill the data, build with node, and publish. Where the atlas home lives depends on the repo's docs policy, so ask before committing anything. Docs-friendly repos can use docs/{system}/atlas/ in-tree. Repos that commit only ADRs and CONTEXT.md should put the atlas, SYSTEM.md, and research/ in a git-ignored scratch dir and attach SYSTEM.md plus research to the spec issue when published. The source notes that committing the whole set once produced a 3,900-line docs PR and four review rounds reconciling three restatements of one design. You can load the design-md or architecture-diagram skill via skill_view for HTML-artifact guidance if useful, and read references/design-language.md for the visual rules either way.
4. Progressive disclosure. A whole system at once reads as noise. Use ten-ish chapters. Each chapter adds at most three structures and runs one small flow that only touches revealed structures. The last chapter shows everything with a flow picker. Unrevealed structures stay in the index, dimmed, with their chapter number. Panels are summary-first: one sentence, then Read more and Steps folded.
5. Shapes and labels. Letters on boxes are not enough. Give each role a shape and put a readable name label on the canvas under every structure. See design-language for the visual rules.
6. Text twin. CONTEXT.md is a glossary and nothing else: the nouns, one line each. ADRs are only for decisions that are hard to reverse, surprising without context, and the result of a real trade-off. These two are the in-tree pieces. SYSTEM.md is generated and research/ holds evidence; both live with the atlas, either in the scratch dir or docs/, per step 3. Do not open issues unless asked.
7. Feedback by question ID. Every question is Q- with a state: open (a string), resolved {q, r} (answer plus date), or routed {q, to} (handed to a named next step). Record the user's words. If they call something "not a question", drop it. If they say "I don't get this", explain with a concrete example before resolving. After each round: rebuild, republish, update memory.
8. Deep dives feed back. Research with subagents (delegate_task) against one shared brief: the interface we own, the requirements that separate candidates, a usage model for cost, and a fixed deliverable shape. Write a synthesis with a normalized cost/fit grid. Fold resolutions into the data as {q, r: '… (from the deep dive, date)'}. If the user rejects a proposal, sweep every file and rewrite. A banner on top of a stale section is not enough.
9. Keep it current. One source, rebuild and republish after every change, never hand-edit generated files, and leave a README.md in the docs folder explaining the set. The table for that README is in references/process-and-lessons.md.

Publishing

atlas.html is one self-contained file. There is no build step and no external assets beyond a Google Fonts stylesheet. Serve the folder with any static server (npx serve, python3 -m http.server) and hand over the URL, or let the repo's pages host serve the committed file. Keep one URL, republish it after every data change, and never keep a second copy. If you keep a stable published URL, put it in META.artifactUrl so SYSTEM.md links to it.

When not to use it

The source is explicit about exclusions. Do not use System Atlas for static one-off diagrams; use the architecture-diagram or excalidraw skill. Do not use it for finished systems that only need a README. Do not use it for a single diagram in a PR. The atlas is best when the system is new enough that vocabulary, decisions, and questions are still moving, and when there will be more than one feedback round.

Limits and gotchas

The source lists several pitfalls worth reading before your first build.

• Keep first and immediately after, otherwise you get quirks mode and mojibake arrows.
• The renderer rebuilds its whole scene on every draw. A stray render() in a hover handler detaches the element under the cursor and the browser stops synthesising clicks. The map looks perfect in a screenshot while nothing responds.
• Some in-app browsers render file:// as a static snapshot. Verify via a static server, not from disk.
• Never delete a question. Resolve it or mark it dropped, so IDs stay stable.
• After every decision, grep the outputs for stale words (pending, the old model name, the rejected design). The person reads everything.
• Large HTML/JS via shell heredocs is brittle. Use write_file and keep the data block JSON-serializable.

Verification

Before you hand the atlas over, check the build and the rendered page.

• node /atlas/build.mjs exits 0 and writes both SYSTEM.md and atlas.html.
• Syntax-check the built script (new Function(js)), then open the served page in a real browser at roughly 1280×800. Check a first chapter, a middle chapter, the last chapter, an inside view, and the light theme.
• Click a structure and confirm the panel says pinned and offers Go inside. Click a packet dot and confirm the payload opens.
• Every structure has one, what, how, a short label, a role kind, and its questions. Ghosts are marked. Chapters exist with per-chapter flows. The last chapter is the whole system.
• SYSTEM.md carries the decisions table, the question index with IDs and states, and the "how this file is maintained" footer.
• Project memory records the atlas URL, docs paths, locked decisions with dates, what the user rejected and why, and the next step.

What pairs with it

The source names two related skills: architecture-diagram and excalidraw. Both are better fits for static diagrams and one-off visuals. Use System Atlas when the architecture is still moving and you need a repeatable update loop, and keep the other two for the moments when a single picture is enough.

Upstream tags for this skill are architecture, diagrams, isometric, and documentation. The category is Creative.