inkboard/system-atlas

What it solves

System Atlas solves the problem of outdated and static architecture diagrams. Instead of a manual drawing that quickly becomes a "lie," it uses a single source of truth (a data file) to generate both an interactive isometric map and a detailed text-based documentation file (SYSTEM.md), ensuring that the visual and written descriptions of a system always remain in sync.

How it works

The tool operates on a simple build pipeline: a user or AI agent edits a data.mjs file containing the system's structures, flows, and decisions. A build script (build.mjs) then processes this data through a template to produce two outputs:

1. An interactive HTML map: A self-contained isometric visualization where users can hover over structures, click to see execution steps, and watch data packets move between components.
2. A text twin: A SYSTEM.md file containing decisions tables, flow tables, and a tracked index of open questions.

Who it’s for

It is designed for developers and architects who need to communicate complex system designs to others, as well as AI agents (via the skills CLI) that can automate the process of mapping a pipeline or updating architecture documentation based on repository changes.

Highlights

• Progressive Disclosure: Organizes the system into "chapters" to prevent information overload, revealing structures gradually.
• to-the-point Visuals: Uses specific isometric shapes for different roles (brains, stores, tool decks, etc.) to make the map legible without a key.
• Inspectable Data Flows: Visualizes real requests as moving dots that can be clicked to reveal JSON payloads.
• Stable Question Tracking: Assigns stable IDs (e.g., Q-<code><n>) to open questions to track feedback and resolutions across multiple design rounds.
• Agent-Ready: Provided as a "skill" that teaches an AI agent the specific design language and process for creating and maintaining an atlas.