SPB Git

Repository Public License

ARCHITECTURE.md 5.6 KB 82 lines markdown

1<!--2ORIX Alarm3File: docs/ARCHITECTURE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89ORIX Alarm is a native iOS 26.1+ app: Swift 6, SwiftUI, AlarmKit, WidgetKit, ActivityKit, App Intents, AVFoundation, Core Haptics, Core Motion, Swift Charts. No third-party package, no network code, no backend.1011```12ORIXAlarm.xcodeproj  (generated by XcodeGen from project.yml, never committed)13├── Packages/AlarmCore     pure logic, no UIKit / AlarmKit — `swift test` on the Mac14├── App                    the iPhone app (MainActor by default)15│   ├── Sources            ORIXAlarmApp, AppModel, RootView16│   ├── Alarm              SystemAlarmService (AlarmKit + fake), App Shortcuts17│   ├── Design             Theme, formatting18│   ├── Wake               audio engine, haptic engine, sound effects19│   ├── Features           Dashboard, Clock, Alarms, Editor, Studio, Missions, Nightstand, Sleep, Insights, Settings20│   └── Resources          assets, synthesised sounds21├── Shared                 compiled into the app and the widget extension (alarm intents, metadata, widget snapshot)22├── Widgets                widget extension: five widgets and the AlarmKit Live Activity23├── Tests                  integration tests of AppModel against the fake alarm service24└── UITests                interface tests and the real-AlarmKit simulator probe25```2627## AlarmCore2829| Area | Types | Role |30|---|---|---|31| Models | `AlarmDefinition`, `WakeScenario`, `MissionStep`, `SnoozePolicy`, `ProgressiveWake`, `IntensityCurve`, `SleepPlan`, `AppSettings`, `QRTag`, `WakeEvent` | Codable, Sendable values |32| Scheduling | `Recurrence`, `Reconciler`, `StableID`, `RuntimeState` / `Occurrence` | next occurrence (DST, time zones), system-versus-local reconciliation, deterministic identifiers, the state machine of one morning |33| Missions | `PuzzleEngine` and one engine per mission, `AdaptiveEngine`, `SeededGenerator` | deterministic generation, pure validation, interpretable adaptive difficulty |34| Wake | `ProgressiveWakeTimeline` | stage and intensity of the progressive wake at a given instant |35| Sleep | `SleepPlanner` | bedtime maths, evening rollover, weekly consistency series |36| Analytics | `WakeStatistics` | statistics from recorded events only |37| Persistence | `JSONFileStore`, `Library`, `History`, `ExportArchive` | versioned atomic JSON, backup, corruption recovery, migrations, export |3839Everything that can be wrong in a subtle way (dates, policies, puzzle validity, storage recovery) lives here so it is tested without a simulator.4041## AppModel4243One `@Observable` main-actor object owns the state: the library, the history, the runtime occurrences, the authorization, the verified system status of each alarm and the mission run being presented. Views read it from the environment and call its methods; they never talk to AlarmKit.4445The system scheduler is behind `SystemAlarmService`:4647- `AlarmKitService` — the real implementation (`AlarmManager`);48- `FakeAlarmService` — in memory, used by unit tests and by UI tests (`-ORIXUITest YES`), able to simulate firing, loss, denial and the system limit.4950Flow of one morning:5152```53system alert ──► user stops ──► (intent, or observed state change) ──► AppModel.handle(.stopped)54     │                                                                      │ records `acknowledged`55     └─► user snoozes ──► SnoozeAlarmIntent ──► AppModel.snooze            ▼56              policy → follow-up countdown (Live Activity)        mission run presented (MissionRunnerView)57                                                                     steps → `missionCompleted` / `missionBypassed`58                                                                     "I'm up" → `wakeConfirmed`59```6061A stop reaches the model by two independent paths: the alarm's stop intent, and the observation of `AlarmManager.alarmUpdates` (an alarm that was alerting and no longer is). When the app was not running, the next activation derives the same facts from the schedule and the current system state and marks them as such. The main alarm never depends on the mission code: a mission that cannot run (no camera, no pedometer, missing QR tag) is replaced by a fallback or skipped through the emergency exit.6263## Missions6465Each mission is a pure engine in AlarmCore plus one SwiftUI view with the same contract:6667```swift68struct XMissionView: View { let mission: ResolvedMission; let onFinish: (MissionOutcome) -> Void }69```7071`MissionRunnerView` runs a sequence (the "Morning Combo"), shows progress, swaps in an alternative when a mission reports `.unavailable` or when the user asks for one, offers the emergency exit, then asks for the wake confirmation. See `docs/MISSIONS.md`.7273## Widgets and intents7475The widget extension cannot ask AlarmKit about the app's alarms, so the app writes a small `widget-snapshot.json` in the app group container. The timeline has one entry after each upcoming alarm, so a widget moves to the following alarm without the app running. The Live Activity renders AlarmKit's `AlarmAttributes<ORIXAlarmMetadata>` (snooze and focus-timer countdowns).7677App Intents for Shortcuts and Siri live in `App/Alarm/AppShortcuts.swift`; they call the same `AppModel` methods as the interface and report scheduling failures instead of pretending.7879## Concurrency8081The app target uses main-actor default isolation; AlarmCore is a regular Swift 6 package with `Sendable` values. Types shared with the widget extension are marked `nonisolated`. `AlarmManager` is not `Sendable`; the single reference to it is `nonisolated(unsafe)` in `AlarmKitService`.82
Files main
Menu

Theme