Architecture
Health Data Architecture for Fitness Apps
Connecting a wearable API is the easy part. The hard part starts once data is flowing: the same walk arrives three times from three sources, one provider reports sleep in local time and steps in UTC, yesterday’s total changes after a watch syncs late, and “today” means something different for a user who flew overnight. This hub covers the layer that makes multi-source health data trustworthy — ingestion, reconciliation, storage, and the monitoring that tells you it broke before your users do.
Two things worth saying before you read further. First, a large share of readers should buy rather than build — most of what follows is precisely what health data aggregators sell, and rebuilding it is months of work that users never see when it goes right. These pages say so where it applies, and say what would make us build instead. Second, this cluster is about design. When something is already broken and you need it fixed today, start at troubleshooting instead; each page here links down to the relevant symptom rather than restating it.
Getting data in
Ingestion and sync — the read model on both sides of the wire.
- Incremental Sync: Reading Only What Changed Since Last TimeSync only new health data with HealthKit anchors and Health Connect change tokens, not an updated_since watermark. Mark days dirty, then recompute them.
- Backfilling Years of Wearable Data Without Hitting Rate LimitsTreat a multi-year first sync as a budgeted, resumable job: recent-first chunks, a checkpoint per window, and rate limits Google never published.
- Background Sync That Does Not Depend on the Phone Waking UpHealthKit background delivery is capped and best-effort, and Health Connect has no push at all. Design so a missed wake costs latency, not correctness.
- Webhook ingestion for health data: making at-least-once delivery safeDesign a health webhook pipeline where a retried delivery can't double a user's calorie total: two dedupe layers, fast ack, versioned upserts.
- Mapping Users to Wearable Provider Accounts and DevicesModel users, provider accounts and data sources as three tables, not one. Connection states, silent revocation, account merges, and why unlink must revoke.
Making it trustworthy
Reconciliation and data quality — where most of the real work is.
- Deduplicating Health Data From Multiple SourcesHealthKit merges only inside statistics queries; Health Connect only for Activity and Sleep. The source-priority and interval-overlap algorithm.
- Normalizing wearable data across providersUnits and field names are the easy layers. Apple stores HRV as SDNN, Health Connect stores RMSSD — so a canonical schema has to carry provenance.
- Timezones and Day Boundaries: Whose Midnight Defines the Day?Store the instant, the UTC offset and the civil date. What DST, travel and provider timestamp mismatches do to daily totals, goals and streaks.
- Missing Data and Gaps in Health MetricsA missing day and a zero day are different facts. How to store absence explicitly, why interpolating health data is wrong, and how to chart gaps.
Storing and serving
Schema decisions that are expensive to reverse later.
- How Should You Store Health Time-Series Data?Health samples are late-arriving and retro-edited. Raw tables vs rollups vs a time-series extension, the natural key, and a schema sketch.
- Resolving Sync Conflicts in an Offline-First Workout LogDevice samples need dedupe, not conflict resolution. User-entered sets and meals need merging: an event-log design and a worked two-device conflict.
- Versioning Derived Metrics and Recomputing Health HistoryA derived metric is a function of raw data plus a formula version. Store the version, recompute on purpose, and never rewrite a user's history silently.
Running it in production
Knowing it broke before your users tell you.
- Monitoring a Health Data Pipeline for Silent FailuresHealth pipelines fail silently. Per-provider freshness SLOs, volume anomalies, implausible values and reconciliation checks that catch it early.
- Deleting and Exporting a User's Health DataRaw samples, rollups, caches, queues, DLQs, logs, embeddings, backups and the OAuth grant: how to erase and export a user's health data properly.
Frequently asked questions
- Why does the same workout show up two or three times?
- Because several apps and devices write to the same health store and nothing reconciles them for you. On iOS, HealthKit performs no automatic deduplication of the raw samples you read — merging happens only inside statistics query results, only for quantity types, so overlapping workouts get no help at all. On Android, Health Connect deduplicates only Activity and Sleep, only through its aggregate API, and the source priority order is controlled by the user in Health Connect settings rather than by your app. Resolution is a layer you own, and it has to be designed rather than discovered.
- Should I build this pipeline or buy an aggregator?
- For most teams, buy. Deduplication, unit normalization, token refresh, per-provider quirks and backfill are exactly what health data aggregators sell, and rebuilding them in-house is months of work that is invisible to users when it goes right and embarrassing when it goes wrong. Build it yourself when you need data an aggregator does not expose, when per-user aggregator pricing does not survive your unit economics at scale, when data residency or a compliance posture forbids a third party holding the data, or when the integration surface is small enough that the abstraction costs more than it saves.
- What is the single most common architectural mistake here?
- Treating health samples as an append-only log. They are not. A watch syncs hours late, a user edits yesterday's workout, a provider revises last night's sleep after further processing, and a device backfills a week after a trip. Any design that computes a daily total once and considers it final will silently serve wrong history. The durable shape is to treat incoming changes as a signal about which days are now dirty, then recompute those days from the current state of the store, rather than incrementally adding what just arrived to a running total.
Independent comparison, last reviewed July 27, 2026. Pricing, rate limits, and feature availability change often — confirm current details in each provider’s official documentation before you commit. Product and company names are trademarks of their respective owners; AIFitnessAPI is not affiliated with, endorsed by, or sponsored by any product listed here.