# tw93/mole architecture

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

- Interactive diagram: https://gitdiagram.com/tw93/mole
- Repository: https://github.com/tw93/mole

## Overview

1. **Overall shape**
   Mole is a macOS-focused maintenance toolkit delivered as a single CLI entrypoint, `mo`, with a mixed implementation split between **Go** and **shell scripts**. The repository is organized around user-facing commands such as clean, uninstall, optimize, analyze, status, purge, installer, update, and remove.

2. **Primary execution boundary**
   The top-level `bin/*.sh` scripts are the main user entrypoints and wrappers. They expose the CLI commands, handle shell integration, and delegate into the shared shell libraries under `lib/`, or into the Go-built subcommands where appropriate. This makes the repo feel like one product, but with multiple implementation layers behind it.

3. **Go-based subsystems**
   `cmd/analyze` and `cmd/status` are the main Go subsystems. They appear to own the more interactive and structured features:
   - `analyze` handles disk exploration, JSON output, live scanning, view formatting, deletion/update flows, and caching.
   - `status` gathers machine health and runtime metrics, diagnoses conditions, and renders the live dashboard.
   These commands are likely the most data-rich parts of the application and also the ones that support machine-readable output.

4. **Shell-based maintenance engine**
   Most destructive or system-touching maintenance work lives in shell libraries under `lib/`. These are grouped by domain:
   - `lib/clean` for cache and artifact cleanup
   - `lib/uninstall` for app removal
   - `lib/optimize` for system refresh and maintenance tasks
   - `lib/manage` for whitelist and purge-path management
   - `lib/ui` for interactive menu components
   - `lib/core` for shared plumbing
   This is the core operational backend for cleanup, uninstall, optimize, purge, and related actions.

5. **Common infrastructure layer**
   `lib/core` is the shared foundation used by the shell subsystems. It centralizes things like command wiring, common helpers, logging, file operations, timeouts, sudo handling, help text, and bundle/app resolution. Architecturally, this is the low-level boundary that keeps each maintenance command from reimplementing the same safety and runtime logic.

6. **Safety and destructive-operation controls**
   Safety is a first-class boundary across the repo. The README and tree show dedicated safety docs, review agents, and tests for dangerous paths. In practice, the destructive commands rely on:
   - path validation and protected-directory rules
   - dry-run behavior
   - whitelists / protected lists
   - logging of file operations
   - confirmation gates for high-risk actions
   This means the architecture is intentionally conservative: commands prefer refusing or skipping over broad deletion.

7. **Data flow for cleanup and uninstall**
   For `clean` and `uninstall`, the flow is roughly: user selection or scan discovery → classification of targets → safety filtering → deletion or trash/removal actions → summary of freed space. The repo also distinguishes between removing apps that are still installed versus cleaning leftovers for already-removed apps. That split is reflected in separate cleanup and uninstall domains.

8. **Data flow for analysis**
   `analyze` operates as a disk traversal and inspection pipeline. It scans a target path, aggregates directory and file sizes, identifies large files, formats the results for interactive browsing, and can emit JSON for scripting. The README indicates a key behavioral boundary: deletion from `analyze` goes through Trash/Finder rather than direct removal, making it safer for ad hoc cleanup.

9. **Data flow for live status**
   `status` is a read-only telemetry pipeline. It collects system state across CPU, memory, disk, network, battery/power, hardware, and process metrics, then computes a health score and renders a live dashboard. It also supports JSON output and auto-switches to JSON when piped, which makes it suitable for automation without changing the command path.

10. **Interactive UI layer**
    The repo has a dedicated terminal UI layer in `lib/ui` and corresponding view logic in the Go commands. This supports menu navigation, paginated selection, and keyboard-driven interaction for actions like choosing apps, selecting files, or reviewing cleanup candidates. The UI is not just presentation; it directly gates destructive operations by forcing user review.

