# tiavina22/hoopix architecture

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

- Interactive diagram: https://gitdiagram.com/tiavina22/hoopix
- Repository: https://github.com/tiavina22/hoopix
- Video tour (about a minute): https://gitdiagram.com/tiavina22/hoopix/video

## Overview

Hoopix is a macOS maintenance and system-visibility app. Users navigate its sections to inspect system state or discover cleanup, uninstall, and project-artifact targets; review a plan or confirmation; then approve changes, with operations recorded for History. Analyze also scans disk usage and moves selected items to Trash, while Optimize runs bounded maintenance tasks. The README documents a presentation/domain/data architecture and shared macOS process and file-operation support. Feature wiring is represented at subsystem level; sampled source primarily confirms native privileged deletion and Trash behavior.

Main entry points: [`lib/core/navigation/app_shell.dart`](https://github.com/tiavina22/hoopix/blob/main/lib/core/navigation/app_shell.dart) (Section navigation), [`lib/core/process/process_runner.dart`](https://github.com/tiavina22/hoopix/blob/main/lib/core/process/process_runner.dart) (Process runner), [`lib/features/clean/data`](https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/data) (Clean discovery and removal), [`lib/features/optimize/data/datasources/optimize_task_runner.dart`](https://github.com/tiavina22/hoopix/blob/main/lib/features/optimize/data/datasources/optimize_task_runner.dart) (Task execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_app["App entry<br/>[app.dart]"]
  node_shell["Section navigation<br/>[app_shell.dart]"]
  node_clean_ui["Clean review"]
  node_uninstall_ui["Uninstall review"]
  node_purge_ui["Purge review"]
  node_optimize_ui["Optimize controls"]
  node_analyze_ui["Disk explorer"]
  node_status_ui["Live status"]
  node_history_ui["Operation history"]
end

subgraph group_maintenance["Maintenance actions"]
  node_clean_engine["Clean planning"]
  node_clean_data["Clean discovery and removal"]
  node_uninstall_engine["Uninstall discovery"]
  node_uninstall_data["App removal actions"]
  node_purge_engine["Artifact planning"]
  node_purge_data["Artifact deletion"]
  node_optimize_engine["Maintenance tasks<br/>[run_optimize.dart]"]
  node_optimize_data["Task execution"]
end

subgraph group_inspection["Inspection and history"]
  node_analyze_engine["Disk scan operations"]
  node_analyze_data["Disk scan sources"]
  node_status_engine["System snapshot"]
  node_status_data["System probes"]
  node_history_data["History reader"]
end

subgraph group_runtime["Shared runtime"]
  node_process["Process runner"]
  node_platform["File and system operations"]
  node_trash_native["Protected Trash channel<br/>[TrashChannel.swift]"]
  node_privileged_native["Privileged delete channel"]
end

node_user(("Mac user"))
node_macos(("macOS tools and filesystem"))
node_operation_log[("Operation log")]

node_user -->|"launches"| node_app
node_app -->|"builds interface"| node_shell
node_user -->|"selects section"| node_shell
node_shell -->|"shows"| node_clean_ui
node_shell -->|"shows"| node_uninstall_ui
node_shell -->|"shows"| node_purge_ui
node_shell -->|"shows"| node_optimize_ui
node_shell -->|"shows"| node_analyze_ui
node_shell -->|"shows"| node_status_ui
node_shell -->|"shows"| node_history_ui
node_clean_ui -->|"requests plan"| node_clean_engine
node_clean_engine -->|"requests discovery"| node_clean_data
node_clean_ui -->|"approves removal"| node_clean_data
node_uninstall_ui -->|"requests inventory"| node_uninstall_engine
node_uninstall_engine -->|"discovers app"| node_uninstall_data
node_uninstall_ui -->|"approves uninstall"| node_uninstall_data
node_purge_ui -->|"requests plan"| node_purge_engine
node_purge_engine -->|"discovers artifacts"| node_purge_data
node_purge_ui -->|"approves deletion"| node_purge_data
node_optimize_ui -->|"starts tasks"| node_optimize_engine
node_optimize_engine -->|"dispatches tasks"| node_optimize_data
node_analyze_ui -->|"requests scan"| node_analyze_engine
node_analyze_engine -->|"requests filesystem data"| node_analyze_data
node_analyze_ui -->|"requests Trash move"| node_platform
node_status_ui -->|"watches status"| node_status_engine
node_status_engine -->|"requests probes"| node_status_data
node_history_ui -->|"fetches records"| node_history_data
node_clean_data -->|"runs commands"| node_process
node_uninstall_data -->|"runs commands"| node_process
node_purge_data -->|"runs commands"| node_process
node_optimize_data -->|"runs commands"| node_process
node_status_data -->|"runs probes"| node_process
node_analyze_data -->|"scans paths"| node_platform
node_platform -->|"invokes channel"| node_trash_native
node_clean_data -.->|"requests privileged delete"| node_privileged_native
node_optimize_data -.->|"requests privileged task"| node_privileged_native
node_process -->|"runs native tools"| node_macos
node_platform -->|"reads and moves files"| node_macos
node_trash_native -->|"moves to Trash"| node_macos
node_privileged_native -->|"deletes allowlisted paths"| node_macos
node_clean_data -->|"records operations"| node_operation_log
node_uninstall_data -->|"records operations"| node_operation_log
node_purge_data -->|"records operations"| node_operation_log
node_optimize_data -->|"records operations"| node_operation_log
node_history_data -->|"reads operations"| node_operation_log

click node_app "https://github.com/tiavina22/hoopix/blob/main/lib/app.dart"
click node_shell "https://github.com/tiavina22/hoopix/blob/main/lib/core/navigation/app_shell.dart"
click node_clean_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/presentation"
click node_uninstall_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/uninstall/presentation"
click node_purge_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/purge/presentation"
click node_optimize_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/optimize/presentation"
click node_analyze_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/analyze/presentation"
click node_status_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/status/presentation"
click node_history_ui "https://github.com/tiavina22/hoopix/tree/main/lib/features/history/presentation"
click node_clean_engine "https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/domain/usecases"
click node_clean_data "https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/data"
click node_uninstall_engine "https://github.com/tiavina22/hoopix/tree/main/lib/features/uninstall/domain/usecases"
click node_uninstall_data "https://github.com/tiavina22/hoopix/tree/main/lib/features/uninstall/data"
click node_purge_engine "https://github.com/tiavina22/hoopix/tree/main/lib/features/purge/domain/usecases"
click node_purge_data "https://github.com/tiavina22/hoopix/tree/main/lib/features/purge/data"
click node_optimize_engine "https://github.com/tiavina22/hoopix/blob/main/lib/features/optimize/domain/usecases/run_optimize.dart"
click node_optimize_data "https://github.com/tiavina22/hoopix/blob/main/lib/features/optimize/data/datasources/optimize_task_runner.dart"
click node_analyze_engine "https://github.com/tiavina22/hoopix/tree/main/lib/features/analyze/domain/usecases"
click node_analyze_data "https://github.com/tiavina22/hoopix/tree/main/lib/features/analyze/data"
click node_status_engine "https://github.com/tiavina22/hoopix/blob/main/lib/features/status/domain/usecases/watch_system_status.dart"
click node_status_data "https://github.com/tiavina22/hoopix/tree/main/lib/features/status/data/datasources"
click node_history_data "https://github.com/tiavina22/hoopix/tree/main/lib/features/history/data"
click node_process "https://github.com/tiavina22/hoopix/blob/main/lib/core/process/process_runner.dart"
click node_platform "https://github.com/tiavina22/hoopix/tree/main/lib/core/platform"
click node_trash_native "https://github.com/tiavina22/hoopix/blob/main/macos/Runner/TrashChannel.swift"
click node_privileged_native "https://github.com/tiavina22/hoopix/blob/main/macos/Runner/PrivilegedDeleteChannel.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,node_shell,node_clean_ui,node_uninstall_ui,node_purge_ui,node_optimize_ui,node_analyze_ui,node_status_ui,node_history_ui,node_user toneBlue
class node_clean_engine,node_clean_data,node_uninstall_engine,node_uninstall_data,node_purge_engine,node_purge_data,node_optimize_engine,node_optimize_data,node_operation_log toneAmber
class node_analyze_engine,node_analyze_data,node_status_engine,node_status_data,node_history_data toneMint
class node_process,node_platform,node_trash_native,node_privileged_native toneRose
class node_macos toneIndigo
```

## Components

### App interface

- [App entry](https://github.com/tiavina22/hoopix/blob/main/lib/app.dart): `lib/app.dart`
- [Section navigation](https://github.com/tiavina22/hoopix/blob/main/lib/core/navigation/app_shell.dart): `lib/core/navigation/app_shell.dart`
- [Clean review](https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/presentation): `lib/features/clean/presentation`
- [Uninstall review](https://github.com/tiavina22/hoopix/tree/main/lib/features/uninstall/presentation): `lib/features/uninstall/presentation`
- [Purge review](https://github.com/tiavina22/hoopix/tree/main/lib/features/purge/presentation): `lib/features/purge/presentation`
- [Optimize controls](https://github.com/tiavina22/hoopix/tree/main/lib/features/optimize/presentation): `lib/features/optimize/presentation`
- [Disk explorer](https://github.com/tiavina22/hoopix/tree/main/lib/features/analyze/presentation): `lib/features/analyze/presentation`
- [Live status](https://github.com/tiavina22/hoopix/tree/main/lib/features/status/presentation): `lib/features/status/presentation`
- [Operation history](https://github.com/tiavina22/hoopix/tree/main/lib/features/history/presentation): `lib/features/history/presentation`

### Maintenance actions

- [Clean planning](https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/domain/usecases): `lib/features/clean/domain/usecases`
- [Clean discovery and removal](https://github.com/tiavina22/hoopix/tree/main/lib/features/clean/data): `lib/features/clean/data`
- [Uninstall discovery](https://github.com/tiavina22/hoopix/tree/main/lib/features/uninstall/domain/usecases): `lib/features/uninstall/domain/usecases`
- [App removal actions](https://github.com/tiavina22/hoopix/tree/main/lib/features/uninstall/data): `lib/features/uninstall/data`
- [Artifact planning](https://github.com/tiavina22/hoopix/tree/main/lib/features/purge/domain/usecases): `lib/features/purge/domain/usecases`
- [Artifact deletion](https://github.com/tiavina22/hoopix/tree/main/lib/features/purge/data): `lib/features/purge/data`
- [Maintenance tasks](https://github.com/tiavina22/hoopix/blob/main/lib/features/optimize/domain/usecases/run_optimize.dart): `lib/features/optimize/domain/usecases/run_optimize.dart`
- [Task execution](https://github.com/tiavina22/hoopix/blob/main/lib/features/optimize/data/datasources/optimize_task_runner.dart): `lib/features/optimize/data/datasources/optimize_task_runner.dart`

### Inspection and history

- [Disk scan operations](https://github.com/tiavina22/hoopix/tree/main/lib/features/analyze/domain/usecases): `lib/features/analyze/domain/usecases`
- [Disk scan sources](https://github.com/tiavina22/hoopix/tree/main/lib/features/analyze/data): `lib/features/analyze/data`
- [System snapshot](https://github.com/tiavina22/hoopix/blob/main/lib/features/status/domain/usecases/watch_system_status.dart): `lib/features/status/domain/usecases/watch_system_status.dart`
- [System probes](https://github.com/tiavina22/hoopix/tree/main/lib/features/status/data/datasources): `lib/features/status/data/datasources`
- [History reader](https://github.com/tiavina22/hoopix/tree/main/lib/features/history/data): `lib/features/history/data`

### Shared runtime

- [Process runner](https://github.com/tiavina22/hoopix/blob/main/lib/core/process/process_runner.dart): `lib/core/process/process_runner.dart`
- [File and system operations](https://github.com/tiavina22/hoopix/tree/main/lib/core/platform): `lib/core/platform`
- [Protected Trash channel](https://github.com/tiavina22/hoopix/blob/main/macos/Runner/TrashChannel.swift): `macos/Runner/TrashChannel.swift`
- [Privileged delete channel](https://github.com/tiavina22/hoopix/blob/main/macos/Runner/PrivilegedDeleteChannel.swift): `macos/Runner/PrivilegedDeleteChannel.swift`

### Other components

- **Mac user**
- **macOS tools and filesystem**
- **Operation log**

## Connections

- Mac user → App entry: launches
- App entry → Section navigation: builds interface
- Mac user → Section navigation: selects section
- Section navigation → Clean review: shows
- Section navigation → Uninstall review: shows
- Section navigation → Purge review: shows
- Section navigation → Optimize controls: shows
- Section navigation → Disk explorer: shows
- Section navigation → Live status: shows
- Section navigation → Operation history: shows
- Clean review → Clean planning: requests plan
- Clean planning → Clean discovery and removal: requests discovery
- Clean review → Clean discovery and removal: approves removal
- Uninstall review → Uninstall discovery: requests inventory
- Uninstall discovery → App removal actions: discovers app
- Uninstall review → App removal actions: approves uninstall
- Purge review → Artifact planning: requests plan
- Artifact planning → Artifact deletion: discovers artifacts
- Purge review → Artifact deletion: approves deletion
- Optimize controls → Maintenance tasks: starts tasks
- Maintenance tasks → Task execution: dispatches tasks
- Disk explorer → Disk scan operations: requests scan
- Disk scan operations → Disk scan sources: requests filesystem data
- Disk explorer → File and system operations: requests Trash move
- Live status → System snapshot: watches status
- System snapshot → System probes: requests probes
- Operation history → History reader: fetches records
- Clean discovery and removal → Process runner: runs commands
- App removal actions → Process runner: runs commands
- Artifact deletion → Process runner: runs commands
- Task execution → Process runner: runs commands
- System probes → Process runner: runs probes
- Disk scan sources → File and system operations: scans paths
- File and system operations → Protected Trash channel: invokes channel
- Clean discovery and removal → Privileged delete channel: requests privileged delete
- Task execution → Privileged delete channel: requests privileged task
- Process runner → macOS tools and filesystem: runs native tools
- File and system operations → macOS tools and filesystem: reads and moves files
- Protected Trash channel → macOS tools and filesystem: moves to Trash
- Privileged delete channel → macOS tools and filesystem: deletes allowlisted paths
- Clean discovery and removal → Operation log: records operations
- App removal actions → Operation log: records operations
- Artifact deletion → Operation log: records operations
- Task execution → Operation log: records operations
- History reader → Operation log: reads operations