flowchart LR
  subgraph phone [Android app]
    ui["Compose screens<br/>(View)"] -->|"user actions"| vm["ViewModel"]
    vm -->|"StateFlow"| ui
    vm --> repo["Repository<br/>(Model)"]
    repo --> local["Room cache · SharedPreferences"]
    platform["AlarmManager · trip-tracking service · WorkManager"] --> repo
  end
  repo -->|"HTTPS · JSON · JWT"| api["Django + DRF<br/>Render (Docker)"]
  api --> db[("Neon Postgres")]
  api --> kakao["Kakao<br/>routes · places · reverse geocoding · static maps"]
  api --> seoul["Seoul subway · bus<br/>real-time arrivals"]
  api -.->|"weekly figures only"| llm["OpenAI-compatible LLM<br/>(OpenRouter)<br/>weekly summary"]

classDiagram
  class LoginActivity
  class MainActivity
  class AuthViewModel {
    +state: StateFlow~UiState~
    +login()
    +signup()
    +onPasswordChange(value)
  }
  class HomeViewModel {
    +nav: StateFlow~NavState~
    +state: StateFlow~UiState~
    +plan: StateFlow~AlarmPlanView~
    +refresh()
    +setAlarmEnabled(id, enabled)
    +submitAdd()
    +recomputePlan(eventId)
    +loadRiskOptions(eventId)
    +saveRiskOption(eventId, key)
    +onAddDestinationHome()
    +openRoutePreview(key)
    +loadReport(week)
    +openReportDay(date, eventId)
    +markBlockDone(blockId)
    +logout()
  }
  class AuthRepository {
    +register()
    +login()
    +checkPassword()
    +logout()
  }
  class EventRepository {
    +loadHome()
    +createEvent()
    +setAlarmEnabled()
    +loadPlan()
    +recomputePlan()
    +loadRiskOptions()
    +saveRiskOption(tau)
    +routeCandidates()
    +liveRoute()
    +importCalendar()
  }
  class RoutineRepository {
    +blocks()
    +createBlock()
    +updateBlock()
    +eventBlocks()
    +setEventBlocks()
  }
  class ReportRepository {
    +weekly(week)
    +calibration()
  }
  class ReportMapping {
    <<mapping>>
    +toView(WeeklyReportDto)
  }
  class RiskOptionsMapping {
    <<mapping>>
    +toView(RiskOptionsDto)
  }
  class ApiClient {
    <<object>>
    +auth: AuthApi
    +events: EventsApi
    +profile: ProfileApi
    +routines: RoutinesApi
    +observations: ObservationsApi
    +alarmLogs: AlarmLogsApi
    +reports: ReportsApi
    +health: HealthApi
  }
  class TokenStore {
    +save()
    +updateAccess()
    +clear()
  }
  class OfflineCache {
    +saveEvents()
    +events()
    +event()
    +saveProfile()
    +saveBlocks()
    +wipe()
  }
  class JitDatabase {
    <<Room>>
  }
  class CacheDao {
    <<DAO>>
  }
  LoginActivity --> AuthViewModel
  MainActivity --> HomeViewModel : renders nav and state
  AuthViewModel --> AuthRepository
  HomeViewModel --> EventRepository
  HomeViewModel --> RoutineRepository
  HomeViewModel --> ReportRepository
  AuthRepository --> ApiClient
  AuthRepository --> TokenStore
  EventRepository --> ApiClient
  EventRepository --> OfflineCache
  RoutineRepository --> ApiClient
  RoutineRepository --> OfflineCache
  ReportRepository --> ApiClient
  ReportRepository ..> ReportMapping
  EventRepository ..> RiskOptionsMapping
  ApiClient --> TokenStore : interceptor and authenticator
  OfflineCache --> JitDatabase
  JitDatabase --> CacheDao

