# navidzamankhan/tucked architecture

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

- Interactive diagram: https://gitdiagram.com/navidzamankhan/tucked
- Repository: https://github.com/navidzamankhan/tucked

## Overview

Tucked is a native macOS menu-bar system monitor. The user opens its unified shelf from the status item; this switches monitoring from passive aggregate sampling to on-demand diagnostics, whose snapshots and history feed the shelf and status display. The graph preserves the documented telemetry, process recovery, hardware, and network capabilities. Some subsystem wiring is based on the README and coordinator excerpts; unsampled implementation details are not expanded into inferred calls.

Main entry points: [`Sources/Tucked/Monitoring/MonitoringCoordinator.swift`](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/MonitoringCoordinator.swift) (Monitoring coordinator), [`Sources/Tucked/UI/ShelfModel.swift`](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/ShelfModel.swift) (Shelf model), [`Sources/Tucked/App/AppCoordinator.swift`](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/App/AppCoordinator.swift) (App coordinator), [`Sources/Tucked/UI/OverviewView.swift`](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/OverviewView.swift) (Overview surface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and shelf"]
  node_app_entry["App lifecycle<br/>[TuckedApp.swift]"]
  node_app_coordinator["App coordinator"]
  node_status["Menu-bar status"]
  node_shelf_controller["Shelf controller"]
end

subgraph group_monitor["Monitoring"]
  node_monitoring["Monitoring coordinator"]
  node_snapshots["Metric snapshots"]
  node_history[("History store<br/>[HistoryStore.swift]")]
end

subgraph group_sensors["Sampling and diagnostics"]
  node_cpu_memory["CPU and memory"]
  node_network_sampler["Network throughput"]
  node_process_sampler["Process sampler"]
  node_termination["Process termination"]
  node_icon_provider["Process icons"]
  node_thermal["Thermal provider"]
  node_smc["Read-only SMC<br/>[SMCReader.swift]"]
  node_wifi["Wi-Fi reader<br/>[WiFiReader.swift]"]
  node_net_diag["Network diagnostics"]
end

subgraph group_presentation["Views and settings"]
  node_shelf_model["Shelf model<br/>[ShelfModel.swift]"]
  node_overview["Overview surface<br/>[OverviewView.swift]"]
  node_shelf_view["Shelf surface<br/>[ShelfView.swift]"]
  node_settings["Settings surface<br/>[SettingsView.swift]"]
  node_preferences["Preferences<br/>[Preferences.swift]"]
  node_login_item["Login item service"]
end

node_user(("Mac user"))
node_public_network(("Public network"))

node_user -->|"clicks"| node_status
node_app_entry -->|"starts"| node_app_coordinator
node_app_coordinator -->|"starts and stops"| node_monitoring
node_app_coordinator -->|"binds snapshots"| node_status
node_app_coordinator -->|"updates snapshots"| node_shelf_model
node_status -->|"toggles shelf"| node_shelf_controller
node_shelf_controller -->|"opens or closes diagnostics"| node_monitoring
node_shelf_model -->|"resets network totals"| node_monitoring
node_monitoring -->|"samples passive metrics"| node_cpu_memory
node_monitoring -->|"samples throughput"| node_network_sampler
node_monitoring -->|"samples diagnostics"| node_process_sampler
node_monitoring -->|"samples diagnostics"| node_thermal
node_monitoring -->|"reads diagnostics"| node_wifi
node_monitoring -->|"probes diagnostics"| node_net_diag
node_thermal -->|"reads sensors"| node_smc
node_net_diag -.->|"probes and resolves IP"| node_public_network
node_monitoring -->|"publishes"| node_snapshots
node_monitoring -->|"updates history"| node_history
node_snapshots -->|"updates display"| node_status
node_snapshots -->|"updates model"| node_shelf_model
node_history -->|"supplies history"| node_shelf_model
node_shelf_view -->|"shows overview"| node_overview
node_shelf_view -->|"shows settings"| node_settings
node_shelf_model -->|"provides telemetry"| node_overview
node_overview -->|"shows process rankings"| node_process_sampler
node_overview -->|"uses process icons"| node_icon_provider
node_shelf_model -->|"requests process recovery"| node_termination
node_settings -->|"reads and updates"| node_preferences
node_settings -->|"controls launch-at-login"| node_login_item

click node_app_entry "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/App/TuckedApp.swift"
click node_app_coordinator "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/App/AppCoordinator.swift"
click node_status "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Shell/StatusItemController.swift"
click node_shelf_controller "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Shell/ShelfController.swift"
click node_monitoring "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/MonitoringCoordinator.swift"
click node_snapshots "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/MetricSnapshot.swift"
click node_history "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/HistoryStore.swift"
click node_shelf_model "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/ShelfModel.swift"
click node_overview "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/OverviewView.swift"
click node_shelf_view "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/ShelfView.swift"
click node_settings "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/SettingsView.swift"
click node_preferences "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Support/Preferences.swift"
click node_login_item "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Support/LoginItemService.swift"
click node_cpu_memory "https://github.com/navidzamankhan/tucked/tree/main/Sources/Tucked/Sampling"
click node_network_sampler "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Sampling/NetworkSampler.swift"
click node_process_sampler "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Processes/ProcessSampler.swift"
click node_termination "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Processes/ProcessTerminationPolicy.swift"
click node_icon_provider "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Processes/ProcessIconProvider.swift"
click node_thermal "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Thermal/ThermalProvider.swift"
click node_smc "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Thermal/SMCReader.swift"
click node_wifi "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Diagnostics/WiFiReader.swift"
click node_net_diag "https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Diagnostics/NetworkDiagnostics.swift"

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_entry,node_app_coordinator,node_status,node_shelf_controller,node_user toneBlue
class node_monitoring,node_snapshots,node_history toneAmber
class node_cpu_memory,node_network_sampler,node_process_sampler,node_termination,node_icon_provider,node_thermal,node_smc,node_wifi,node_net_diag toneMint
class node_shelf_model,node_overview,node_shelf_view,node_settings,node_preferences,node_login_item toneRose
class node_public_network toneIndigo
```

## Components

### App and shelf

- [App lifecycle](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/App/TuckedApp.swift): `Sources/Tucked/App/TuckedApp.swift`
- [App coordinator](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/App/AppCoordinator.swift): `Sources/Tucked/App/AppCoordinator.swift`
- [Menu-bar status](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Shell/StatusItemController.swift): `Sources/Tucked/Shell/StatusItemController.swift`
- [Shelf controller](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Shell/ShelfController.swift): `Sources/Tucked/Shell/ShelfController.swift`

### Monitoring

- [Monitoring coordinator](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/MonitoringCoordinator.swift): `Sources/Tucked/Monitoring/MonitoringCoordinator.swift`
- [Metric snapshots](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/MetricSnapshot.swift): `Sources/Tucked/Monitoring/MetricSnapshot.swift`
- [History store](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Monitoring/HistoryStore.swift): `Sources/Tucked/Monitoring/HistoryStore.swift`

### Sampling and diagnostics

- [CPU and memory](https://github.com/navidzamankhan/tucked/tree/main/Sources/Tucked/Sampling): `Sources/Tucked/Sampling`
- [Network throughput](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Sampling/NetworkSampler.swift): `Sources/Tucked/Sampling/NetworkSampler.swift`
- [Process sampler](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Processes/ProcessSampler.swift): `Sources/Tucked/Processes/ProcessSampler.swift`
- [Process termination](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Processes/ProcessTerminationPolicy.swift): `Sources/Tucked/Processes/ProcessTerminationPolicy.swift`
- [Process icons](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Processes/ProcessIconProvider.swift): `Sources/Tucked/Processes/ProcessIconProvider.swift`
- [Thermal provider](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Thermal/ThermalProvider.swift): `Sources/Tucked/Thermal/ThermalProvider.swift`
- [Read-only SMC](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Thermal/SMCReader.swift): `Sources/Tucked/Thermal/SMCReader.swift`
- [Wi-Fi reader](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Diagnostics/WiFiReader.swift): `Sources/Tucked/Diagnostics/WiFiReader.swift`
- [Network diagnostics](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Diagnostics/NetworkDiagnostics.swift): `Sources/Tucked/Diagnostics/NetworkDiagnostics.swift`

### Views and settings

- [Shelf model](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/ShelfModel.swift): `Sources/Tucked/UI/ShelfModel.swift`
- [Overview surface](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/OverviewView.swift): `Sources/Tucked/UI/OverviewView.swift`
- [Shelf surface](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/ShelfView.swift): `Sources/Tucked/UI/ShelfView.swift`
- [Settings surface](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/UI/SettingsView.swift): `Sources/Tucked/UI/SettingsView.swift`
- [Preferences](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Support/Preferences.swift): `Sources/Tucked/Support/Preferences.swift`
- [Login item service](https://github.com/navidzamankhan/tucked/blob/main/Sources/Tucked/Support/LoginItemService.swift): `Sources/Tucked/Support/LoginItemService.swift`

### Other components

- **Mac user**
- **Public network**

## Connections

- Mac user → Menu-bar status: clicks
- App lifecycle → App coordinator: starts
- App coordinator → Monitoring coordinator: starts and stops
- App coordinator → Menu-bar status: binds snapshots
- App coordinator → Shelf model: updates snapshots
- Menu-bar status → Shelf controller: toggles shelf
- Shelf controller → Monitoring coordinator: opens or closes diagnostics
- Shelf model → Monitoring coordinator: resets network totals
- Monitoring coordinator → CPU and memory: samples passive metrics
- Monitoring coordinator → Network throughput: samples throughput
- Monitoring coordinator → Process sampler: samples diagnostics
- Monitoring coordinator → Thermal provider: samples diagnostics
- Monitoring coordinator → Wi-Fi reader: reads diagnostics
- Monitoring coordinator → Network diagnostics: probes diagnostics
- Thermal provider → Read-only SMC: reads sensors
- Network diagnostics → Public network: probes and resolves IP
- Monitoring coordinator → Metric snapshots: publishes
- Monitoring coordinator → History store: updates history
- Metric snapshots → Menu-bar status: updates display
- Metric snapshots → Shelf model: updates model
- History store → Shelf model: supplies history
- Shelf surface → Overview surface: shows overview
- Shelf surface → Settings surface: shows settings
- Shelf model → Overview surface: provides telemetry
- Overview surface → Process sampler: shows process rankings
- Overview surface → Process icons: uses process icons
- Shelf model → Process termination: requests process recovery
- Settings surface → Preferences: reads and updates
- Settings surface → Login item service: controls launch-at-login