SPB Git

Repository Public License

ARCHITECTURE.md 5.6 KB

# 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.

text
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 probe

# AlarmCore

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:

text
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:

swift
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.

Files main
Menu

Theme