# wp043/wp-mac-watch architecture

> Architecture diagram of the GitHub repository wp043/wp-mac-watch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wp043/wp-mac-watch
- Repository: https://github.com/wp043/wp-mac-watch

## Overview

This is a **Rust workspace** that produces:
- a **main interactive TUI binary** (`wp-mac-watch/`): “Activity Monitor alternative” (process list + system metrics + process actions).
- a **scriptable CLI binary** (`crates/cli/`): `snapshot` (JSON), `kill`, `kill-tree`.

Architecture-wise, it’s a **local-only, macOS-native observability + control tool** (no server, no network services). The key design intent in the README is: **a clean “core” data model** that multiple frontends can consume (TUI now; potential menubar later).

- **crate/module boundaries**
- **data flow (snapshots → diff → filtering/sorting → rendering)**
- **control flow (user input → action → kill/kill-tree)**
- **macOS integration points** (process enumeration, launchd attribution, signals)

##### File structure → architectural decomposition
From the tree + README:

**Workspace root**
- `Cargo.toml` = workspace orchestrator (multiple crates)
- `crates/` = reusable libraries + a CLI binary crate
- `wp-mac-watch/` = main binary crate wiring everything together

**Crates**
- `crates/core` (`wp_mac_watch_core`): **domain layer**
Data model + diffing + search + filter/sort. This is the “clean core”.
- `crates/mac` (`wp_mac_watch_mac`): **platform adapter / collectors**
MacCollector (process + CPU/mem/swap), launchd attribution, kill helpers, “handle_action”.
- `crates/tui` (`wp_mac_watch_tui`): **presentation + interaction loop**
`run_tui(rx, tx)` suggests it consumes updates from a channel and emits commands/actions to another channel.
- `crates/cli` (`wp_mac_watch_cli`): **non-interactive interface**
clap-based command parsing; calls into mac/core to output JSON snapshot and perform actions.

**Main binary**
- `wp-mac-watch/src/main.rs`: the **composition root**
“wires sampler + TUI + actions” (per README). This is where concurrency/channels typically live.

##### Data/Domain (Core)
- **ProcessSnapshot / ProcessRow**
- **SystemMetrics**
- **Attribution / AttributionKind**
- **SearchQuery / GroupMode / SortKey**
- **build_snapshot / diff_snapshots / filter_and_sort**

##### Platform layer (macOS collectors + actions)
- **MacCollector** (collect processes + CPU/mem/swap)
- **launchd plist index** (attribution)
- **kill_pid / kill_tree / handle_action**
- OS APIs: process table, memory stats, signals (SIGKILL/SIGTERM), launchd plists

##### TUI frontend (ratatui)
- event loop `run_tui(rx, tx)`
- renders: header/system bar, process table, details pane, footer
- handles keybindings → emits “actions” (force kill, kill tree, sort, search, group toggle)

##### CLI frontend
- clap parsing
- `snapshot` outputs JSON
- `kill` / `kill-tree` invoke process control

##### Composition root + runtime wiring (main binary)
- sampling loop / scheduler (periodic collection)
- channels between sampler ↔ TUI (rx/tx)
- action handler loop (receives actions from UI; dispatches to mac kill functions)
- state store (current snapshot, diff, selected row, search/sort/group mode)

##### macOS → MacCollector
(process list, CPU%, memory, swap; launchd attribution)
##### MacCollector → core::build_snapshot
produces `ProcessSnapshot + SystemMetrics`
##### core::diff_snapshots
previous snapshot + current snapshot → `SnapshotDiff`
##### core::filter_and_sort
uses `SearchQuery`, `SortKey`, `GroupMode` → filtered list for display
##### → TUI render
table + details pane + system bar

##### User input in TUI (keys `/`, `s`, `Tab`, `f`, `t`)
→ emits an **Action/Command** message (via `tx`)
##### Action handler (in main binary)
→ calls `wp_mac_watch_mac::handle_action` / `kill_pid` / `kill_tree`

##### CLI flow
- `wp-mac-watch-cli snapshot`:
CLI → MacCollector/core build_snapshot → JSON stdout
- `kill` / `kill-tree`:
CLI → mac kill_pid/kill_tree → macOS signals

Keep CLI separate from the TUI runtime wiring (it’s a different entrypoint).

- **Clean-ish layering / Hexagonal tendency**
- `core` = domain + pure logic (filter/sort/diff)
- `mac` = adapter to OS (impure, platform-specific)
- `tui` / `cli` = delivery mechanisms (UI + commands)
- `wp-mac-watch` = composition root
- **Snapshot + Diff model**
- periodic sampling → immutable-ish snapshots → diff for change representation
- **Message passing / channels**
- `run_tui(rx, tx)` strongly implies decoupled event loops (producer/consumer)

