# jpferreria/cleanup-mac architecture

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

- Interactive diagram: https://gitdiagram.com/jpferreria/cleanup-mac
- Repository: https://github.com/jpferreria/cleanup-mac

## Overview

The repository provides two macOS cleanup experiences: a native SwiftUI app and a Python command-line utility. Both let users inspect categorized reclaimable storage and remove selected data; the app also offers Apple Intelligence advice and a Siri/Shortcuts health check. The CLI’s scan and clean flows are visible in its source. Swift excerpts show UI actions, cleanup behavior, model evaluation, and the intent, but omit parts of the scan orchestration, so those internal links are not inferred.

Main entry points: [`CleanupApp.swift`](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift) (Cleanup view model), [`cleanup.py`](https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_swift["Native macOS app"]
  node_swiftui["Cleanup interface<br/>[CleanupApp.swift]"]
  node_swiftmodel["Cleanup view model<br/>[CleanupApp.swift]"]
  node_swiftcategories["Cleanup categories<br/>[CleanupApp.swift]"]
  node_swiftclean["Selected cleanup<br/>[CleanupApp.swift]"]
  node_intent["Storage health intent<br/>[CleanupApp.swift]"]
end

subgraph group_cli["Python CLI"]
  node_cli["CLI commands<br/>[cleanup.py]"]
  node_clicategories["CLI categories<br/>[cleanup.py]"]
  node_cliscan["Size scanner<br/>[cleanup.py]"]
  node_clidelete["Category deletion<br/>[cleanup.py]"]
end

subgraph group_advisor["Storage advice"]
  node_foundation["On-device assessment<br/>[CleanupApp.swift]"]
  node_heuristic["Fallback advisor<br/>[CleanupApp.swift]"]
end

node_user(("Mac user"))
node_siri(("Siri / Shortcuts"))
node_cliuser(("CLI user"))
node_filesystem[("macOS filesystem")]

node_user -->|"uses"| node_swiftui
node_swiftui -->|"requests scan"| node_swiftmodel
node_swiftui -->|"requests cleanup"| node_swiftmodel
node_swiftmodel -->|"cleans selected"| node_swiftclean
node_siri -->|"checks health"| node_intent
node_intent -->|"requests assessment"| node_foundation
node_swiftmodel -->|"evaluates storage"| node_foundation
node_swiftmodel -->|"falls back"| node_heuristic
node_cliuser -->|"runs command"| node_cli
node_cli -->|"runs scan"| node_cliscan
node_cli -->|"runs clean"| node_clidelete
node_cliscan -->|"reads paths"| node_clicategories
node_cliscan -->|"measures files"| node_filesystem
node_clidelete -->|"reads paths"| node_clicategories
node_clidelete -->|"deletes contents"| node_filesystem

click node_swiftui "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_swiftmodel "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_swiftcategories "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_swiftclean "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_intent "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_foundation "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_heuristic "https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift"
click node_cli "https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py"
click node_clicategories "https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py"
click node_cliscan "https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py"
click node_clidelete "https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py"

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_swiftui,node_swiftmodel,node_swiftcategories,node_swiftclean,node_intent,node_user,node_cliuser toneBlue
class node_cli,node_clicategories,node_cliscan,node_clidelete,node_filesystem toneAmber
class node_foundation,node_heuristic toneMint
class node_siri toneIndigo
```

## Components

### Native macOS app

- [Cleanup interface](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`
- [Cleanup view model](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`
- [Cleanup categories](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`
- [Selected cleanup](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`
- [Storage health intent](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`

### Python CLI

- [CLI commands](https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py): `cleanup.py`
- [CLI categories](https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py): `cleanup.py`
- [Size scanner](https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py): `cleanup.py`
- [Category deletion](https://github.com/jpferreria/cleanup-mac/blob/main/cleanup.py): `cleanup.py`

### Storage advice

- [On-device assessment](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`
- [Fallback advisor](https://github.com/jpferreria/cleanup-mac/blob/main/CleanupApp.swift): `CleanupApp.swift`

### Other components

- **Mac user**
- **Siri / Shortcuts**
- **CLI user**
- **macOS filesystem**

## Connections

- Mac user → Cleanup interface: uses (evidence: `README.md`)
- Cleanup interface → Cleanup view model: requests scan (evidence: `CleanupApp.swift`)
- Cleanup interface → Cleanup view model: requests cleanup (evidence: `CleanupApp.swift`)
- Cleanup view model → Selected cleanup: cleans selected (evidence: `CleanupApp.swift`)
- Siri / Shortcuts → Storage health intent: checks health (evidence: `README.md`)
- Storage health intent → On-device assessment: requests assessment (evidence: `CleanupApp.swift`)
- Cleanup view model → On-device assessment: evaluates storage (evidence: `CleanupApp.swift`)
- Cleanup view model → Fallback advisor: falls back (evidence: `CleanupApp.swift`)
- CLI user → CLI commands: runs command (evidence: `README.md`)
- CLI commands → Size scanner: runs scan (evidence: `cleanup.py`)
- CLI commands → Category deletion: runs clean (evidence: `cleanup.py`)
- Size scanner → CLI categories: reads paths (evidence: `cleanup.py`)
- Size scanner → macOS filesystem: measures files (evidence: `cleanup.py`)
- Category deletion → CLI categories: reads paths (evidence: `cleanup.py`)
- Category deletion → macOS filesystem: deletes contents (evidence: `cleanup.py`)
