# Design: alarm-clock-module

## Architecture
- Flutter owns alarm domain data, UX, recurrence calculation, and persistence.
- Android owns exact wakeup delivery through AlarmManager/setAlarmClock and notification actions.
- Communication uses a MethodChannel, tentatively `pluriwave/alarm_scheduler`.
- Existing `ServicioTimer` remains unchanged; a new `ServicioAlarmas` manages alarms.

## Data model
- `AlarmaMusical`: id, name, enabled, hour, minute, scheduleType, weekdays, stationUuid/url snapshot, fallbackStation snapshot, bundledSoundId, volume, snoozeMinutes, soundOnVacation, nextOccurrenceAt.
- `RangoVacaciones`: id, name, startDate, endDate, enabled.
- `ExcepcionAlarma`: alarmId, occurrenceAt, type (`skipNext`, `snooze`, `vacation`).
- `EjecucionAlarma`: scheduledAt, firedAt, status, fallbackUsed, failureReason.

## Persistence
Use JSON files or SharedPreferences for MVP to avoid risky DB migrations. If alarm history grows, migrate to sqflite later.

## Android native components
- `PluriWaveAlarmReceiver`: receives exact alarm and pre-alarm actions.
- `PluriWaveAlarmScheduler`: schedules/cancels next alarm and pre-notification.
- `PluriWaveAlarmActivity` or full-screen notification target for the ringing UI.
- Notification channels:
  - `alarm_pre_notice`: silent, low/default importance, no sound.
  - `alarm_ringing`: high importance for active alarms.

## Audio strategy
MVP: when the alarm fires, bring the Flutter app/alarm screen forward and use existing audio_service to play station/fallback. If Flutter/audio startup fails, Android should be able to play a bundled raw sound as last fallback.

## Reliability diagnostics
Expose statuses for:
- exact alarm permission (`canScheduleExactAlarms`).
- notification permission.
- battery optimization warning.
- DND policy access for optional override.

## Key decision
Use `setAlarmClock` for actual alarm occurrences because Android treats these as critical and visible user alarms. Use a separate exact/inexact notification alarm for the 30-minute silent pre-notice depending on permission and platform behavior.