# caezium/burrow architecture

> Architecture diagram of the GitHub repository caezium/burrow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caezium/burrow
- Repository: https://github.com/caezium/burrow

## Overview

Burrow is a system-maintenance and monitoring desktop app, with macOS as its mature native product and Windows preview implementations. The main user workflow is to choose a tool in the app, inspect a scan or preview, then run a cleanup, uninstall, purge, or maintenance action through the bundled engine; destructive operations are consent-gated. Separate capabilities include disk analysis, live status and metric history, and an MCP interface for AI agents. The graph combines README-documented capabilities with sampled engine, history, MCP, and helper relationships; unsampled feature internals are represented at their exact source paths, without inferred call chains.

Main entry points: [`macos/Sources/RootView.swift`](https://github.com/caezium/burrow/blob/main/macos/Sources/RootView.swift) (Tool views), [`macos/Sources/BurrowEngine.swift`](https://github.com/caezium/burrow/blob/main/macos/Sources/BurrowEngine.swift) (Engine facade), [`macos/Sources/CleanHub.swift`](https://github.com/caezium/burrow/blob/main/macos/Sources/CleanHub.swift) (Cleanup tools), [`macos/Sources/MetricsStore.swift`](https://github.com/caezium/burrow/blob/main/macos/Sources/MetricsStore.swift) (Metric history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_macos_ui["macOS app"]
  node_mac_app["App shell<br/>[App.swift]"]
  node_mac_views["Tool views<br/>[RootView.swift]"]
  node_cleanup["Cleanup tools<br/>[CleanHub.swift]"]
  node_uninstall["App uninstall"]
  node_dev_purge["Dev artifact purge<br/>[GitSweep.swift]"]
  node_maintenance["Maintenance<br/>[Maintenance.swift]"]
  node_disk_analysis["Disk analysis<br/>[DiskScanner.swift]"]
  node_live_status["Live status"]
end

subgraph group_macos_runtime["Engine and safety"]
  node_engine_facade["Engine facade<br/>[BurrowEngine.swift]"]
  node_engine_runner["Process runner<br/>[EngineRunner.swift]"]
  node_engine_cli["Engine discovery<br/>[EngineCLI.swift]"]
  node_privilege["Privileged helper"]
end

subgraph group_agent_history["Agents and history"]
  node_mcp["MCP server<br/>[MCPServer.swift]"]
  node_metrics[("Metric history<br/>[MetricsStore.swift]")]
  node_store[("Local store<br/>[Store.swift]")]
end

subgraph group_windows_app["Windows previews"]
  node_win_shell["Windows shell<br/>[App.xaml.cs]"]
  node_win_tools["Windows tool pages<br/>[ToolPages.tsx]"]
  node_win_engine["Windows engine service"]
  node_win_mcp["Windows MCP service"]
end

node_user(("Mac user"))
node_agent(("AI agent"))

node_user -->|"uses"| node_mac_app
node_mac_app -->|"presents"| node_mac_views
node_mac_views -->|"offers cleanup"| node_cleanup
node_mac_views -->|"offers uninstall"| node_uninstall
node_mac_views -->|"offers purge"| node_dev_purge
node_mac_views -->|"offers maintenance"| node_maintenance
node_mac_views -->|"offers analysis"| node_disk_analysis
node_mac_views -->|"shows status"| node_live_status
node_cleanup -->|"runs engine"| node_engine_facade
node_uninstall -->|"runs engine"| node_engine_facade
node_dev_purge -->|"runs engine"| node_engine_facade
node_maintenance -->|"runs engine"| node_engine_facade
node_engine_facade -->|"captures commands"| node_engine_runner
node_engine_facade -->|"resolves binary"| node_engine_cli
node_cleanup -.->|"may elevate"| node_privilege
node_agent -->|"queries tools"| node_mcp
node_mcp -->|"reads history"| node_metrics
node_live_status -->|"records metrics"| node_metrics
node_metrics -->|"persists locally"| node_store
node_user -->|"uses preview"| node_win_shell
node_win_shell -->|"presents tools"| node_win_tools
node_win_tools -.->|"executes commands"| node_win_engine
node_agent -->|"can query"| node_win_mcp

click node_mac_app "https://github.com/caezium/burrow/blob/main/macos/Sources/App.swift"
click node_mac_views "https://github.com/caezium/burrow/blob/main/macos/Sources/RootView.swift"
click node_cleanup "https://github.com/caezium/burrow/blob/main/macos/Sources/CleanHub.swift"
click node_uninstall "https://github.com/caezium/burrow/blob/main/macos/Sources/UninstallPlan.swift"
click node_dev_purge "https://github.com/caezium/burrow/blob/main/macos/Sources/GitSweep.swift"
click node_maintenance "https://github.com/caezium/burrow/blob/main/macos/Sources/Maintenance.swift"
click node_disk_analysis "https://github.com/caezium/burrow/blob/main/macos/Sources/DiskScanner.swift"
click node_live_status "https://github.com/caezium/burrow/blob/main/macos/Sources/SnapshotProducer.swift"
click node_engine_facade "https://github.com/caezium/burrow/blob/main/macos/Sources/BurrowEngine.swift"
click node_engine_runner "https://github.com/caezium/burrow/blob/main/macos/Sources/EngineRunner.swift"
click node_engine_cli "https://github.com/caezium/burrow/blob/main/macos/Sources/EngineCLI.swift"
click node_privilege "https://github.com/caezium/burrow/blob/main/macos/HelperSources/HelperService.swift"
click node_mcp "https://github.com/caezium/burrow/blob/main/macos/Sources/MCPServer.swift"
click node_metrics "https://github.com/caezium/burrow/blob/main/macos/Sources/MetricsStore.swift"
click node_store "https://github.com/caezium/burrow/blob/main/macos/Sources/Store.swift"
click node_win_shell "https://github.com/caezium/burrow/blob/main/windows/App.xaml.cs"
click node_win_tools "https://github.com/caezium/burrow/blob/main/windows/typescript/src/components/ToolPages.tsx"
click node_win_engine "https://github.com/caezium/burrow/blob/main/windows/Services/MoleEngineService.cs"
click node_win_mcp "https://github.com/caezium/burrow/blob/main/windows/Services/LocalMcpServerService.cs"

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_mac_app,node_mac_views,node_cleanup,node_uninstall,node_dev_purge,node_maintenance,node_disk_analysis,node_live_status,node_user toneBlue
class node_engine_facade,node_engine_runner,node_engine_cli,node_privilege toneAmber
class node_mcp,node_metrics,node_store toneMint
class node_win_shell,node_win_tools,node_win_engine,node_win_mcp toneRose
class node_agent toneIndigo
```

## Components

### macOS app

- [App shell](https://github.com/caezium/burrow/blob/main/macos/Sources/App.swift): `macos/Sources/App.swift`
- [Tool views](https://github.com/caezium/burrow/blob/main/macos/Sources/RootView.swift): `macos/Sources/RootView.swift`
- [Cleanup tools](https://github.com/caezium/burrow/blob/main/macos/Sources/CleanHub.swift): `macos/Sources/CleanHub.swift`
- [App uninstall](https://github.com/caezium/burrow/blob/main/macos/Sources/UninstallPlan.swift): `macos/Sources/UninstallPlan.swift`
- [Dev artifact purge](https://github.com/caezium/burrow/blob/main/macos/Sources/GitSweep.swift): `macos/Sources/GitSweep.swift`
- [Maintenance](https://github.com/caezium/burrow/blob/main/macos/Sources/Maintenance.swift): `macos/Sources/Maintenance.swift`
- [Disk analysis](https://github.com/caezium/burrow/blob/main/macos/Sources/DiskScanner.swift): `macos/Sources/DiskScanner.swift`
- [Live status](https://github.com/caezium/burrow/blob/main/macos/Sources/SnapshotProducer.swift): `macos/Sources/SnapshotProducer.swift`

### Engine and safety

- [Engine facade](https://github.com/caezium/burrow/blob/main/macos/Sources/BurrowEngine.swift): `macos/Sources/BurrowEngine.swift`
- [Process runner](https://github.com/caezium/burrow/blob/main/macos/Sources/EngineRunner.swift): `macos/Sources/EngineRunner.swift`
- [Engine discovery](https://github.com/caezium/burrow/blob/main/macos/Sources/EngineCLI.swift): `macos/Sources/EngineCLI.swift`
- [Privileged helper](https://github.com/caezium/burrow/blob/main/macos/HelperSources/HelperService.swift): `macos/HelperSources/HelperService.swift`

### Agents and history

- [MCP server](https://github.com/caezium/burrow/blob/main/macos/Sources/MCPServer.swift): `macos/Sources/MCPServer.swift`
- [Metric history](https://github.com/caezium/burrow/blob/main/macos/Sources/MetricsStore.swift): `macos/Sources/MetricsStore.swift`
- [Local store](https://github.com/caezium/burrow/blob/main/macos/Sources/Store.swift): `macos/Sources/Store.swift`

### Windows previews

- [Windows shell](https://github.com/caezium/burrow/blob/main/windows/App.xaml.cs): `windows/App.xaml.cs`
- [Windows tool pages](https://github.com/caezium/burrow/blob/main/windows/typescript/src/components/ToolPages.tsx): `windows/typescript/src/components/ToolPages.tsx`
- [Windows engine service](https://github.com/caezium/burrow/blob/main/windows/Services/MoleEngineService.cs): `windows/Services/MoleEngineService.cs`
- [Windows MCP service](https://github.com/caezium/burrow/blob/main/windows/Services/LocalMcpServerService.cs): `windows/Services/LocalMcpServerService.cs`

### Other components

- **Mac user**
- **AI agent**

## Connections

- Mac user → App shell: uses (evidence: `README.md`)
- App shell → Tool views: presents (evidence: `README.md`)
- Tool views → Cleanup tools: offers cleanup (evidence: `README.md`)
- Tool views → App uninstall: offers uninstall (evidence: `README.md`)
- Tool views → Dev artifact purge: offers purge (evidence: `README.md`)
- Tool views → Maintenance: offers maintenance (evidence: `README.md`)
- Tool views → Disk analysis: offers analysis (evidence: `README.md`)
- Tool views → Live status: shows status (evidence: `README.md`)
- Cleanup tools → Engine facade: runs engine (evidence: `README.md`)
- App uninstall → Engine facade: runs engine (evidence: `README.md`)
- Dev artifact purge → Engine facade: runs engine (evidence: `README.md`)
- Maintenance → Engine facade: runs engine (evidence: `README.md`)
- Engine facade → Process runner: captures commands (evidence: `macos/Sources/BurrowEngine.swift`)
- Engine facade → Engine discovery: resolves binary (evidence: `macos/Sources/BurrowEngine.swift`)
- Cleanup tools → Privileged helper: may elevate
- AI agent → MCP server: queries tools (evidence: `README.md`)
- MCP server → Metric history: reads history (evidence: `README.md`)
- Live status → Metric history: records metrics (evidence: `README.md`)
- Metric history → Local store: persists locally (evidence: `README.md`)
- Mac user → Windows shell: uses preview (evidence: `README.md`)
- Windows shell → Windows tool pages: presents tools
- Windows tool pages → Windows engine service: executes commands
- AI agent → Windows MCP service: can query (evidence: `README.md`)