Steps, distance, calories, heart rate, and sleep have to be pulled from the user's platform (Android Health Connect on Android, Apple HealthKit on iOS) by a health and nutrition app — and present it as one clean, deduplicated daily profile. There are very few similarities between the two APIs: separate read mechanics, different authorization schemes, and different data structures. We built the mobile sync layer that makes them look like one.
The Challenge
- Two native APIs that agree on nothing. Apple HealthKit returns daily aggregates through callbacks; Health Connect returns raw, paginated samples with rich source metadata. Same concepts, completely different shapes — and the app had to normalize both into one schema.
- Double-counting is the default. A phone, a smartwatch, and a third-party app can all report the same 8,000 steps. Naively summing them inflates every metric. The app needed to recognize overlapping sources and count each real-world activity once.
- Battery and network can't pay for freshness. Health data changes all day, but reading the full history on every sync would drain the battery and saturate cellular connections. The sync cadence had to stay light while still feeling live.
Permissions can be confusing. Dozens of data types, two permission models, background-read restrictions, and users who grant some scopes but not others — all of which the app has to handle without crashing the flow.
Our Solution
We built a three-layer sync: a thin native layer reads each platform's API, an on-device normalization layer deduplicates and rolls the data into daily summaries, and the backend stores it and reconciles it into a single trusted ledger. The client never ships raw samples — it ships clean, timezone-correct daily rollups.
Architecture
- iOS reads Apple HealthKit through react-native-health; Android reads Health Connect through react-native-health-connect.
- On-device normalization transforms both platforms' output into one schema and deduplicates before anything leaves the phone.
- Sync triggers — 30 days of history on first launch, then lightweight 1-day incremental reads on a 10-minute interval and on every app resume.
- Transport — normalized daily rollups are POSTed to the main server's /user-health/system-activity, which forwards them (with user ID + timezone) to the health microservice.
- Persistence — each source/day is stored idempotently as a HealthSystemAggregate; a MongoDB change stream then reconciles it into a per-day HealthLedger.
Expo / React Native managed workflow with native HealthKit and Health Connect modules.
Key Features
- One normalization contract for two APIs. Platform-specific readers feed a single formatHealthData step that emits the same shape regardless of source — so the backend and UI never branch on iOS vs Android.
2. Max-based deduplication on the device. Within each source, a day's readings are summed; then the daily value is the Math.max() across sources (calories keyed by source|deviceType), so multiple readings from one device accumulate while a watch and a phone reporting the same day don't double up:
// Sum readings within each source, then take the max ACROSS sources dateSourceMap[date][source] += entry.count; const totalSteps = Math.ceil(Math.max(...Object.values(dateSourceMap[date]))); |
3.The right read strategy per platform. Health Connect reads are paginated with a pageToken loop (1,000 records/page); HealthKit's daily aggregates are looped day-by-day. Each quirk is contained in its own reader, invisible to the rest of the app.
4. A sync cadence that respects the battery. A full 30-day backfill runs only once (guarded by a first-call flag); after that, every sync pulls just one day — fast on cellular, cheap on power.
5. Timezone-correct daily grouping. Samples are bucketed into YYYY-MM-DD keys in the user's own timezone, so a workout at 11 PM lands on the right day no matter where the server lives.
6. Idempotent backend writes. Each rollup upserts on (userId, deviceId, source, date) — re-sending the same day is a no-op, making retries and overlapping syncs safe.
7. Honest degradation. Missing permissions, empty reads, and Health Connect rate-limit errors are caught and surfaced cleanly — an empty day never crashes the sync, and the user gets a clear prompt instead of a silent failure.
Results
- A single, consistent health profile across iOS and Android — the platform difference is invisible to the rest of the app.
- Overlapping device/app sources are deduplicated, so steps and calories reflect reality instead of inflated sums.
- Lightweight incremental syncs keep data fresh without draining battery or burning mobile data.
Timezone-correct, idempotent writes mean every metric lands on the right day, and retries never corrupt the record.
Technology Stack
React Native (Expo) · react-native-health (HealthKit) · react-native-health-connect · NestJS · MongoDB · MongoDB Change Streams · moment-timezone
