Architecture

Tech Stack

• Swift 6 — actors, async/await, structured concurrency
• SwiftUI — @Observable, NavigationSplitView, Charts
• XcodeGen — project generation from project.yml
• OSLog — structured subsystem logging
• FoundationModels — on-device AI (macOS 26+)

Project Layers

App/              — App entry, AppDelegate, RootView with sidebar navigation
Features/         — One folder per feature (Cleanup, Dashboard, DiskAnalyzer, Processes, etc.)
Domains/          — Business logic (CleanupEngine, ProcessManager, LaunchServiceManager)
Infrastructure/   — Cross-cutting services (SafetyManager, TrashManager, PermissionsManager, etc.)
Models/           — Shared data types

Key Patterns

• Feature-oriented — each feature has its own Views, ViewModel, and supporting types
• State machine — CleanupCoordinator uses CleanupStateMachine (idle → scanning → preview → executing → completed)
• Parallel scanning — cleanup categories execute via withTaskGroup across all cores
• Safety gate — all file operations pass through SafetyManager which validates against protected paths
• Actors for isolation — TrashManager, UninstallerService, DiskScanner, AIExplanationService are actors

Cleanup Pipeline

CleanupViewModel
  → CleanupCoordinator (state machine)
    → CleanupEngine (parallel category execution)
      → CleanupPathProvider (embedded path arrays + dynamic discovery)
        → SafetyManager (path validation)
          → FileManager / CommandRunner (deletion)
    → TransactionJournal (persist history)

Navigation

RootView uses NavigationSplitView with a sidebar containing 7 items grouped into 4 sections (Dashboard, Tools, System, Settings).

AI Integration

AIExplanationService wraps LanguageModelSession from FoundationModels. Each feature (Cleanup, Disk Analyzer, Processes, etc.) calls the service with a context-specific prompt. The service is an actor; all calls are async.