# nihaldr/ultimate_alarm_clock architecture

> Architecture diagram of the GitHub repository nihaldr/ultimate_alarm_clock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nihaldr/ultimate_alarm_clock
- Repository: https://github.com/nihaldr/ultimate_alarm_clock

## Overview

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: [`lib/app/routes/app_pages.dart`](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/routes/app_pages.dart) (Page config), [`lib/app/modules/addOrUpdateAlarm/views/add_or_update_alarm_view.dart`](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/addOrUpdateAlarm/views/add_or_update_alarm_view.dart) (Add alarm), [`lib/app/modules/alarmRing/views/alarm_ring_view.dart`](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/alarmRing/views/alarm_ring_view.dart) (Alarm ring), [`lib/app/data/models/alarm_model.dart`](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/models/alarm_model.dart) (Domain models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_main(("main.dart<br/>app entry<br/>[main.dart]"))
  node_routes["App routes<br/>navigation<br/>[app_routes.dart]"]
  node_pages["Page config<br/>navigation map<br/>[app_pages.dart]"]
  node_home["Home<br/>dashboard module<br/>[home_view.dart]"]
  node_add_alarm["Add alarm<br/>alarm editor"]
  node_alarm_ring["Alarm ring<br/>ring UI"]
  node_alarm_challenge["Challenges<br/>dismiss flows"]
  node_timer["Timer<br/>[timer_view.dart]"]
  node_timer_ring["Timer ring<br/>timer alert"]
  node_world_clock["World clock<br/>clock module"]
  node_settings["Settings<br/>control panel<br/>[settings_view.dart]"]
  node_models[("Domain models<br/>entities<br/>[alarm_model.dart]")]
  node_storage[("Local storage<br/>persistence<br/>[isar_provider.dart]")]
  node_push["Push layer<br/>messaging"]
end

subgraph group_android["Android engine"]
  node_alarm_rx{{"Alarm receiver<br/>android broadcast<br/>[AlarmReceiver.kt]"}}
  node_boot_rx{{"Boot receiver<br/>android broadcast<br/>[BootReceiver.kt]"}}
  node_alarm_utils["Alarm utils<br/>scheduler<br/>[AlarmUtils.kt]"]
  node_smart_services{{"Smart services<br/>background checks"}}
  node_timer_native{{"Native timer<br/>timer engine<br/>[TimerService.kt]"}}
  node_android_db[("Android DB<br/>shared persistence<br/>[DatabaseHelper.kt]")]
end

subgraph group_backend["Firebase backend"]
  node_firebase[("Firestore sync<br/>cloud sync<br/>[firestore.rules]")]
  node_functions["Cloud functions<br/>server helpers<br/>[index.js]"]
end

subgraph group_platforms["Platform shells"]
  node_shells["Platform shells<br/>hosts<br/>[AppDelegate.swift]"]
end

node_main -->|"boots into"| node_routes
node_routes -->|"maps"| node_pages
node_pages -->|"opens"| node_home
node_pages -->|"opens"| node_add_alarm
node_pages -->|"opens"| node_alarm_ring
node_pages -->|"opens"| node_alarm_challenge
node_pages -->|"opens"| node_timer
node_pages -->|"opens"| node_timer_ring
node_pages -->|"opens"| node_world_clock
node_pages -->|"opens"| node_settings
node_home -->|"renders"| node_models
node_add_alarm -->|"edits"| node_models
node_settings -->|"configures"| node_storage
node_models -->|"persists in"| node_storage
node_storage -->|"shares state"| node_android_db
node_add_alarm -->|"syncs shared alarms"| node_firebase
node_firebase -->|"triggers"| node_functions
node_push -->|"consumes updates"| node_firebase
node_add_alarm -->|"schedules"| node_alarm_utils
node_alarm_utils -->|"fires through"| node_alarm_rx
node_boot_rx -->|"restores"| node_alarm_utils
node_alarm_rx -->|"launches"| node_alarm_ring
node_alarm_ring -->|"requires"| node_alarm_challenge
node_add_alarm -->|"configures"| node_smart_services
node_smart_services -->|"enforces"| node_alarm_challenge
node_timer -->|"drives"| node_timer_native
node_timer_native -->|"notifies"| node_timer_ring
node_shells -->|"hosts"| node_main

click node_main "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/main.dart"
click node_routes "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/routes/app_routes.dart"
click node_pages "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/routes/app_pages.dart"
click node_home "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/home/views/home_view.dart"
click node_add_alarm "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/addOrUpdateAlarm/views/add_or_update_alarm_view.dart"
click node_alarm_ring "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/alarmRing/views/alarm_ring_view.dart"
click node_alarm_challenge "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/alarmChallenge/views/alarm_challenge_view.dart"
click node_timer "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/timer/views/timer_view.dart"
click node_timer_ring "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/timerRing/views/timer_ring_view.dart"
click node_world_clock "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/worldClock/views/world_clock_view.dart"
click node_settings "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/settings/views/settings_view.dart"
click node_models "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/models/alarm_model.dart"
click node_storage "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/providers/isar_provider.dart"
click node_push "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/providers/push_notifications.dart"
click node_firebase "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/firestore.rules"
click node_functions "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/functions/index.js"
click node_alarm_rx "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmReceiver.kt"
click node_boot_rx "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/BootReceiver.kt"
click node_alarm_utils "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmUtils.kt"
click node_smart_services "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/SmartControlCombinationService.kt"
click node_timer_native "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/TimerService.kt"
click node_android_db "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/DatabaseHelper.kt"
click node_shells "https://github.com/nihaldr/ultimate_alarm_clock/blob/main/ios/Runner/AppDelegate.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_routes,node_pages,node_home,node_add_alarm,node_alarm_ring,node_alarm_challenge,node_timer,node_timer_ring,node_world_clock,node_settings,node_models,node_storage,node_push toneBlue
class node_alarm_rx,node_boot_rx,node_alarm_utils,node_smart_services,node_timer_native,node_android_db toneAmber
class node_firebase,node_functions toneMint
class node_shells toneRose
```

## Components

### Flutter app

Presentation, state, models, and app orchestration in Dart.

- [main.dart](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/main.dart): app entry · Initializes the Flutter app and hands off to splash/navigation. · `lib/main.dart`
- [App routes](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/routes/app_routes.dart): navigation · Central route and page mapping for the app shell. · `lib/app/routes/app_routes.dart`
- [Page config](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/routes/app_pages.dart): navigation map · Route-to-module wiring used by GetX navigation. · `lib/app/routes/app_pages.dart`
- [Home](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/home/views/home_view.dart): dashboard module · Main alarm list and entry point into key app flows. · `lib/app/modules/home/views/home_view.dart`
- [Add alarm](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/addOrUpdateAlarm/views/add_or_update_alarm_view.dart): alarm editor · Creates and edits alarms, including smart controls and sharing. · `lib/app/modules/addOrUpdateAlarm/views/add_or_update_alarm_view.dart`
- [Alarm ring](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/alarmRing/views/alarm_ring_view.dart): ring UI · Full-screen alarm presentation and wake-up effects. · `lib/app/modules/alarmRing/views/alarm_ring_view.dart`
- [Challenges](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/alarmChallenge/views/alarm_challenge_view.dart): dismiss flows · Math, shake, QR, and pedometer dismissal challenge screens. · `lib/app/modules/alarmChallenge/views/alarm_challenge_view.dart`
- [Timer](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/timer/views/timer_view.dart): timer module · Timer UI and countdown orchestration separate from alarms. · `lib/app/modules/timer/views/timer_view.dart`
- [Timer ring](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/timerRing/views/timer_ring_view.dart): timer alert · Timer completion experience and alert UI. · `lib/app/modules/timerRing/views/timer_ring_view.dart`
- [World clock](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/worldClock/views/world_clock_view.dart): clock module · World clock browsing and timezone display. · `lib/app/modules/worldClock/views/world_clock_view.dart`
- [Settings](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/modules/settings/views/settings_view.dart): control panel · Theme, language, haptics, format, API, and sign-in settings. · `lib/app/modules/settings/views/settings_view.dart`
- [Domain models](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/models/alarm_model.dart): entities · Alarm, timer, profile, user, ringtone, clock, and debug data models. · `lib/app/data/models/alarm_model.dart`
- [Local storage](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/providers/isar_provider.dart): persistence · Isar, SQLite, secure storage, and key-value preferences behind the Dart app. · `lib/app/data/providers/isar_provider.dart`
- [Push layer](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/lib/app/data/providers/push_notifications.dart): messaging · 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](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmReceiver.kt): android broadcast · 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](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/BootReceiver.kt): android broadcast · Restores scheduled alarms after device reboot. · `android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/BootReceiver.kt`
- [Alarm utils](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmUtils.kt): scheduler · Native alarm scheduling and helper logic. · `android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/AlarmUtils.kt`
- [Smart services](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/SmartControlCombinationService.kt): background checks · 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](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/TimerService.kt): timer engine · 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](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/android/app/src/main/kotlin/com/ccextractor/ultimate_alarm_clock/ultimate_alarm_clock/DatabaseHelper.kt): shared persistence · 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](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/firestore.rules): cloud sync · Shared alarms, profiles, and collaboration state in Firestore. · `firestore.rules`
- [Cloud functions](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/functions/index.js): server helpers · 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](https://github.com/nihaldr/ultimate_alarm_clock/blob/main/ios/Runner/AppDelegate.swift): hosts · Flutter host projects for mobile, desktop, and web packaging. · `ios/Runner/AppDelegate.swift`

## Connections

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