classDiagram
  class AlarmScheduler {
    +sync(schedules)
    +snooze(schedule, minutes)
    +restoreAll()
    +cancelAll()
    +registered()
  }
  class ScheduledAlarmStore {
    +all()
    +replaceAll(schedules)
    +find(eventId)
  }
  class AlarmReceiver {
    <<BroadcastReceiver>>
  }
  class BootReceiver {
    <<BroadcastReceiver>>
  }
  class AlarmActivity {
    -dismiss()
    -snooze()
  }
  class TripTrackingService {
    <<foreground Service>>
  }
  class TripGeofence {
    +offer(fix)
    +finalizeArrival()
  }
  class TripLiveState {
    <<object>>
    +snapshot: StateFlow
    +arrival: StateFlow
    +liveRoute: StateFlow
  }
  class TripObservationQueue {
    +enqueue()
    +flush()
  }
  class BlockObservationQueue {
    +enqueue()
    +flush()
  }
  class AlarmLogQueue {
    +record(kind, schedule)
    +flush()
  }
  class LiveRouteStore
  class MorningSessionStore
  class JitWork {
    <<object>>
    +requestObservationUpload()
    +ensurePeriodicSync()
    +cancelAll()
  }
  class ObservationUploadWorker {
    <<Worker>>
  }
  class PlanSyncWorker {
    <<Worker, 6 h>>
  }
  class RouteRefreshWorker {
    <<Worker, 15 min>>
  }
  class EventRepository
  class HomeViewModel
  AlarmScheduler --> ScheduledAlarmStore
  AlarmScheduler ..> AlarmReceiver : PendingIntent
  AlarmReceiver --> AlarmActivity : full-screen intent
  BootReceiver --> AlarmScheduler : restoreAll
  AlarmActivity --> AlarmScheduler : snooze
  AlarmActivity --> TripTrackingService : start on dismiss
  AlarmActivity --> MorningSessionStore : start session
  AlarmScheduler --> AlarmLogQueue : alarm time set or changed
  AlarmReceiver --> AlarmLogQueue : fired
  AlarmActivity --> AlarmLogQueue : dismissed, snoozed, silenced
  ObservationUploadWorker --> AlarmLogQueue
  TripTrackingService --> TripGeofence
  TripTrackingService --> TripLiveState : publish
  TripTrackingService --> TripObservationQueue
  TripTrackingService --> LiveRouteStore
  TripTrackingService --> EventRepository : live route every minute
  JitWork --> ObservationUploadWorker
  JitWork --> PlanSyncWorker
  JitWork --> RouteRefreshWorker
  ObservationUploadWorker --> TripObservationQueue
  ObservationUploadWorker --> BlockObservationQueue
  PlanSyncWorker --> EventRepository
  PlanSyncWorker --> AlarmScheduler
  RouteRefreshWorker --> EventRepository
  RouteRefreshWorker --> AlarmScheduler
  RouteRefreshWorker ..> TripLiveState : skips the tracked event
  HomeViewModel ..> TripLiveState : observes
  HomeViewModel --> AlarmScheduler : sync after a fresh load
  HomeViewModel --> BlockObservationQueue : one tap per block

