HealthTracking/docs/superpowers/plans/2026-06-05-fightrate-p1-essential-features.md

Implementation Plan: FightRate P1 Essential Features

Overview

Implement the next FightRate feature batch as incremental, testable slices: workout sessions, round timer, configurable alerts, more robust BLE state, and sensor metadata (battery/body location). Keep PT-BR visible copy and English code identifiers.

Architecture Decisions

• Keep local-first SQLite as source of truth.
• Add session data without replacing existing sample storage.
• Prefer pure domain logic for round timer and alerts so behavior is unit-testable.
• Keep BLE foreground service as owner of the device connection.
• Expose sensor metadata through existing service broadcasts to avoid direct BLE ownership in the ViewModel.

Task List

Phase 1: Domain foundation

• Add WorkoutSession, WorkoutSessionStatus, RoundTimerConfig, RoundTimerSnapshot, and calculators.
• Add unit tests for timer transitions and session summary calculations.

Phase 2: Persistence

• Add workout_sessions table and nullable session_id on heart_rate_samples.
• Add safe migration from current database version.
• Add store methods to start/pause/resume/finish active sessions and insert samples with active session id.

Phase 3: UI/ViewModel integration

• Add session and round timer state to LiveHeartRateUiState.
• Add ViewModel actions: start/pause/resume/finish session and update timer config.
• Add visible Compose controls in Live screen.

Phase 4: Alerts

• Add persisted alert settings with safe defaults.
• Add configurable vibration/sound toggles and zone/limit thresholds.
• Trigger alerts from service/ViewModel without spamming.

Phase 5: BLE hardening and metadata

• Add BLE status events for scan/connect/service/descriptor failures and unexpected disconnects.
• Add conservative reconnect/backoff in foreground service.
• Read battery level and body sensor location when available.
• Show metadata in Sensor screen.

Review/Verification

• Run unit tests after domain/persistence slices.
• Run ./gradlew :app:testDebugUnitTest :app:assembleDebug before final response.
• Run code review and front/UI review via fresh-context reviewers.
• Reconcile findings and fix required issues.

Risks

Risk	Impact	Mitigation
Database migration loses samples	High	Add additive migration, no DROP for current versions
BLE changes break screen-off tracking	High	Keep service ownership; add metadata/status only
UI becomes cluttered	Medium	Compact cards and PT-BR labels
Alert spam	Medium	Throttle alerts and use safe defaults