11. **Support tooling and install/update path**
    The `scripts/` and `install.sh` files support installation, release automation, quick-launcher setup, and repository maintenance tasks. This sits outside the core command runtime but is important architecturally because it defines how the CLI is distributed, updated, and integrated into shell environments.

12. **Testing and validation boundaries**
    The repo uses a strong split between:
    - Go tests under `cmd/analyze`, `cmd/status`, and `internal/`
    - BATS integration tests under `tests/` for shell commands and system behavior
    - CI workflows under `.github/workflows/`
    This testing structure mirrors the implementation split: Go logic is unit-tested, while system-affecting shell behavior is validated with higher-level integration tests.

13. **Security and operational governance**
    Security-related files and workflows are prominent: `SECURITY.md`, `SECURITY_AUDIT.md`, gitleaks, CodeQL, and dedicated safety review agents. That indicates the project treats local-destructive operations, path handling, and shell execution as architectural risk areas, not just implementation details.

14. **How to diagram it**
    The clean architecture view is: **user/terminal → `mo` entry scripts → command-specific engine (`cmd/*` or `lib/*`) → filesystem/system APIs → output/logging/trash**. Around that core, add side boundaries for **interactive UI**, **safety validation**, **metrics collection**, **installation/release tooling**, and **testing/CI**.

