Personal project

StorageLens

Native macOS app that shows where disk space went and reclaims it safely

Status: In progress
Role: Solo: product plan, architecture, Swift implementation

Native SwiftUI + Swift 6
Measures real allocation, not file size
Evidence-based cleanup catalog
Trash-first, undoable cleanup

The app model asks the volume probe for capacity, which reads statfs, and probes Full Disk Access.

Architecture · 10 nodes · 4 flows

Service / compute
Data store
Client
External system
Synchronous
Async / loop

Scroll sideways to see the full diagram

How it flows, step by step

Click a step to jump to it. Click a component for details.

What it does

StorageLens is a native macOS app that explains where disk space went. It reports the distinct free-space figures macOS exposes, scans the volume into a squarified treemap and category bar, and offers a curated, versioned catalog of cleanup targets with risk tiers and plain-language consequences. Deletion goes to the Trash by default, with a dry-run plan, an operation log and a verified space delta.

The problem

macOS Storage settings hide what uses the disk and report several free-space numbers that disagree. Existing cleaners are opaque. StorageLens shows accurate numbers first and only then offers informed, recoverable cleanup.

What I built

Capacity accounting surfaces the distinct free-space figures macOS reports (including purgeable space) instead of collapsing them into one misleading number.
Streaming, cancellable scanner built on getattrlistbulk with bounded concurrency, measuring physical allocation, feeding a squarified treemap and a category bar.
Versioned JSON catalog of cleanup targets with risk tiers (safe, low, judgment, never), regeneration cost and evidence for every claim, correctable without shipping a new binary.
Conservative deletion semantics: Trash by default, dry-run plan, operation log, undo, and a re-stat of the volume to report the real reclaimed delta.
Measurement logic lives in a dependency-free local Swift package (StorageLensKit), separate from the SwiftUI target, with fixture-based unit tests and comparison against system output.
Full Disk Access probe returns a tri-state (granted, denied, unknown) so the UI degrades honestly; Xcode project is generated from a versioned XcodeGen spec.

Key decisions and why

Native Swift instead of a cross-platform stack

Correct file semantics need low-level APIs: physical allocation via st_blocks, fast traversal via getattrlistbulk, and accurate volume stats via statfs.

Measurement kit separated from the UI

A package with no external dependencies keeps scanner, accounting math and catalog matching testable on synthetic trees, without a real multi-hundred-GB disk.

The catalog is the product, not the treemap

Visualizers and cleaners already exist; the differentiator is a versioned catalog of cleanup targets with risk tiers, evidence and plain-language consequences.

Trash-first deletion with verified results

Recoverable removal via NSWorkspace, exact paths shown before acting, and a re-stat after cleanup so success is never claimed from a return code alone; root-owned paths use a minimal privileged helper.

Non-sandboxed, Developer ID distribution

Scanning the whole disk requires Full Disk Access, which does not fit the App Store sandbox; the app ships as a notarized DMG.

Tech stack

Languages: Swift 6
Frontend: SwiftUI
DevOps: Swift Package ManagerXcodeGen
Backend: Darwin APIs (statfs)SMAppService + XPCgetattrlistbulk
Testing: XCTest