Architecture
ORIX 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.
ORIXAlarm.xcodeproj (generated by XcodeGen from project.yml, never committed)
├── Packages/AlarmCore pure logic, no UIKit / AlarmKit — `swift test` on the Mac
├── App the iPhone app (MainActor by default)
│ ├── Sources ORIXAlarmApp, AppModel, RootView
│ ├── Alarm SystemAlarmService (AlarmKit + fake), App Shortcuts
│ ├── Design Theme, formatting
│ ├── Wake audio engine, haptic engine, sound effects
│ ├── Features Dashboard, Clock, Alarms, Editor, Studio, Missions, Nightstand, Sleep, Insights, Settings
│ └── Resources assets, synthesised sounds
├── Shared compiled into the app and the widget extension (alarm intents, metadata, widget snapshot)
├── Widgets widget extension: five widgets and the AlarmKit Live Activity
├── Tests integration tests of AppModel against the fake alarm service
└── UITests interface tests and the real-AlarmKit simulator probeAlarmCore
| Area | Types | Role |
|---|---|---|
| Models | AlarmDefinition, WakeScenario, MissionStep, SnoozePolicy, ProgressiveWake, IntensityCurve, SleepPlan, AppSettings, QRTag, WakeEvent |
Codable, Sendable values |
| Scheduling | Recurrence, Reconciler, StableID, RuntimeState / Occurrence |
next occurrence (DST, time zones), system-versus-local reconciliation, deterministic identifiers, the state machine of one morning |
| Missions | PuzzleEngine and one engine per mission, AdaptiveEngine, SeededGenerator |
deterministic generation, pure validation, interpretable adaptive difficulty |
| Wake | ProgressiveWakeTimeline |
stage and intensity of the progressive wake at a given instant |
| Sleep | SleepPlanner |
bedtime maths, evening rollover, weekly consistency series |
| Analytics | WakeStatistics |
statistics from recorded events only |
| Persistence | JSONFileStore, Library, History, ExportArchive |
versioned atomic JSON, backup, corruption recovery, migrations, export |
Everything that can be wrong in a subtle way (dates, policies, puzzle validity, storage recovery) lives here so it is tested without a simulator.
AppModel
One @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.
The system scheduler is behind SystemAlarmService:
AlarmKitService— the real implementation (AlarmManager);FakeAlarmService— in memory, used by unit tests and by UI tests (-ORIXUITest YES), able to simulate firing, loss, denial and the system limit.
Flow of one morning:
system alert ──► user stops ──► (intent, or observed state change) ──► AppModel.handle(.stopped)
│ │ records `acknowledged`
└─► user snoozes ──► SnoozeAlarmIntent ──► AppModel.snooze ▼
policy → follow-up countdown (Live Activity) mission run presented (MissionRunnerView)
steps → `missionCompleted` / `missionBypassed`
"I'm up" → `wakeConfirmed`A 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.
Missions
Each mission is a pure engine in AlarmCore plus one SwiftUI view with the same contract:
struct XMissionView: View { let mission: ResolvedMission; let onFinish: (MissionOutcome) -> Void }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.
Widgets and intents
The 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).
App 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.
Concurrency
The 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.