Main entry points: [`mo`](https://github.com/tw93/mole/tree/main/mo) (mo), [`cmd/analyze`](https://github.com/tw93/mole/tree/main/cmd/analyze) (Analyze), [`lib/core`](https://github.com/tw93/mole/tree/main/lib/core) (Core), [`cmd/status`](https://github.com/tw93/mole/tree/main/cmd/status) (Status)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI entrypoints"]
  node_mo["mo<br/>cli entrypoint"]
  node_bin_clean["clean<br/>shell wrapper<br/>[clean.sh]"]
  node_bin_uninstall["uninstall<br/>shell wrapper<br/>[uninstall.sh]"]
  node_bin_optimize["optimize<br/>shell wrapper<br/>[optimize.sh]"]
  node_bin_analyze["analyze<br/>shell wrapper<br/>[analyze.sh]"]
  node_bin_status["status<br/>shell wrapper<br/>[status.sh]"]
  node_bin_purge["purge<br/>shell wrapper<br/>[purge.sh]"]
  node_bin_installer["installer<br/>shell wrapper<br/>[installer.sh]"]
end

subgraph group_grp_go["Go commands"]
  node_analyze_cmd[("Analyze<br/>go command")]
  node_status_cmd[("Status<br/>go command")]
  node_analyze_scan(("Scanner<br/>scan pipeline<br/>[scanner.go]"))
  node_analyze_live(("Live view<br/>interactive scan<br/>[live_scan.go]"))
  node_analyze_json["JSON out<br/>machine output<br/>[json.go]"]
  node_status_metrics[("Metrics<br/>telemetry collector<br/>[metrics.go]")]
  node_status_diag{{"Diagnosis<br/>health engine<br/>[diagnosis.go]"}}
  node_status_view(("Dashboard<br/>terminal view<br/>[view.go]"))
end

subgraph group_grp_shell["Shell maintenance"]
  node_core["Core<br/>shell foundation"]
  node_clean_lib["Clean<br/>shell domain"]
  node_uninstall_lib["Uninstall<br/>shell domain"]
  node_optimize_lib["Optimize<br/>shell domain"]
  node_manage_lib["Manage<br/>policy domain"]
  node_ui_lib(("UI"))
end

subgraph group_grp_support["Support tooling"]
  node_install_tooling["Install<br/>release tooling<br/>[install.sh]"]
  node_scripts["Scripts<br/>ops tooling"]
  node_tests["Tests<br/>validation suite"]
end

node_mo -->|"dispatches to"| node_bin_clean
node_mo -->|"dispatches to"| node_bin_uninstall
node_mo -->|"dispatches to"| node_bin_optimize
node_mo -->|"dispatches to"| node_bin_analyze
node_mo -->|"dispatches to"| node_bin_status
node_mo -->|"dispatches to"| node_bin_purge
node_mo -->|"dispatches to"| node_bin_installer
node_bin_clean -->|"uses"| node_clean_lib
node_bin_uninstall -->|"uses"| node_uninstall_lib
node_bin_optimize -->|"uses"| node_optimize_lib
node_bin_purge -->|"uses"| node_manage_lib
node_bin_analyze -->|"invokes"| node_analyze_cmd
node_bin_status -->|"invokes"| node_status_cmd
node_bin_installer -->|"uses"| node_install_tooling
node_analyze_cmd -->|"scans"| node_analyze_scan
node_analyze_cmd -->|"renders"| node_analyze_live
node_analyze_cmd -->|"exports"| node_analyze_json
node_analyze_cmd -->|"uses"| node_ui_lib
node_analyze_cmd -->|"uses"| node_core
node_status_cmd -->|"collects"| node_status_metrics
node_status_cmd -->|"evaluates"| node_status_diag
node_status_cmd -->|"renders"| node_status_view
node_status_cmd -->|"uses"| node_core
node_clean_lib -->|"uses"| node_core
node_uninstall_lib -->|"uses"| node_core
node_optimize_lib -->|"uses"| node_core
node_manage_lib -->|"uses"| node_core
node_ui_lib -->|"uses"| node_core
node_tests -.->|"validates"| node_core
node_tests -.->|"validates"| node_clean_lib
node_tests -.->|"validates"| node_uninstall_lib
node_tests -.->|"validates"| node_analyze_cmd
node_tests -.->|"validates"| node_status_cmd
node_scripts -->|"supports"| node_install_tooling

click node_mo "https://github.com/tw93/mole/tree/main/mo"
click node_bin_clean "https://github.com/tw93/mole/blob/main/bin/clean.sh"
click node_bin_uninstall "https://github.com/tw93/mole/blob/main/bin/uninstall.sh"
click node_bin_optimize "https://github.com/tw93/mole/blob/main/bin/optimize.sh"
click node_bin_analyze "https://github.com/tw93/mole/blob/main/bin/analyze.sh"
click node_bin_status "https://github.com/tw93/mole/blob/main/bin/status.sh"
click node_bin_purge "https://github.com/tw93/mole/blob/main/bin/purge.sh"
click node_bin_installer "https://github.com/tw93/mole/blob/main/bin/installer.sh"
click node_analyze_cmd "https://github.com/tw93/mole/tree/main/cmd/analyze"
click node_status_cmd "https://github.com/tw93/mole/tree/main/cmd/status"
click node_analyze_scan "https://github.com/tw93/mole/blob/main/cmd/analyze/scanner.go"
click node_analyze_live "https://github.com/tw93/mole/blob/main/cmd/analyze/live_scan.go"
click node_analyze_json "https://github.com/tw93/mole/blob/main/cmd/analyze/json.go"
click node_status_metrics "https://github.com/tw93/mole/blob/main/cmd/status/metrics.go"
click node_status_diag "https://github.com/tw93/mole/blob/main/cmd/status/diagnosis.go"
click node_status_view "https://github.com/tw93/mole/blob/main/cmd/status/view.go"
click node_core "https://github.com/tw93/mole/tree/main/lib/core"
click node_clean_lib "https://github.com/tw93/mole/tree/main/lib/clean"
click node_uninstall_lib "https://github.com/tw93/mole/tree/main/lib/uninstall"
click node_optimize_lib "https://github.com/tw93/mole/tree/main/lib/optimize"
click node_manage_lib "https://github.com/tw93/mole/tree/main/lib/manage"
click node_ui_lib "https://github.com/tw93/mole/tree/main/lib/ui"
click node_install_tooling "https://github.com/tw93/mole/blob/main/install.sh"
click node_scripts "https://github.com/tw93/mole/tree/main/scripts"
click node_tests "https://github.com/tw93/mole/tree/main/tests"

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_mo,node_bin_clean,node_bin_uninstall,node_bin_optimize,node_bin_analyze,node_bin_status,node_bin_purge,node_bin_installer toneBlue
class node_analyze_cmd,node_status_cmd,node_analyze_scan,node_analyze_live,node_analyze_json,node_status_metrics,node_status_diag,node_status_view toneAmber
class node_core,node_clean_lib,node_uninstall_lib,node_optimize_lib,node_manage_lib,node_ui_lib toneMint
class node_install_tooling,node_scripts,node_tests toneRose
```

## Components

### CLI entrypoints

User-facing shell wrappers and command dispatch.

- [mo](https://github.com/tw93/mole/tree/main/mo): cli entrypoint · Primary CLI launcher for the toolkit. · `mo`
- [clean](https://github.com/tw93/mole/blob/main/bin/clean.sh): shell wrapper · Shell entrypoint for cache and artifact cleanup. · `bin/clean.sh`
- [uninstall](https://github.com/tw93/mole/blob/main/bin/uninstall.sh): shell wrapper · Shell entrypoint for app removal flows. · `bin/uninstall.sh`
- [optimize](https://github.com/tw93/mole/blob/main/bin/optimize.sh): shell wrapper · Shell entrypoint for maintenance and refresh tasks. · `bin/optimize.sh`
- [analyze](https://github.com/tw93/mole/blob/main/bin/analyze.sh): shell wrapper · Wrapper that dispatches into the Go analyzer. · `bin/analyze.sh`
- [status](https://github.com/tw93/mole/blob/main/bin/status.sh): shell wrapper · Wrapper that dispatches into the Go status monitor. · `bin/status.sh`
- [purge](https://github.com/tw93/mole/blob/main/bin/purge.sh): shell wrapper · Shell entrypoint for purge and whitelist-driven removal. · `bin/purge.sh`
- [installer](https://github.com/tw93/mole/blob/main/bin/installer.sh): shell wrapper · Shell entrypoint for install and setup actions. · `bin/installer.sh`

### Go commands

Structured analysis and telemetry subsystems.

- [Analyze](https://github.com/tw93/mole/tree/main/cmd/analyze): go command · Disk exploration, formatting, JSON output, and delete/update flows. · `cmd/analyze`
- [Status](https://github.com/tw93/mole/tree/main/cmd/status): go command · System health telemetry, diagnosis, and live dashboard rendering. · `cmd/status`
- [Scanner](https://github.com/tw93/mole/blob/main/cmd/analyze/scanner.go): scan pipeline · Traverses paths and builds size/classification results. · `cmd/analyze/scanner.go`
- [Live view](https://github.com/tw93/mole/blob/main/cmd/analyze/live_scan.go): interactive scan · Live scanning and interactive browsing of analysis results. · `cmd/analyze/live_scan.go`
- [JSON out](https://github.com/tw93/mole/blob/main/cmd/analyze/json.go): machine output · Structured export for scripting and automation. · `cmd/analyze/json.go`
- [Metrics](https://github.com/tw93/mole/blob/main/cmd/status/metrics.go): telemetry collector · Collects CPU, memory, disk, network, battery, GPU, hardware, and process data. · `cmd/status/metrics.go`
- [Diagnosis](https://github.com/tw93/mole/blob/main/cmd/status/diagnosis.go): health engine · Computes health signals and system diagnosis. · `cmd/status/diagnosis.go`
- [Dashboard](https://github.com/tw93/mole/blob/main/cmd/status/view.go): terminal view · Renders the live status interface. · `cmd/status/view.go`

### Shell maintenance

Core operational libraries for destructive and system-touching tasks.

- [Core](https://github.com/tw93/mole/tree/main/lib/core): shell foundation · Shared command wiring, logging, timeouts, help, sudo, and file operations. · `lib/core`
- [Clean](https://github.com/tw93/mole/tree/main/lib/clean): shell domain · Cleanup routines for caches, app leftovers, and system artifacts. · `lib/clean`
- [Uninstall](https://github.com/tw93/mole/tree/main/lib/uninstall): shell domain · Application removal flows and batch uninstall support. · `lib/uninstall`
- [Optimize](https://github.com/tw93/mole/tree/main/lib/optimize): shell domain · Maintenance and system refresh tasks. · `lib/optimize`
- [Manage](https://github.com/tw93/mole/tree/main/lib/manage): policy domain · Whitelist and purge-path management for controlled deletion. · `lib/manage`
- [UI](https://github.com/tw93/mole/tree/main/lib/ui): terminal ui · Interactive menus, selection, and pagination for user review. · `lib/ui`

### Support tooling

Install, release, security, and test boundaries.

- [Install](https://github.com/tw93/mole/blob/main/install.sh): release tooling · Installation, launcher setup, and release/update automation. · `install.sh`
- [Scripts](https://github.com/tw93/mole/tree/main/scripts): ops tooling · Repository checks, release support, and homebrew tap maintenance. · `scripts`
- [Tests](https://github.com/tw93/mole/tree/main/tests): validation suite · Shell integration tests plus Go unit and fuzz coverage for safety-critical paths. · `tests`

## Connections

- mo → clean: dispatches to · Primary CLI exposes cleanup command.
- mo → uninstall: dispatches to · Primary CLI exposes uninstall command.
- mo → optimize: dispatches to · Primary CLI exposes optimize command.
- mo → analyze: dispatches to · Primary CLI exposes analysis command.
- mo → status: dispatches to · Primary CLI exposes status command.
- mo → purge: dispatches to · Primary CLI exposes purge command.
- mo → installer: dispatches to · Primary CLI exposes installer command.
- clean → Clean: uses · Cleanup wrapper delegates into shell domain.
- uninstall → Uninstall: uses · Uninstall wrapper delegates into shell domain.
- optimize → Optimize: uses · Optimize wrapper delegates into shell domain.
- purge → Manage: uses · Purge wrapper uses policy and whitelist logic.
- analyze → Analyze: invokes · Wrapper launches Go analyzer.
- status → Status: invokes · Wrapper launches Go status command.
- installer → Install: uses · Installer wrapper routes to setup tooling.
- Analyze → Scanner: scans · Core analyzer traverses filesystem and aggregates sizes.
- Analyze → Live view: renders · Interactive analysis views and live browsing.
- Analyze → JSON out: exports · Machine-readable output path for scripts.
- Analyze → UI: uses · Interactive selection and review UI.
- Analyze → Core: uses · Shared shell plumbing and safety helpers.
- Status → Metrics: collects · Telemetry collection across system subsystems.
- Status → Diagnosis: evaluates · Transforms metrics into health assessment.
- Status → Dashboard: renders · Live dashboard output.
- Status → Core: uses · Shared process and runtime helpers.
- Clean → Core: uses · Cleanup routines rely on shared safety and file ops.
- Uninstall → Core: uses · Removal flows depend on shared shell foundation.
- Optimize → Core: uses · Maintenance tasks reuse common execution plumbing.
- Manage → Core: uses · Whitelist and purge-path logic uses common helpers.
- UI → Core: uses · Terminal UI builds on shared shell utilities.
- Tests → Core: validates · Integration and fuzz tests cover common shell behavior.
- Tests → Clean: validates · Cleanup behavior is heavily tested.
- Tests → Uninstall: validates · Uninstall safety and behavior are tested.
- Tests → Analyze: validates · Go analyzer behavior is unit tested.
- Tests → Status: validates · Status command behavior is unit tested.
- Scripts → Install: supports · Repository scripts support installation and release flows.