How nihaldr/ultimate_alarm_clock works
1. Overall shape
- This is a cross-platform Flutter app for alarm/timer/world-clock use, but the architecture is heavily split between a Flutter UI layer and a native Android Kotlin layer for background execution, alarm scheduling, boot recovery, and smart controls.
- The repo also contains iOS, macOS, Windows, Linux, and Web shells, but the most complex runtime behavior is on Android.
2. Flutter presentation layer
- The app uses GetX in a standard module / controller / view / binding structure under lib/app/modules.
- Each screen is isolated as a module: home, settings, add/update alarm, alarm ring, alarm challenges, timer, stopwatch, world clock, notifications, debug, about, splash, and bottom navigation.
- app_pages.dart and app_routes.dart centralize navigation; bindings wire controllers and services into each route.
3. Domain model layer
- Core data objects live under lib/app/data/models and represent the app’s main entities: alarms, timers, profiles, users, ringtones, quotes, flags, world clocks, and debug state.
- The generated *.g.dart files indicate code-generated persistence serialization, which suggests these models are shared across UI, local storage, and backend sync logic.
4. Local persistence boundary
- The app uses multiple persistence systems for different responsibilities:
- Isar for fast offline alarm data and app state.
- SQLite / SQFLite for cross-language sharing with native Kotlin code.
- Flutter Secure Storage for sensitive settings and tokens.
- GetStorage for lightweight app preferences.
- This separation matters architecturally: alarm data can be read locally by both Flutter and native code, while secrets and user preferences stay in secure/local key-value storage.
5. Remote backend boundary
- Firebase Firestore is the main cloud data source for shared alarms, shared profiles, and user-related collaboration state.
- Firebase Cloud Functions in functions/ provide server-side helpers such as sendNotification and rescheduleAlarm, which act as backend coordination points for shared alarm workflows.
- Firebase config files in Android/iOS and Firestore rules/indexes confirm that cloud sync is a first-class subsystem, not an add-on.
6. Android native alarm engine
- The Android Kotlin code under android/app/src/main/kotlin/... is the execution engine for time-critical behavior.
- Key responsibilities are split across:
- AlarmReceiver / BootReceiver for alarm firing and reboot recovery.
- AlarmUtils for alarm scheduling helpers.
- SmartControlCombinationService, ScreenMonitorService, and LocationFetcherService / WeatherFetcherService for smart dismissal and environmental checks.
- Timer-related classes for exact timer execution and notification behavior.
- The README’s migration note is important: scheduling and smart-control logic were moved into Kotlin to avoid waking the Flutter app in the background.
7. Alarm lifecycle flow
- Alarm creation/editing starts in Flutter, mainly from the add/update alarm module.
- The alarm configuration is persisted locally and/or synced to Firestore depending on whether the alarm is shared.
- Native Android code then takes over for exact scheduling, boot rescheduling, and ring-time delivery; when the alarm triggers, the app transitions into the alarm ring and challenge flows.
8. Smart controls and wake-up challenges
- A major feature boundary is the “smart alarm” layer that can automatically dismiss or modify alarm behavior based on:
- screen activity
- weather
- location
- shake
- QR code
- math
- pedometer
- sunrise / ambient effects
- These are surfaced in Flutter as configuration tiles, but the enforcement often depends on native services and background checks.
9. Shared alarms and profiles
- Shared alarms are synchronized through Firestore and coordinated with Firebase Messaging for real-time updates when another user changes or accepts an alarm.
- The app supports shared user lists, accept/reject flows, profile-based alarm grouping, and persistence so shared alarms survive app kills and device reboot.
- This is a key distributed-system boundary in the repo: the same alarm can exist locally, in Firestore, and in the native scheduler simultaneously.
10. Timer subsystem
- Timers are a separate subsystem with their own Flutter module, local database helper, notification handling, and native support.
- The timer feature supports multiple concurrent timers, background notifications when minimized, and direct database access from Kotlin for reliability and performance.
- Treat it as parallel to alarms rather than just another screen.
11. Startup, settings, and app shell
- main.dart initializes the app, then the splash screen leads into the main navigation shell and home view.
- Settings provide the control plane for theme, language, haptics, 24-hour format, weather API, Google sign-in, and sorted alarm list behavior.
- The UI is therefore mostly a configuration and orchestration layer over the local/cloud/native subsystems.
12. External services and integrations
- Relevant integrations include Google Sign-In, Google Calendar, Firebase Cloud Messaging, Open-Meteo weather, and optional media/ringtone playback.
- Some utilities also suggest integration points for location lookup, Spotify playback, and custom/system ringtone selection.
- For an architecture diagram, these are external edges connected mostly through the settings, alarm configuration, and smart-control paths.
13. Operational support
- The repository includes GitHub Actions, Dependabot, pre-commit hooks, Firestore rules/indexes, and platform-specific packaging for Android/iOS desktop/web.
- These do not define the runtime architecture, but they show the project is maintained as a full multi-platform Flutter product with Firebase-backed backend services and native mobile scheduling.
Main entry points: app_pages.dart Page config · add_or_update_alarm_view.dart Add alarm · alarm_ring_view.dart Alarm ring · alarm_model.dart Domain models
Components 23
Flutter app
Presentation, state, models, and app orchestration in Dart.
- main.dart · Initializes the Flutter app and hands off to splash/navigation.
lib/main.dart - App routes · Central route and page mapping for the app shell.
lib/app/routes/app_routes.dart - Page config · Route-to-module wiring used by GetX navigation.
lib/app/routes/app_pages.dart - Home · Main alarm list and entry point into key app flows.
lib/app/modules/home/views/home_view.dart - Add alarm · Creates and edits alarms, including smart controls and sharing.
lib/app/modules/addOrUpdateAlarm/views/add_or_update_alarm_view.dart - Alarm ring · Full-screen alarm presentation and wake-up effects.
lib/app/modules/alarmRing/views/alarm_ring_view.dart - Challenges · Math, shake, QR, and pedometer dismissal challenge screens.
lib/app/modules/alarmChallenge/views/alarm_challenge_view.dart - Timer · Timer UI and countdown orchestration separate from alarms.
lib/app/modules/timer/views/timer_view.dart - Timer ring · Timer completion experience and alert UI.
lib/app/modules/timerRing/views/timer_ring_view.dart - World clock · World clock browsing and timezone display.
lib/app/modules/worldClock/views/world_clock_view.dart - Settings · Theme, language, haptics, format, API, and sign-in settings.
lib/app/modules/settings/views/settings_view.dart - Domain models · Alarm, timer, profile, user, ringtone, clock, and debug data models.
lib/app/data/models/alarm_model.dart - Local storage · Isar, SQLite, secure storage, and key-value preferences behind the Dart app.
lib/app/data/providers/isar_provider.dart - Push layer · Push notification and cloud API integration from Flutter.
lib/app/data/providers/push_notifications.dart
Android engine
Native Kotlin scheduling, receivers, background services, and timer execution.
- Alarm receiver · Receives exact alarm triggers and wakes ring-time behavior.
android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmReceiver.kt - Boot receiver · Restores scheduled alarms after device reboot.
android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/BootReceiver.kt - Alarm utils · Native alarm scheduling and helper logic.
android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmUtils.kt - Smart services · Screen, location, weather, and combination services used by smart dismiss rules.
android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/SmartControlCombinationService.kt - Native timer · Timer database, receiver, service, and notifications for reliable background timers.
android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/TimerService.kt - Android DB · Native database helpers used to share alarm and timer state with Kotlin code.
android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/DatabaseHelper.kt
Firebase backend
Cloud sync, notifications, and server-side alarm coordination.
- Firestore sync · Shared alarms, profiles, and collaboration state in Firestore.
firestore.rules - Cloud functions · Server-side reschedule and notification helpers for shared alarms.
functions/index.js
Platform shells
Desktop, mobile, and web host shells for the Flutter app.
- Platform shells · Flutter host projects for mobile, desktop, and web packaging.
ios/Runner/AppDelegate.swift
Connections 28
- main.dart → App routes: boots into · App startup config leads into navigation setup.
- App routes → Page config: maps · Route names resolve to page/module bindings.
- Page config → Home: opens · Home is a primary route target.
- Page config → Add alarm: opens · Alarm creation and editing route.
- Page config → Alarm ring: opens · Alarm ring screen route.
- Page config → Challenges: opens · Challenge flows are routed as part of dismissal.
- Page config → Timer: opens · Timer module route.
- Page config → Timer ring: opens · Timer completion route.
- Page config → World clock: opens · World clock route.
- Page config → Settings: opens · Settings route.
- Home → Domain models: renders · Home consumes alarm and profile entities.
- Add alarm → Domain models: edits · Alarm editor works with shared domain objects.
- Settings → Local storage: configures · Theme, language, and preferences are stored locally.
- Domain models → Local storage: persists in · Core entities are serialized to local storage.
- Local storage → Android DB: shares state · Some alarm/timer state is mirrored for native access.
- Add alarm → Firestore sync: syncs shared alarms · Shared alarms and profiles are written to Firestore.
- Firestore sync → Cloud functions: triggers · Cloud functions coordinate shared alarm actions.
- Push layer → Firestore sync: consumes updates · Notification and sync flows depend on cloud state.
- Add alarm → Alarm utils: schedules · Alarm setup is handed to native scheduling helpers.
- Alarm utils → Alarm receiver: fires through · Exact scheduled alarms are delivered to the receiver.
- Boot receiver → Alarm utils: restores · Boot recovery re-creates pending alarm schedules.
- Alarm receiver → Alarm ring: launches · Triggered alarms transition into the ring experience.
- Alarm ring → Challenges: requires · Dismissal can branch into wake-up challenges.
- Add alarm → Smart services: configures · Smart dismissal rules are selected in the editor.
- Smart services → Challenges: enforces · Native checks support challenge and dismissal behavior.
- Timer → Native timer: drives · Timer UI delegates exact countdown execution to native code.
- Native timer → Timer ring: notifies · Timer completion opens the timer alert screen.
- Platform shells → main.dart: hosts · Platform entrypoints host the Flutter app.