inkboard/system-atlas

What it solves

System Atlas solves the problem of outdated and static architecture diagrams. Instead of manual drawings that quickly become "lies," it provides a single source of truth (a data file) that automatically generates both an interactive, isometric visual map and a structured text document (SYSTEM.md). This ensures that the visual and textual representations of a system's architecture always agree and can be updated with a single edit.

How it works

The tool uses a data-driven approach to map systems:

1. Single Source of Truth: All system structures, flows, and decisions are defined in a data.mjs file.
2. Generation: A build script (build.mjs) processes this data to produce two outputs: a self-contained atlas.html file for interactive exploration and a SYSTEM.md file for documentation.
3. Interactive Map: The resulting HTML map allows users to hover over structures to read them, click to pin them, and dive into execution steps. It features "progressive-disclosure chapters" to prevent information overload by revealing the system in small, manageable chunks.
4. Agent Integration: It is designed as an "agent skill," meaning AI agents can be triggered to create, update, or walk through the atlas based on plain language requests.

Who it’s for

It is for developers and architects who need to communicate complex system designs to others, track architecture decisions and open questions by stable IDs, and maintain documentation that stays in sync with the actual codebase.

Highlights

• Interactive Isometric Map: A zoomable, pannable HTML map with role-specific shapes for different system components (e.g., brains, stores, gates).
• Text Twin: Automatically generates a SYSTEM.md file containing decision tables, flow tables, and a question index.
• Progressive Disclosure: Organizes the system into chapters that reveal structures and data flows incrementally.
• Inspectable Data Packets: Visualizes real requests as moving dots that can be clicked to inspect JSON payloads.
• Question Tracking: Uses stable IDs (Q-<code><n>) to track open and resolved architecture questions through feedback rounds.