jakefassora-hc/ai-scope

1. Overall shape

- This is a local, read-only Python web app that inventories your Claude-related workspace and git portfolio, then serves it in a browser UI at 127.0.0.1:8765.

- The architecture is split into a thin server/entrypoint, a set of filesystem/process/git scanners, a graph/tree layer for visualization, and a browser frontend in templates/ + static/.

2. Runtime boundary

- app.py is the entrypoint that wires the subsystems together and exposes the UI/API.

- The server is intentionally localhost-only and does not call external services; all data comes from the local machine.

3. Primary data sources

- The app reads from several local sources:

- ~/.claude/ and CLAUDE.md files for Claude context.

- The home directory for browsing files.

- ~/projects/ plus active git worktrees for repository state.

- The local process table for running claude CLI processes.

- Plan documents under docs/superpowers/plans/ and similar .md / .html artifacts for the map view.

4. Scanner layer

- The scope/ package is organized around dedicated scanners:

- config_scanner.py for Claude config/context files.

- file_browser.py for directory traversal and file access.

- git_scanner.py for repo/worktree discovery and status.

- process_scanner.py for live claude process discovery.

- plan_scanner.py for plan-document discovery.

- Each scanner produces structured records that are later merged into the UI model rather than rendering directly.

5. Safety and policy boundary

- exclusions.py enforces a hard deny list for sensitive paths and file types.

- redact.py strips secrets before any file content is sent to the browser.

- This means the architecture has a clear disk-to-server sanitization boundary: raw local files are inspected, filtered, and redacted server-side before any client sees them.

6. Insights and rules

- rules.py and likely the scanner outputs feed an Insights subsystem that identifies config rot and risky patterns.

- The README explicitly calls out stale CLAUDE.md files, abandoned worktrees, and at-risk unpushed work as the main derived signals.

- token_estimator.py adds a cost model for Claude context files so the UI can show token impact without querying an LLM.

7. Structure-building for the UI

- tree_builder.py assembles hierarchical file/repo structures for browsing and navigation.

- graph_builder.py builds the higher-level portfolio map used by the Map tab, turning repositories, phases, and plan files into a visual graph model.

- This is the main aggregation boundary: raw scanner results become a browsable tree and a visual graph.

8. Frontend composition

- templates/index.html and templates/prototype.html define the browser shell.

- static/app.js contains the client-side interactions for switching tabs, loading content, and driving the D3 visualization.

- static/style.css provides the presentation layer; the frontend is mostly a thin renderer over server-provided data.

9. Map visualization flow

- The Map tab is a dedicated visualization pipeline: repo and plan metadata are scanned, normalized into graph/tree structures, and then rendered in the browser as a D3-powered Circles/Sunburst view.

- Clicking a .md or .html plan file opens it inline, so the browser can move from portfolio-wide structure to document-level detail without leaving the app.

10. Main user-facing subsystems

- The UI is organized into five operational views:

- Claude Context: Claude config and context files with token estimates.

- File Browser: controlled access to the local home tree.

- Processes: live claude process inventory and working directories.

- Git State: repository and worktree status.

- Map: portfolio visualization of repos/phases/plans.

- These are separate presentations of the same underlying local inventory, not separate backends.

11. Test boundary

- tests/ mirrors the core modules one-for-one, which suggests the architecture is intentionally decomposed and testable at the scanner/transform level.

- The presence of test_api_graph.py indicates the graph output is validated as a first-class API artifact, not just a UI detail.

12. Architecture summary for a diagram

- A good diagram would show: local filesystem + process table + git repos on the left, feeding scanner modules in the middle, then policy/redaction + aggregation (tree/graph/rules/token estimates), then a local Python server, and finally the browser UI tabs and D3 map on the right.

- The key design principle is that the app is a read-only local observability tool: it observes, filters, and visualizes, but never mutates user data.