Extended Health Data Sync

Sync additional HealthKit data types beyond workouts — sleep analysis, nutrition, body measurements, vitals (resting HR, HRV, VO2max). Requires schema extensions on the backend.

Updated for SYNTHESIS schema

Sleep → `sleep_sessions` + `sleep_streams`

Discrete sleep events with summary scores: sleep_score, efficiency, stage durations (deep/REM/light/awake), onset latency, wakeup count
HRV, resting HR, respiratory rate, SpO2 measured during sleep
High-resolution streams (HR, sleep_stage, SpO2) stored as Parquet on S3
is_main_sleep boolean distinguishes primary sleep from naps

All-day health data → staging → Parquet compaction

Incremental samples (all-day HR, steps, stress, skin temp) land in health_samples_staging (Postgres buffer)
Daily compaction job compresses staging rows to Parquet files in health_streams
Staging table holds at most ~1 day of data, then truncated

Daily summaries → `athlete_metrics`

Derived or provider-reported daily values: HRV, resting HR, weight, body fat, steps, stress, readiness, VO2max, respiratory rate, SpO2, skin temperature
One row per athlete per metric per date per source
Supports subjective wellness: soreness, fatigue, mood, motivation (1-5 scales)
locked boolean prevents auto-sync from overwriting manual edits

Query patterns

Today's data (real-time display): read from health_samples_staging (Postgres, fast)
Historical data (charts, trends): read from health_streams Parquet files (S3, cheap)
Daily summary (calendar, coaching): read from athlete_metrics (Postgres, pre-computed)

Data flow examples

Apple Health sleep → sleep_session + sleep_streams (Parquet) → athlete_metrics (sleep_score, hrv)
Apple Health all-day HR → health_samples_staging → daily compaction → health_streams (Parquet) → derive resting_hr → athlete_metrics
Manual weight entry → direct insert into athlete_metrics with source = 'manual'

Depends on

#31 Implement SYNTHESIS Schema
#32 Object Storage Setup (S3/R2/MinIO)
#34 Health & Sleep Data Schema

Reference

See docs/api-research/SYNTHESIS.md §7 (Athlete Health Data: Three First-Class Entities).