WIP

docs/ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Architecture
+
+ClipBored is a single-process AppKit utility built with Swift Package Manager.
+
+## Runtime Shape
+
+- `ClipBoredApp` creates `NSApplication`, sets accessory activation, installs `AppDelegate`, and starts the run loop.
+- `AppDelegate` wires shared services, status menu items, settings observers, and global shortcuts.
+- `ClipboardMonitorService` polls `NSPasteboard.changeCount` on a utility queue with adaptive active/idle intervals.
+- `ClipboardStore` keeps the in-memory item list and persists rows to SQLite on a serial queue.
+- `ClipboardCacheService` stores bounded image previews under Application Support and keeps a small `NSCache`.
+- `ShortcutManager` registers Carbon hotkeys for app-wide commands.
+- `ClipboardPanelController` owns the bottom panel lifecycle and target-app tracking.
+- `ClipboardPanelViewModel` filters, sorts, selects, copies, pastes, pins, organizes, deletes, opens, and reveals items.
+- `SettingsWindowController` exposes native controls for capture, privacy, performance, shortcuts, and data management.
+
+## Data Flow
+
+1. The monitor notices a pasteboard change.
+2. Source app metadata is checked against ignored apps.
+3. Pasteboard content is normalized into a `ClipboardItem`.
+4. Sensitive text is skipped when exclusion is enabled.
+5. Copied images run local Vision OCR only when `Search in image labels` is enabled.
+6. The store deduplicates, preserves pinned and collection-assigned items, enforces limits, and persists the mutation.
+7. The panel view model receives store updates and recomputes the visible list.
+
+## Persistence
+
+History is stored in SQLite at:
+
+```text
+~/Library/Application Support/ClipBored/history.sqlite
+```
+
+Images are stored under:
+
+```text
+~/Library/Application Support/ClipBored/images/
+```
+
+Restorable non-image payloads such as audio clips, rich text, and PDFs are stored under:
+
+```text
+~/Library/Application Support/ClipBored/attachments/
+```
+
+Legacy JSON import still exists for migration from early builds.
+
+Textual SQLite fields, including optional collection names and image OCR text, are encrypted and decrypted at the `ClipboardStore` boundary. App-managed image cache files, URL preview thumbnails, audio clips, rich text sidecars, and PDF attachments are encrypted and decrypted at the `ClipboardCacheService` boundary. The encryption key is stored in Keychain when available, with an owner-only app-local fallback key if Keychain access blocks or fails. Full history clears remove the local fallback key when present and reset cached key state after SQLite deletion succeeds. Runtime `ClipboardItem` values remain plaintext in memory so search, duplicate detection, copy, paste, organization, and cache cleanup operate normally. Opening or revealing encrypted media creates a temporary decrypted copy for macOS handoff; stale temporary previews are cleared on launch, cache/history clear, and quit.
+
+## Size And Power Constraints
+
+The release build intentionally avoids SwiftUI, Combine, Swift Concurrency, third-party packages, bundled media, and app resources beyond `Info.plist`.
+
+The build script uses `-Osize`, whole-module optimization, disabled reflection metadata, linker dead stripping, symbol stripping, and hardened-runtime signing. The current public targets, enforced by `scripts/build-macos-app.sh`, are a 1 MiB executable and a 1.8 MB app bundle.