classDiagram
  class accounts_views {
    <<views>>
    RegisterView
    LoginView
    PasswordCheckView
    MeView
    ProfileView
  }
  class events_views {
    <<views>>
    EventListCreateView
    EventDetailView
    EventRecomputeView
    EventRiskOptionsView
    EventCalendarImportView
    EventTagListView
    PlaceSearchView
    PlaceStaticMapView
    PlaceReverseView
    RouteCandidateView
    RouteLiveView
  }
  class routines_views {
    <<views>>
    RoutineBlockListCreateView
    RoutineBlockDetailView
    EventBlockSelectionView
    BlockObservationBatchView
  }
  class observations_views {
    <<views>>
    ObservationBatchView
    ObservationListView
    AlarmLogBatchView
  }
  class reports_views {
    <<views>>
    WeeklyReportView
    CalibrationView
  }
  class events_alarms {
    <<module>>
    +alarm_states(user)
    +reset_alarm_overrides(event)
  }
  class planning_risk_options {
    <<module>>
    +build_risk_options(event)
  }
  class planning_history {
    <<module>>
    +record_revision()
  }
  class reports_summary {
    <<module>>
    +summary_for(user, report)
    +build_facts()
    +check_text()
    +render_template()
  }
  class reports_llm {
    <<module>>
    +configured()
    +chat()
  }
  class ApiRequestLogMiddleware {
    <<middleware>>
  }
  class planning_services {
    <<module>>
    +compute_and_store(event)
    +recompute_for_user(user)
  }
  class planning_estimators {
    <<module>>
    +estimate_prep()
    +estimate_travel()
    +compute_alarm_math()
  }
  class planning_distributions {
    <<module>>
    Normal
    Empirical
    Mixture
    +convolve()
    +blend()
  }
  class routing_clients {
    <<module>>
    +route_candidates()
    +resolve_route()
    +best_route()
    +search_places()
    +static_map()
    +coord_to_address()
  }
  class routing_realtime {
    <<module>>
    +enrich_candidates()
    +subway_arrivals()
    +bus_arrivals()
  }
  class reports_services {
    <<module>>
    +weekly()
    +calibration()
    +lateness_causes()
  }
  class prediction_learning {
    <<module>>
    +update_route_corrections()
    +build_artifact()
    +save_artifact()
  }
  class train_models {
    <<command>>
  }
  accounts_views --> planning_services : home or prep change recomputes up to 50 events
  events_views --> planning_services : create, patch, recompute, import
  routines_views --> planning_services : PUT event blocks
  events_views --> events_alarms : alarm_on, is_first_alarm
  events_views --> routing_clients : search, static map, reverse, candidates, live route
  planning_services --> routing_clients : resolve_route or best_route
  planning_services --> planning_estimators
  planning_estimators --> planning_distributions
  routing_clients --> routing_realtime : real-time arrivals on candidates
  reports_views --> reports_services
  reports_views --> reports_summary : summary on top of the figures
  reports_summary --> reports_llm : only when configured and under the limits
  events_views --> planning_risk_options : GET risk-options
  events_views --> events_alarms : reset on manual creation
  planning_risk_options --> planning_estimators
  planning_services --> planning_history : every computation
  train_models --> prediction_learning