Small callouts like: “core has no OS/UI dependencies; reused by both CLI and TUI”.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View 1: Crate / Dependency Architecture (Static)
  %% =========================
  subgraph V1["View 1: Crate / Dependency Architecture (Static)"]
    direction TB

    subgraph EP["Entry points (bin crates)"]
      direction TB
      BIN_TUI["wp-mac-watch (bin)\nInteractive TUI app\n(composition root)"]:::bin
      BIN_CLI["wp-mac-watch-cli (bin)\nScriptable CLI\n(snapshot/kill/kill-tree)"]:::bin
    end

    subgraph LIB["Workspace crates (shared libraries)"]
      direction TB
      CR_TUI["wp_mac_watch_tui (crate)\nPresentation + interaction\nrun_tui(rx, tx)"]:::frontend
      CR_CORE["wp_mac_watch_core (crate)\nClean domain model\nsnapshot/diff/filter/sort/search"]:::core
      CR_MAC["wp_mac_watch_mac (crate)\nmacOS adapter\nMacCollector + kill helpers\nhandle_action"]:::platform
    end

    subgraph EXT["External deps + OS interfaces"]
      direction TB
      DEP_RATATUI["ratatui / terminal backend\n(rendering + input)"]:::ext
      DEP_CLAP["clap\n(arg parsing)"]:::ext
      OS_APIS["macOS system interfaces\n(process table, kernel metrics, signals)\nlaunchd plists"]:::os
    end

    %% Static dependencies
    BIN_TUI -->|"uses"| CR_TUI
    BIN_TUI -->|"uses"| CR_MAC
    BIN_TUI -->|"uses"| CR_CORE

    BIN_CLI -->|"uses"| CR_MAC
    BIN_CLI -->|"uses"| CR_CORE
    BIN_CLI -.->|"uses"| DEP_CLAP

    CR_TUI -->|"uses"| CR_CORE
    CR_TUI -.->|"renders/reads_input_via"| DEP_RATATUI

    CR_MAC -->|"uses_models/types"| CR_CORE
    CR_MAC -.->|"calls"| OS_APIS
  end

  %% =========================
  %% View 2: Runtime Data + Control Flow (Dynamic)
  %% =========================
  subgraph V2["View 2: Runtime Data + Control Flow (Dynamic)"]
    direction TB

    subgraph RT_TUI["Interactive runtime (wp-mac-watch)"]
      direction TB

      MAIN_WIRING["Composition root\n(wp-mac-watch/src/main.rs)\nspawns loops + channels\nholds state (snapshot/diff/ui selection)"]:::bin

      LOOP_SAMPLER["Sampler loop\n(periodic tick)\ncollects telemetry"]:::loop
      LOOP_TUI["TUI loop\nrun_tui(rx, tx)\nrender + keybindings\n(confirm destructive actions)"]:::loop
      LOOP_ACTION["Action handler loop\nreceives Action/Command\ninvokes mac::handle_action\nkill_pid / kill_tree"]:::loop

      CH_UPDATES["Channel: Updates\nSampler -> UI\n(rx)"]:::channel
      CH_ACTIONS["Channel: Actions\nUI -> Handler\n(tx)"]:::channel
    end

    subgraph PIPE["Snapshot pipeline (core)"]
      direction TB
      STEP_COLLECT["MacCollector\n(collect processes + CPU/mem/swap)\n+ launchd attribution"]:::platform
      STEP_BUILD["core::build_snapshot\n-> ProcessSnapshot + SystemMetrics"]:::core
      STEP_DIFF["core::diff_snapshots\n(prev, current)\n-> SnapshotDiff"]:::core
      STEP_FILTER["core::filter_and_sort\n(SearchQuery, SortKey, GroupMode)\n-> rows_for_display"]:::core
      STEP_RENDER["TUI render\n(system bar + table + details + footer)"]:::frontend
    end

    subgraph OS["macOS (local-only)"]
      direction TB
      OS_PROC[("macOS: process table")]:::os
      OS_METRICS[("macOS: CPU/mem/swap APIs")]:::os
      OS_LAUNCHD[("launchd plists\n(attribution source)")]:::os
      OS_SIG[("Signals\n(SIGTERM / SIGKILL)")]:::os
    end

    %% Runtime wiring (threads/loops)
    MAIN_WIRING -->|"spawns"| LOOP_SAMPLER
    MAIN_WIRING -->|"spawns"| LOOP_TUI
    MAIN_WIRING -->|"spawns"| LOOP_ACTION

    LOOP_SAMPLER -.->|"sends_updates"| CH_UPDATES
    CH_UPDATES -.->|"rx"| LOOP_TUI

    LOOP_TUI -.->|"emits_Action/Command\n(KillPid/KillTree/Sort/Search/Group)"| CH_ACTIONS
    CH_ACTIONS -.->|"recv"| LOOP_ACTION

    %% Telemetry pipeline
    LOOP_SAMPLER -->|"calls"| STEP_COLLECT
    OS_PROC -.->|"enumerate"| STEP_COLLECT
    OS_METRICS -.->|"read_metrics"| STEP_COLLECT
    OS_LAUNCHD -.->|"read_index"| STEP_COLLECT

    STEP_COLLECT -->|"ProcessSnapshot+SystemMetrics"| STEP_BUILD
    STEP_BUILD -->|"current_snapshot"| STEP_DIFF
    STEP_DIFF -->|"SnapshotDiff"| STEP_FILTER
    STEP_FILTER -->|"rows_for_display"| STEP_RENDER
    STEP_RENDER -->|"frame_updates"| LOOP_TUI

    %% Action/control flow
    LOOP_ACTION -->|"calls"| STEP_COLLECT
    LOOP_ACTION -->|"handle_action / kill_pid / kill_tree"| OS_SIG
    OS_SIG -.->|"changes_OS_state\n(process exits)"| OS_PROC
    OS_PROC -.->|"reflected_next_tick"| LOOP_SAMPLER
  end

  %% =========================
  %% View 3: CLI flows (Dynamic, separate entrypoint)
  %% =========================
  subgraph V3["View 3: CLI Flows (Dynamic)"]
    direction TB

    CLI_MAIN["CLI entrypoint\n(snapshot -> JSON stdout)\n(kill / kill-tree)"]:::bin
    CLI_SNAPSHOT["snapshot command\ncollect -> build_snapshot\nserialize JSON"]:::loop
    CLI_KILL["kill / kill-tree commands\ninvoke mac kill helpers"]:::loop
    STDOUT["stdout\n(JSON)"]:::ext

    CLI_MAIN -->|"parses_args"| DEP_CLAP
    CLI_MAIN -->|"dispatches"| CLI_SNAPSHOT
    CLI_MAIN -->|"dispatches"| CLI_KILL

    CLI_SNAPSHOT -->|"calls"| STEP_COLLECT
    CLI_SNAPSHOT -->|"calls"| STEP_BUILD
    CLI_SNAPSHOT -->|"writes"| STDOUT

    CLI_KILL -->|"kill_pid/kill_tree"| OS_SIG
    OS_SIG -.->|"affects"| OS_PROC
  end

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click BIN_TUI "https://github.com/wp043/wp-mac-watch/tree/main/wp-mac-watch/"
  click MAIN_WIRING "https://github.com/wp043/wp-mac-watch/blob/main/wp-mac-watch/src/main.rs"
  click CR_CORE "https://github.com/wp043/wp-mac-watch/tree/main/crates/core/"
  click STEP_BUILD "https://github.com/wp043/wp-mac-watch/blob/main/crates/core/src/lib.rs"
  click STEP_DIFF "https://github.com/wp043/wp-mac-watch/blob/main/crates/core/src/lib.rs"
  click STEP_FILTER "https://github.com/wp043/wp-mac-watch/blob/main/crates/core/src/lib.rs"
  click CR_MAC "https://github.com/wp043/wp-mac-watch/tree/main/crates/mac/"
  click STEP_COLLECT "https://github.com/wp043/wp-mac-watch/blob/main/crates/mac/src/lib.rs"
  click CR_TUI "https://github.com/wp043/wp-mac-watch/tree/main/crates/tui/"
  click LOOP_TUI "https://github.com/wp043/wp-mac-watch/blob/main/crates/tui/src/lib.rs"
  click BIN_CLI "https://github.com/wp043/wp-mac-watch/tree/main/crates/cli/"
  click CLI_MAIN "https://github.com/wp043/wp-mac-watch/blob/main/crates/cli/src/main.rs"
  click V1 "https://github.com/wp043/wp-mac-watch/blob/main/Cargo.toml"

  %% =========================
  %% Styles
  %% =========================
  classDef bin fill:#1f3a5f,stroke:#9ad1ff,stroke-width:2px,color:#ffffff
  classDef core fill:#1b5e20,stroke:#a5d6a7,stroke-width:2px,color:#ffffff
  classDef platform fill:#4e342e,stroke:#ffccbc,stroke-width:2px,color:#ffffff
  classDef frontend fill:#4a148c,stroke:#e1bee7,stroke-width:2px,color:#ffffff
  classDef loop fill:#0f172a,stroke:#93c5fd,stroke-width:2px,color:#e5e7eb
  classDef channel fill:#263238,stroke:#80cbc4,stroke-width:2px,color:#e0f2f1,stroke-dasharray: 6 4
  classDef os fill:#263238,stroke:#ffd54f,stroke-width:2px,color:#fff8e1
  classDef ext fill:#37474f,stroke:#b0bec5,stroke-width:2px,color:#eceff1,stroke-dasharray: 5 5
```
