How to use AppGraph
AppGraph collects the architecture-graph suites generated for each project and renders them with one shared, collision-free graph engine.
Browse apps
The home page lists every ingested project as a card — name, stack, node counts and generation date. Click a card to open its overview.
Open a graph
Each app has three graphs: File Architecture (the source tree), System Design (runtime topology in five zones) and Flow Graph (the five most significant flows). Layout is computed by ELK — arrows never cross nodes or labels.
Read the legend
Every graph page has a collapsible legend documenting the visual conventions used on that page — see the reference below for the full list.
Click nodes for details
Clicking (or focusing and pressing Enter on) any node slides in a detail panel: role, imports, exports, line counts, reverse dependencies, config keys, connections and confidence. Esc closes it.
Use search
The search box on a graph page dims non-matching nodes and scrolls the first match into view. The global search on the home page spans every node of every app and jumps straight to the right graph with the node highlighted.
Explore the cluster
The Cluster page shows all apps as an Obsidian-style force graph, connected through the technologies they share. Hover to highlight a neighbourhood, click an app to open it.
Legend reference
Every visual convention used across the three graph types.
| Solid border | Verified component — found directly in the codebase. |
|---|---|
| Dashed border | External system or inferred component (evidence listed in footnotes). |
| Double top border | Directory (file-architecture tree). |
| Double bottom border | Database / persistent store. |
| Two top lines | Load balancer, proxy or dispatcher. |
| Accent dot, top-left | Entry-point file. |
| Grey fill, grey text | Generated / compiled artifact. |
| Colored corner chip | File-type tag (TS, JSON, MD… — frozen palette). |
| Stadium, accent fill | Flow start / end. |
| Diamond | Decision — branch edges labeled with the outcome. |
| Parallelogram | Data object. |
| Dark-red fill | Error state; dark-red edges are error paths. |
| Dashed edge | Data flow. |
| Arrowheads both ends | Bidirectional (request/response) link. |
| Dashed band with small-caps title | Zone — External/Client, Edge, Application, Data, External Services. |
Adding a new app
Generate the 4-file graph suite for the project (via the /sys-design skill), then point the ingestion script at the folder:
npm run ingest -- "C:\path\to\project\graph-myapp"
Suites generated with spec v2 embed a canonical #graph-data JSON block and ingest losslessly. Older suites are parsed best-effort from their embedded JS arrays. The script writes data/apps/<slug>/ — edit app.json there to set tags, linked apps or the accent color, then restart the dev server. New apps appear on the home page and in the cluster automatically.