erDiagram
  User ||--|| Profile : has
  User ||--o{ Event : owns
  Place |o--o{ Event : "destination of"
  EventTag |o--o{ Event : "sets tau of"
  Event ||--o| AlarmPlan : "computed into"
  User ||--o{ RoutineBlock : defines
  RoutineBlock |o--o{ RoutineBlock : "precondition of"
  Event ||--o{ EventBlockSelection : uses
  RoutineBlock ||--o{ EventBlockSelection : "chosen in"
  RoutineBlock ||--o{ BlockObservation : "timed by"
  Event |o--o{ BlockObservation : "morning of"
  Event ||--o{ TripObservation : "depart or arrive"
  User |o--o{ ModelArtifact : "personal (none = global)"
  Event ||--o{ PlanRevision : "history of its plan"
  Event |o--o{ AlarmLog : "rang, snoozed, switched"
  User ||--o{ WeeklySummary : "one per week"
  User ||--o{ LlmCall : "counts toward limits"
  User |o--o{ ApiRequestLog : "made (none = anonymous)"

  User {
    bigint id PK
    string email UK
    string password "hash"
    string nickname
    datetime terms_agreed_at
    bool is_active
    datetime date_joined
  }
  Profile {
    bigint id PK
    bigint user_id FK "one per user"
    float home_lat "pair with home_lng"
    float home_lng
    string home_label
    float default_tau "0.90"
    int onboarding_prep_min
    datetime shadow_started_at
    string timezone
  }
  Place {
    bigint id PK
    string name
    float lat
    float lng
    string address
    string kakao_place_id UK "null for plain addresses"
    datetime created_at
  }
  EventTag {
    bigint id PK
    string key UK
    string label
    float default_tau
    string penalty_shape
    int order
  }
  Event {
    bigint id PK
    bigint user_id FK
    bigint place_id FK
    bigint tag_id FK
    string source
    string external_id "calendar id"
    string title
    datetime start_at
    bool alarm_enabled "null = first-alarm rule"
    float tau_override
    string route_key
    bool destination_is_home "resolved from the profile"
    float origin_lat "null = home"
    float origin_lng
    string origin_label
    datetime created_at
    datetime updated_at
  }
  AlarmPlan {
    bigint id PK
    bigint user_id FK
    bigint event_id FK "one per event"
    string status "ok no_home no_place route_failed"
    datetime alarm_at
    datetime depart_by
    datetime arrive_at
    int prep_minutes
    int travel_minutes
    int buffer_minutes
    float tau_used
    int on_time_probability "null = learning"
    string confidence_basis
    string prep_source
    json prep_breakdown
    float total_quantile_minutes
    string travel_mode
    string travel_source
    int travel_sample_count "trips behind the correction"
    string route_summary
    string route_key
    string route_detail
    json route_path
    int route_distance_m
    string alt_route_key
    string alt_route_label
    int alt_faster_minutes
    json alt_route_path
    datetime computed_at
  }
  RoutineBlock {
    bigint id PK
    bigint user_id FK
    bigint precondition_id FK
    string name
    int default_min_minutes
    int default_max_minutes
    string drop_cost
    bool parallelizable
    bool included_by_default
    int order
    datetime created_at
    datetime updated_at
  }
  EventBlockSelection {
    bigint id PK
    bigint event_id FK
    bigint block_id FK
    bool checked
    datetime updated_at
  }
  BlockObservation {
    bigint id PK
    bigint user_id FK
    bigint block_id FK
    bigint event_id FK
    date observed_on
    float duration_minutes
    float slack_minutes "slack at block start"
    bool was_parallel
    string client_uuid
    datetime client_recorded_at
    datetime server_received_at
  }
  TripObservation {
    bigint id PK
    bigint user_id FK
    bigint event_id FK
    string kind "depart or arrive"
    string detector
    datetime observed_at
    float lat
    float lng
    float accuracy_m
    float distance_m
    int dwell_seconds "0 since 2.0"
    datetime entered_at "radius entered"
    string client_uuid
    datetime created_at
  }
  PlanRevision {
    bigint id PK
    bigint user_id FK
    bigint event_id FK
    datetime computed_at
    string trigger "create update recompute import profile blocks"
    string status
    datetime alarm_at
    datetime depart_by
    datetime arrive_at
    int prep_minutes
    int travel_minutes
    int buffer_minutes
    float tau_used
    int on_time_probability
    string travel_source
    int travel_sample_count
    string route_key
    string requested_route_key
    int route_minutes_raw "Kakao minutes before correction"
    datetime event_start_at
  }
  AlarmLog {
    bigint id PK
    bigint user_id FK
    bigint event_id FK "null once deleted"
    string kind "scheduled fired snoozed dismissed silenced enabled disabled auto"
    datetime occurred_at
    datetime alarm_at
    int snooze_minutes
    string source "app or server"
    string client_uuid
    datetime created_at
  }
  WeeklySummary {
    bigint id PK
    bigint user_id FK
    date week_start
    string facts_hash
    json facts "figures sent"
    text text
    string model
    datetime updated_at
  }
  LlmCall {
    bigint id PK
    bigint user_id FK
    date day
    date week_start
    string outcome "pending ok invalid or a failure"
    string model
    string facts_hash
    int duration_ms
    datetime created_at
  }
  ApiRequestLog {
    bigint id PK
    bigint user_id FK
    datetime created_at
    string method
    string route "URL pattern"
    bigint object_id
    int status_code
    int duration_ms
    string app_version
    json query "secrets and coordinates removed"
    json request_body
    json response_body
    string error_code
  }
  RouteCorrection {
    bigint id PK
    string route_signature "empty = global"
    string mode
    int hour_bucket "-1 = all hours"
    string weekday_type
    float factor
    float sd_minutes
    int sample_count
    datetime updated_at
  }
  ModelArtifact {
    bigint id PK
    bigint user_id FK "null = global"
    string version
    json payload
    int sample_count
    bool is_active
    datetime created_at
  }

classDiagram
  class Distribution {
    <<abstract>>
    +mean
    +quantile(tau)
    +cdf(minutes)
    +sample(rng)
  }
  class Normal
  class Empirical
  class Mixture
  class PrepEstimate {
    +distribution: Distribution
    +block_count
  }
  class TravelEstimate {
    +distribution: Distribution
    +raw_minutes
    +factor
  }
  class AlarmMath {
    +prep_minutes
    +travel_minutes
    +buffer_minutes
    +total_minutes
  }
  Distribution <|-- Normal
  Distribution <|-- Empirical
  Distribution <|-- Mixture
  PrepEstimate --> Distribution
  TravelEstimate --> Distribution
  PrepEstimate ..> AlarmMath : compute_alarm_math
  TravelEstimate ..> AlarmMath : compute_alarm_math