Architecture

Project Structure

MacOSCleaner/
├── App/                 App lifecycle, RootView, routing
├── Features/            Feature modules (one per capability)
├── Domains/             Domain logic (cleanup engine, services)
├── Resources/           Localized strings, catalog data
├── project.yml          XcodeGen project definition
└── scripts/             Build-time tools

Features

Each feature is a self-contained module:

• Dashboard — disk usage rings, system info, cleanup history card and History window (⌘Y)
• Cleanup — scan UI (base + extended), cleanup execution, script logs
• DiskAnalyzer — folder scanning with breadcrumb navigation, Quick Look preview, search
• Duplicates — duplicate detection with master-detail review UI
• Uninstaller — app removal with deep scan, orphan detection with evidence scoring, post-uninstall leftovers sheet, helper-app collapsing
• Updates — in-app update notification sheet, update prompt controller
• Processes — process list and control
• StartupServices — launch agent management, service deletion
• Settings — modular settings UI
• AppIntents — Siri/Shortcuts integration
• Permissions — Full Disk Access guidance and prompts

Domains

• Cleanup — CleanupEngine (per-category logic), CleanupCoordinator (orchestration, app soft-quit, review-only leaf selection), SafetyManager (path protection with strict allowed roots), DuplicateFinderEngine, SystemMaintenanceService (Spotlight reindex), registry types
• ProcessManagement — AppQuitter (3-second graceful quit, then force-terminate), ProcessSafetyPolicy (protected process blocklist)
• StartupServices — LaunchServiceManager, LaunchdControl (bootout)
• Services — SystemInfoService, NetworkService, UpdateService, ProcessService, StartupServicesScanner
• Storage — StorageInfoService (disk usage)

Path Registry

The cleanup and uninstaller databases are a private catalog (not committed to the public repository):

• engine_paths.json — 2,343 path definitions for 304 apps and 92 toolchains, version 3.0 format
• ui_metadata.json — display names, icons, difficulty ratings
• catalog_policy.json — policy file validated at build time; required together with the other two files

At build time they are packed into a binary catalog asset (PrivateCleanupCatalog.dataset) by scripts/generate_cleanup_paths.swift, which writes and verifies the packed asset. Public builds without the source files use the compiled fallback catalog (EmbeddedCleanupPaths).

Path Template Tokens

Paths are stored as templates with tokens resolved at runtime:

Token	Resolves to
<APP_SUPPORT>	~/Library/Application Support
<CACHES>	~/Library/Caches
<PREFS>	~/Library/Preferences
<CONTAINERS>	~/Library/Containers
<GROUP_CONTAINERS>	~/Library/Group Containers
<LOGS>	~/Library/Logs
<SAVED_STATE>	~/Library/Saved Application State
<HOME>	~
<USER_LIB>	~/Library
<USER_CACHE>	~/Library/Caches
<USER_CONFIG>	~/.config
<USER_LOCAL_SHARE>	~/.local/share
<VAR_FOLDERS>	/var/folders
<SYS_LIB>	/Library
<SYS_APP_SUPPORT>	/Library/Application Support
<SYS_LAUNCH_AGENTS>	/Library/LaunchAgents
<SYS_LAUNCH_DAEMONS>	/Library/LaunchDaemons
<SYS_PRIV_HELPERS>	/Library/PrivilegedHelperTools
<SYS_CACHES>	/Library/Caches
<SYS_PREFS>	/Library/Preferences
<SYS_LOGS>	/Library/Logs

Path Purposes

Purpose	Meaning
cache	Regenerable, cleaned by default
app_data	Uninstall-only, never touched by cleanup
shared	Shared with other apps, never automatic
user_content	Personal content, opt-in only

App Intents

The AppIntents feature declares five intents exposed to Siri/Shortcuts/Automator: clean developer caches, clean a category, get storage status, run scheduled cleanup, empty Trash. Mutating intents require system authentication. Each can be toggled in Settings → Automation. See Siri & Automation.

Root View

The app uses a floating glass pill navigation bar (no sidebar): Dashboard, Cleanup, Disk Space, Duplicates, Uninstaller, Processes, Startup Services, Settings — mapped to ⌘1–⌘8. Switching the language reloads the interface via a view identity change.

Threading & Swift 6

Domain logic uses Swift actors (CleanupCoordinator, DuplicateFinderEngine, services). The project is built with Swift 6 language mode and strict concurrency checking (SWIFT_STRICT_CONCURRENCY: complete).

Build System

XcodeGen (project.yml) generates the Xcode project. A pre-build script validates the private catalog (all three JSON files required together for maintainer builds) and verifies the packed asset; public builds fall back to the embedded catalog. See Building from Source.