# Proposal: alarm-clock-module

## Intent
Build an Android-first musical alarm system for PluriWave that can wake the user with radio/music while keeping reliable fallbacks and clear Android permission diagnostics.

## Scope
- Add a new alarm domain separate from the existing sleep timer.
- Support one-shot and recurrent alarms by weekday.
- Support snooze options: 3, 5, and 10 minutes.
- Support a silent pre-alarm notification 30 minutes before the next occurrence, with an action to skip only that next execution.
- Support vacation ranges and per-alarm `soundOnVacation` behavior. Default: true.
- Support audio fallback chain: selected station, optional fallback station, bundled internal alarm sounds.
- Add Android native scheduling using AlarmManager/setAlarmClock via MethodChannel.
- Add Flutter UI for listing, editing, enabling/disabling, vacation ranges, and reliability diagnostics.

## Out of Scope for MVP
- Cloud sync.
- iOS reliable alarm parity.
- Complex alarm-dismiss challenges.
- Multiple fallback station chains beyond one optional fallback station.
- Full background radio streaming implementation independent from existing audio_service if not needed for MVP.

## Rollback Plan
- Alarm functionality is isolated behind new services/models/screens and Android receivers.
- Existing radio playback, timer, favorites, EQ, and recording flows should remain untouched except for navigation entry points.
- If native scheduling causes issues, remove Android manifest receiver/service entries and hide the alarms entry point.

## Risks
- Android exact alarms require special permissions on Android 12+ and can be denied by default on Android 14+.
- OEM battery managers may still interfere; app must expose diagnostics and guidance.
- DND bypass requires Notification Policy Access and cannot be silently forced.
- Playing a radio stream at alarm time depends on network; bundled sounds must always be present.