NoGooleApps/replica/uhr/architecture.md

# Architecture: Uhr (Android, ohne Google)

Basis: `recon.md`, `features.csv`. Same conventions as `wetter/`: one native app, no server, no accounts.
**No network permission at all.** World clock cities come from the system time zone database, sounds from the device and the app.

## Stack

| Schicht | Wahl | warum |
| --- | --- | --- |
| Sprache/UI | Kotlin + Jetpack Compose, Material 3 Expressive | same as Wetter, shared look and know-how |
| Persistenz | Room (alarms, instances, timers, cities) + DataStore (settings, stopwatch, bedtime) | relational where it matters, key-value for singletons |
| Alarme | `AlarmManager.setAlarmClock()` | exempt from Doze, shows the alarm icon in the status bar, the only API that is reliable for wake-up alarms |
| Klingeln | foreground service (type `systemExempted`/`mediaPlayback`) + full-screen-intent notification → ringing activity over the lock screen | the pattern Android expects for alarm clocks |
| Timer/Stoppuhr | state in DB/DataStore, `end_at` / `elapsedRealtime` based; foreground service with live notification only while running | survives process death; no ticking in the background |
| Widgets | Jetpack Glance + RemoteViews `TextClock`/`AnalogClock` | clocks tick without app updates |
| Bildschirmschoner | `DreamService` | system screensaver API |
| Ortsliste Weltuhr | `java.time.ZoneId` + localized names from ICU (`android.icu.util.TimeZone` display names, exemplar cities) | offline, no city API needed |
| Töne | `RingtoneManager` (system alarm sounds) + own files via `ACTION_OPEN_DOCUMENT` (persisted URI permission) + bundled CC0 sounds | no streaming services |
| Build/Verteilung | Gradle KTS, minSdk 29, targetSdk 36; release via `scripts/release.sh uhr` (Obtainium) | same pipeline as Wetter |

## Permissions

| permission | why |
| --- | --- |
| `USE_EXACT_ALARM` (API 33+), `SCHEDULE_EXACT_ALARM` (≤32) | alarm clock apps may use exact alarms without asking |
| `USE_FULL_SCREEN_INTENT` | ringing screen over the lock screen (Android 14+: check `canUseFullScreenIntent`, guide the user to the setting) |
| `POST_NOTIFICATIONS` | upcoming, snoozed, missed, timer, stopwatch |
| `FOREGROUND_SERVICE` (+ type) | ringing, running timers |
| `RECEIVE_BOOT_COMPLETED` | reschedule after reboot |
| `VIBRATE`, `WAKE_LOCK` | ringing |

No `INTERNET`, no location.

## Schema

See `schema.sql`: 4 tables (`alarms`, `alarm_instances`, `timers`, `cities`), singletons in DataStore. Access rules: single user, app-private storage, no RLS needed.
Hard constraints: one bedtime wake alarm (partial unique index); a running timer always has `end_at` (check constraint); one instance row per alarm (primary key).

## Interne API (Repositories / Use Cases)

| Aufruf | macht | Flow |
| --- | --- | --- |
| `AlarmRepo.observe()` | alarms + next instance, sorted by time | F01 |
| `AlarmRepo.upsert(alarm)` | save, then `Scheduler.reschedule(alarm)` | F01, F02 |
| `AlarmRepo.delete(id)` / `undo` | delete, cancel PendingIntent | F02 |
| `Scheduler.reschedule(alarm)` | compute next fire (days, skip_until, DST-safe via `ZonedDateTime`), write instance, `setAlarmClock` | all |
| `Scheduler.rescheduleAll()` | on boot, `TIME_SET`, `TIMEZONE_CHANGED`, app update | — |
| `Ringing.start(alarmId)` | foreground service: sound (gradual volume), vibration, full-screen activity, silence-after timeout | F03 |
| `Ringing.snooze()` / `dismiss()` | instance → snoozed (fire_at + snooze) / next occurrence | F03 |
| `AlarmRepo.dismissNext(id)` | skip the upcoming ring only | F04 |
| `TimerRepo.add/pause/resume/addMinute/reset/delete` | state transitions with `end_at`, schedule `setExactAndAllowWhileIdle` for the end | F05 |
| `Stopwatch.start/stop/lap/reset` | DataStore singleton | F06 |
| `CityRepo.search(q)` / `add` / `reorder` / `delete` | offline zone search | F07 |
| `Bedtime.save(schedule)` | writes bedtime + the wake alarm (`is_bedtime_wake`) + reminder alarm | F08 |
| `Sounds.list()` / `preview(uri)` | ringtones + bundled + picked files | F09 |

### Background

| Auslöser | macht |
| --- | --- |
| `setAlarmClock` fire → `AlarmReceiver` | start ringing service |
| 2 h before an alarm (inexact alarm) | "upcoming alarm" notification with "Dismiss now" |
| silence-after timeout | stop ringing, instance → missed, missed notification |
| `BOOT_COMPLETED`, `TIME_SET`, `TIMEZONE_CHANGED`, `MY_PACKAGE_REPLACED` | `rescheduleAll()` |
| timer end (exact alarm) | timer ringing |
| bedtime reminder (exact) | reminder notification |

## Was beißt

- **Time zones and DST:** alarms are wall-clock; the next fire is computed with `ZonedDateTime` in the current zone, so 7:00 stays 7:00 after a zone change; a time skipped by DST rings at the first valid minute after.
- **Doze / OEM battery killers:** only `setAlarmClock` is reliable; show a one-time hint for battery optimization on aggressive OEMs.
- **Android 14+ full-screen intent:** may be off for sideloaded apps → detect and explain, fall back to a heads-up notification that still rings.
- **Race conditions:** snooze and dismiss from the notification and the activity at the same time → all transitions go through one `Mutex` in the ringing service.
- **Process death:** timers and stopwatch keep only timestamps, never counters.
- **Two alarms at the same time:** ring both labels in one screen; the second does not cancel the first.
- **Sounds:** a picked file can disappear → fall back to the default sound, never ring silently by accident.
- **No network:** nothing to rate-limit, nothing to leak; app is F-Droid friendly.

## Build-Reihenfolge

1. **Vertical slice** (S01, S03, S11): add an alarm, it rings at the time with sound over the lock screen, stop. Tables `alarms`, `alarm_instances`. Proves AlarmManager + full-screen intent.
2. **Must alarms** (S02, S04, S15): expanded card, days, label, vibrate, sound picker, snooze, delete/undo, snoozed notification, settings for snooze/silence-after, reboot/time-change handling.
3. **Timer + stopwatch** (S08, S09, S12): keypad, multiple timers, ring progress, background notifications, laps. Table `timers`.
4. **World clock** (S06, S07): local time, cities offline, reorder/delete, analog/digital. Table `cities`.
5. **Design pass**: expressive cards, bottom bar, big time typography, slide-to-act.
6. **Widgets** (S16): digital, analog, next alarm, style options like Wetter.
7. **Should**: pause alarm, dismiss early, upcoming/missed notifications, gradual volume, volume buttons, bedtime (S10), own sound files, settings (S13).
8. **Could**: sunrise alarm, sleep sounds, screensaver (S14), world clock widget, automatic home clock.