CleanMM/Docs/Architecture.md

# Architecture

## High-Level Topology

- `AtlasApp` — main macOS application shell
- `AtlasWorkerXPC` — non-privileged worker service
- `AtlasPrivilegedHelper` — allowlisted helper executable for structured destructive actions
- `AtlasCoreAdapters` — wrappers around reusable upstream and local system capabilities
- `AtlasStore` — persistence for runs, rules, recovery, settings, diagnostics, and the app-language preference

## Layering

### Presentation

- SwiftUI scenes and views
- Navigation state
- View models or reducers
- App-language selection and locale injection at the app shell

### Application

- Use cases such as `StartScan`, `PreviewPlan`, `ExecutePlan`, `RestoreItems`
- App uninstall flows: `ListApps`, `PreviewAppUninstall`, `ExecuteAppUninstall`
- Settings flows: `GetSettings`, `UpdateSettings`

### Domain

- `Finding`
- `ActionPlan`
- `ActionItem`
- `TaskRun`
- `RecoveryItem`
- `RecoveryPayload`
- `AppFootprint`
- `PermissionState`
- `AtlasSettings`
- `AtlasLanguage`

### Infrastructure

- XPC transport
- JSON-backed workspace state persistence
- Recovery-state normalization that prunes expired recovery entries on load/save
- Logging and audit events
- Best-effort permission inspection
- Helper executable client
- Process orchestration

### Execution

- Upstream adapters: `MoleHealthAdapter`, `MoleSmartCleanAdapter`
- Release and packaged worker flows load upstream shell runtime from bundled `MoleRuntime` resources instead of source-tree paths
- Local adapters: `MacAppsInventoryAdapter`
- Recovery-first state mutation for Smart Clean and app uninstall flows
- Allowlisted helper actions for bundle trashing, restoration, and launch-service removal
- Release-facing execution must fail closed when real worker/adapter/helper capability is unavailable; scaffold fallback is development-only by opt-in
- Smart Clean now supports a real Trash-based execution path for a safe structured subset of user-owned targets, plus physical restoration when recovery mappings are present
- Restore requests recheck expiry and destination conflicts before side effects, so expired or conflicting recovery items fail closed

## Process Boundaries

- UI must not parse shell output directly.
- UI must not execute privileged shell commands directly.
- `AtlasWorkerXPC` owns long-running task orchestration and progress events.
- Direct-distribution builds default to the same real worker implementation in-process; `AtlasWorkerXPC` remains available behind `ATLAS_PREFER_XPC_WORKER=1` for explicit runtime validation.
- `AtlasPrivilegedHelper` accepts structured actions only and validates paths before acting.
- Persistent workspace mutation belongs behind the repository/worker boundary rather than ad hoc UI state.
- UI copy localization is sourced from structured package resources instead of hard-coded per-screen strings.

## Distribution Direction

- Distribution target: `Developer ID + Hardened Runtime + Notarization`
- Initial release target: direct distribution, not Mac App Store
- Native packaging currently uses `xcodegen + xcodebuild`, embeds the helper into `Contents/Helpers/`, and emits `.zip`, `.dmg`, and `.pkg` distribution artifacts.
- Tagged GitHub Releases reuse the same native packaging scripts in CI and publish `.zip`, `.dmg`, `.pkg`, and checksum assets.
- When release signing credentials are configured, CI signs and notarizes those assets; otherwise it falls back to a local development signing identity and marks the GitHub Release as a prerelease.
- Local internal packaging now prefers a stable non-ad-hoc app signature when a usable identity is available, so macOS TCC decisions can survive rebuilds more reliably during development.
- If Apple release certificates are unavailable, Atlas can fall back to a repo-managed local signing keychain for stable app-bundle identity; public release artifacts still require `Developer ID`.

## Security Principles

- Least privilege by default
- Explain permission need before request
- Prefer `Trash` or recovery-backed restore paths
- Audit all destructive actions