# jakefassora-hc/ai-scope architecture

> Architecture diagram of the GitHub repository jakefassora-hc/ai-scope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jakefassora-hc/ai-scope
- Repository: https://github.com/jakefassora-hc/ai-scope

## Overview

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.

Main entry points: [`scope/graph_builder.py`](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/graph_builder.py) (Graph builder), [`scope/config_scanner.py`](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/config_scanner.py) (Config scan), [`scope/rules.py`](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/rules.py) (Insights rules), [`scope/tree_builder.py`](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/tree_builder.py) (Tree builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_py["app.py<br/>entrypoint server<br/>[app.py]"]
end

subgraph group_inputs["Local Inputs"]
  node_local_fs[("Local files<br/>filesystem source")]
  node_git_sources[("Git repos<br/>git source")]
  node_process_table[("Process table<br/>os source")]
end

subgraph group_scanners["Scanners"]
  node_config_scanner["Config scan<br/>scanner<br/>[config_scanner.py]"]
  node_file_browser["File browse<br/>scanner<br/>[file_browser.py]"]
  node_git_scanner["Git scan<br/>scanner<br/>[git_scanner.py]"]
  node_process_scanner["Process scan<br/>scanner<br/>[process_scanner.py]"]
  node_plan_scanner["Plan scan<br/>scanner<br/>[plan_scanner.py]"]
end

subgraph group_core["Core Processing"]
  node_exclusions["Exclusions<br/>policy filter<br/>[exclusions.py]"]
  node_redact["Redaction<br/>sanitizer<br/>[redact.py]"]
  node_rules["Insights rules<br/>analysis rules<br/>[rules.py]"]
  node_token_estimator["Token cost<br/>estimator<br/>[token_estimator.py]"]
  node_tree_builder["Tree builder<br/>aggregator<br/>[tree_builder.py]"]
  node_graph_builder["Graph builder<br/>aggregator<br/>[graph_builder.py]"]
end

subgraph group_frontend["Frontend"]
  node_index_html["Index shell<br/>template<br/>[index.html]"]
  node_prototype_html["Prototype shell<br/>template<br/>[prototype.html]"]
  node_app_js["Client app<br/>frontend logic<br/>[app.js]"]
  node_style_css["Styles<br/>presentation<br/>[style.css]"]
  node_browser_ui(("Browser UI<br/>local web ui"))
  node_map_view(("Map view<br/>visualization"))
end

node_local_fs -->|"read"| node_config_scanner
node_local_fs -->|"browse"| node_file_browser
node_git_sources -->|"inspect"| node_git_scanner
node_process_table -->|"inspect"| node_process_scanner
node_local_fs -->|"read"| node_plan_scanner
node_config_scanner -->|"filter"| node_exclusions
node_file_browser -->|"filter"| node_exclusions
node_git_scanner -->|"signal"| node_rules
node_config_scanner -->|"signal"| node_rules
node_process_scanner -->|"signal"| node_rules
node_plan_scanner -->|"input"| node_graph_builder
node_git_scanner -->|"input"| node_graph_builder
node_config_scanner -->|"input"| node_token_estimator
node_exclusions -->|"sanitize"| node_redact
node_redact -->|"structure"| node_tree_builder
node_redact -->|"structure"| node_graph_builder
node_rules -->|"annotate"| node_tree_builder
node_token_estimator -->|"annotate"| node_tree_builder
node_tree_builder -->|"serve"| node_app_py
node_graph_builder -->|"serve"| node_app_py
node_app_py -->|"deliver"| node_browser_ui
node_index_html -->|"compose"| node_browser_ui
node_prototype_html -->|"compose"| node_browser_ui
node_app_js -->|"drive"| node_browser_ui
node_style_css -->|"style"| node_browser_ui
node_browser_ui -->|"show"| node_map_view
node_graph_builder -->|"feed"| node_map_view
node_plan_scanner -->|"open"| node_map_view

click node_app_py "https://github.com/jakefassora-hc/ai-scope/blob/main/app.py"
click node_config_scanner "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/config_scanner.py"
click node_file_browser "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/file_browser.py"
click node_git_scanner "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/git_scanner.py"
click node_process_scanner "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/process_scanner.py"
click node_plan_scanner "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/plan_scanner.py"
click node_exclusions "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/exclusions.py"
click node_redact "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/redact.py"
click node_rules "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/rules.py"
click node_token_estimator "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/token_estimator.py"
click node_tree_builder "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/tree_builder.py"
click node_graph_builder "https://github.com/jakefassora-hc/ai-scope/blob/main/scope/graph_builder.py"
click node_index_html "https://github.com/jakefassora-hc/ai-scope/blob/main/templates/index.html"
click node_prototype_html "https://github.com/jakefassora-hc/ai-scope/blob/main/templates/prototype.html"
click node_app_js "https://github.com/jakefassora-hc/ai-scope/blob/main/static/app.js"
click node_style_css "https://github.com/jakefassora-hc/ai-scope/blob/main/static/style.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_py toneBlue
class node_local_fs,node_git_sources,node_process_table toneAmber
class node_config_scanner,node_file_browser,node_git_scanner,node_process_scanner,node_plan_scanner toneMint
class node_exclusions,node_redact,node_rules,node_token_estimator,node_tree_builder,node_graph_builder toneRose
class node_index_html,node_prototype_html,node_app_js,node_style_css,node_browser_ui,node_map_view toneIndigo
```

## Components

### Runtime

Local Python server and browser-facing entrypoint

- [app.py](https://github.com/jakefassora-hc/ai-scope/blob/main/app.py): entrypoint server · Local read-only web server and API entrypoint · `app.py`

### Local Inputs

Filesystem, git, and process data observed by the app

- **Local files**: filesystem source · Home directory, Claude context, and plan documents
- **Git repos**: git source · ~/projects and active worktrees
- **Process table**: os source · Running claude CLI processes

### Scanners

Dedicated collectors for each local data source

- [Config scan](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/config_scanner.py): scanner · Discovers Claude config and context files · `scope/config_scanner.py`
- [File browse](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/file_browser.py): scanner · Controlled traversal and file access · `scope/file_browser.py`
- [Git scan](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/git_scanner.py): scanner · Finds repos, worktrees, and git status · `scope/git_scanner.py`
- [Process scan](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/process_scanner.py): scanner · Finds live claude processes and working dirs · `scope/process_scanner.py`
- [Plan scan](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/plan_scanner.py): scanner · Finds plan documents and map artifacts · `scope/plan_scanner.py`

### Core Processing

Policy, redaction, ranking, and structure building

- [Exclusions](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/exclusions.py): policy filter · Hard deny list for sensitive paths and file types · `scope/exclusions.py`
- [Redaction](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/redact.py): sanitizer · Removes secrets before content leaves the server · `scope/redact.py`
- [Insights rules](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/rules.py): analysis rules · Detects stale context, abandoned worktrees, and risk patterns · `scope/rules.py`
- [Token cost](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/token_estimator.py): estimator · Estimates Claude context token impact · `scope/token_estimator.py`
- [Tree builder](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/tree_builder.py): aggregator · Builds browsable hierarchy for navigation · `scope/tree_builder.py`
- [Graph builder](https://github.com/jakefassora-hc/ai-scope/blob/main/scope/graph_builder.py): aggregator · Builds portfolio map and relationship graph · `scope/graph_builder.py`

### Frontend

Browser shell, client logic, and visualizations

- [Index shell](https://github.com/jakefassora-hc/ai-scope/blob/main/templates/index.html): template · Main browser UI shell · `templates/index.html`
- [Prototype shell](https://github.com/jakefassora-hc/ai-scope/blob/main/templates/prototype.html): template · Alternate or experimental browser shell · `templates/prototype.html`
- [Client app](https://github.com/jakefassora-hc/ai-scope/blob/main/static/app.js): frontend logic · Tab switching, data loading, and D3 interactions · `static/app.js`
- [Styles](https://github.com/jakefassora-hc/ai-scope/blob/main/static/style.css): presentation · Browser presentation layer · `static/style.css`
- **Browser UI**: local web ui · Local tabbed interface for inventory and map views
- **Map view**: visualization · D3-powered portfolio graph and sunburst-style view

## Connections

- Local files → Config scan: read · Scan Claude context and config files
- Local files → File browse: browse · Traverse the local home tree
- Git repos → Git scan: inspect · Discover repositories and worktrees
- Process table → Process scan: inspect · List live claude processes
- Local files → Plan scan: read · Find plan and map documents
- Config scan → Exclusions: filter · Reject sensitive paths and files
- File browse → Exclusions: filter · Apply path and file safety rules
- Git scan → Insights rules: signal · Feed repo health and worktree signals
- Config scan → Insights rules: signal · Feed Claude context health signals
- Process scan → Insights rules: signal · Feed active usage signals
- Plan scan → Graph builder: input · Provide plan and document nodes
- Git scan → Graph builder: input · Provide repository and worktree nodes
- Config scan → Token cost: input · Measure context file cost
- Exclusions → Redaction: sanitize · Allow only safe content onward
- Redaction → Tree builder: structure · Prepare sanitized records for browsing
- Redaction → Graph builder: structure · Prepare sanitized records for mapping
- Insights rules → Tree builder: annotate · Attach insight flags to tree records
- Token cost → Tree builder: annotate · Attach token estimates to context files
- Tree builder → app.py: serve · Provide hierarchical data to the API
- Graph builder → app.py: serve · Provide graph data to the API
- app.py → Browser UI: deliver · Serve local UI and API responses
- Index shell → Browser UI: compose · Primary browser shell
- Prototype shell → Browser UI: compose · Alternate browser shell
- Client app → Browser UI: drive · Client-side interaction and tab behavior
- Styles → Browser UI: style · Presentation and layout
- Browser UI → Map view: show · Render the map tab and D3 visualization
- Graph builder → Map view: feed · Map data model for visualization
- Plan scan → Map view: open · Inline-open plan documents from the map