Every question the Architecture pages answer

The 15 architecture pages answer 75 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.

Incremental Sync: Reading Only What Changed Since Last Time

Why can't I just filter health samples by a last-synced timestamp?Because a watermark is a filter over a time column, and both candidate columns fail. If you filter on event time (the sample's start date),…
Is an expired Health Connect changes token thrown as an exception I can catch?No. Google surfaces it as a boolean flag on the response, changesTokenExpired, and the official codelab pattern is for your own code to…
Does an HKQueryAnchor still work after the user reinstalls my app?Apple does not document this either way. What Apple documents is only how to persist an anchor: HKQueryAnchor adopts NSSecureCoding, so you…
Should I add up the samples an anchored query returns to get a daily total?No, and this is the mistake that survives adopting a proper cursor. Three reasons. A replay after an anchor reset would double the total.…
How do I know which day a deleted sample belonged to?Only from an index you built yourself at ingest time, because neither platform tells you. Apple's HKDeletedObject exposes just a uuid and…

Backfilling Years of Wearable Data Without Hitting Rate Limits

How far back can I backfill Health Connect data, and what stops me at 30 days?Google documents that by default any app can read Health Connect data for up to 30 days prior to when any permission was first granted. To…
What happens to a user's backfilled history when they reinstall my app?On Android the readable window resets. Google documents that deleting the app revokes all permissions including the history permission, and…
Should the backfill and the incremental sync share a worker?No, and on Health Connect that is close to a correctness requirement rather than a preference. Changes tokens expire after 30 days if…
What rate should I tune a Health Connect backfill loop to?There is no number to tune to. Google documents that rate limits exist and publishes only the categories: a periodic limit and a daily…
Why do users see wrong personal records and streaks while a backfill is running?Because a partial history is a complete history as far as your PR logic is concerned. If you have imported the last 30 days and you compute…

Background Sync That Does Not Depend on the Phone Waking Up

Does force-quitting an iOS app stop HealthKit background delivery?It is very widely repeated and probably true, but it is not documented. We found no statement on developer.apple.com, in documentation or…
What happens if my observer query does not call its completion handler?Apple documents that HealthKit retries using a backoff algorithm, and that if your app fails to respond three times HealthKit assumes it…
Why does requesting immediate background delivery for step count change nothing on iOS?Apple documents that some sample types have a maximum frequency of hourly and that the system enforces this frequency transparently, naming…
Can Health Connect notify my app when new health data arrives?No. Google documents that your app cannot get notified of new data, and instead tells you to check at two points: each time your app…
Why do my background HealthKit reads fail while the phone is locked?Apple documents that the device encrypts the HealthKit store when the user locks it, so your app may not be able to read from the store…

Webhook ingestion for health data: making at-least-once delivery safe

Should I dedupe on the webhook event ID or on the day the event points at?Both, at different layers. Dedupe the delivery on the provider's event ID so a retried POST does no work twice. Separately, make the effect…
A provider sent eleven webhooks for the same day's steps. Is that a bug on their side?No, that is normal. Health providers re-notify the same day repeatedly as it fills in: the morning walk, the lunchtime sync, the watch…
Does Health Connect send a webhook when a user's steps change?No. Google documents that your app cannot get notified of new data on Health Connect, so there is no push mechanism to subscribe to. You…
How long should I keep webhook delivery IDs before purging the idempotency table?At least as long as the provider's maximum retry horizon, which you should read off their documentation rather than guess. There is a…
If two webhooks for the same user arrive out of order, which one should win?The one with the higher provider version or modified timestamp, never the one that arrived later. Out-of-order arrival is normal because a…

Mapping Users to Wearable Provider Accounts and Devices

Can one person connect two Fitbit accounts at the same time?Only if your schema has somewhere to put the second one. It happens for real reasons: a work wellness account alongside a personal one, or…
What happens when two of my accounts that share one wearable login get merged?That collision is the test your model either passes or fails. With a connection table you repoint the link rows and the samples never move,…
How do I tell an expired access token apart from a grant the user revoked?Do not decide from the resource call. A 401 on a data request means the access token needs refreshing, and that is an internal state your…
How do I keep a shared smart scale from mixing two people's weights?Recognize that the provider account is a container for measurements, not a person, and that your connection row says nothing about whose…
Should unlinking a wearable also delete the data already synced?Those are two different requests and the states should answer them differently. A user pressing Disconnect means stop, not erase. What…

Deduplicating Health Data From Multiple Sources

Does HealthKit automatically remove duplicate steps from iPhone and Apple Watch?Not for the samples you read. HealthKit merges overlapping sources only inside statistics-query results, meaning HKStatisticsQuery and…
Why did an Android user's step total change after they reordered apps in Health Connect settings?Because Health Connect's deduplication lives in the Aggregate API and uses a priority list only the end user can change. Google documents…
How do you resolve two workouts that partially overlap rather than exactly duplicate each other?Cut the timeline at every start and end instant across all candidate samples, which gives you atomic sub-intervals over which the set of…
Should you pick one winning device per day or resolve source conflicts per interval?Per interval. Picking a winning device for the whole day deletes every period the winner did not record, which is a common real case: the…
Why do on-device Android steps suddenly appear under a package name I have never seen?Google documents that starting with the June 2026 update, steps counted natively by Health Connect are attributed to a Synthetic Package…

Normalizing wearable data across providers

Can I convert SDNN into RMSSD so HRV lines up across platforms?No. They are two different statistics computed from the same interbeat intervals, and there is no constant that converts one into the…
What provenance columns does a canonical health record actually need?Beyond the value and unit: the measurement definition (not just the metric family), the source app and its version, the device manufacturer…
Should manually entered health data be stored in the same table as device samples?Same table is fine; same treatment is not. Health Connect models recording method as a required field with separate constants for…
Why is a source package name or bundle identifier not a stable way to identify a wearable source?Google documents that from the June 2026 update, steps tracked natively by Health Connect are attributed to a Synthetic Package Name that…
Does buying an aggregator remove the normalization problem?It removes the tedious half and often that is the right trade, because maintaining unit tables and field maps across many providers is real…

Timezones and Day Boundaries: Whose Midnight Defines the Day?

Should daily totals use the timezone the user is in now, or the one they were in when the data was recorded?The one they were in at the time, in our judgement. That gives the user the day they actually lived through, and it is the only option that…
How long is a day when the clocks change, and what does that do to a step goal or a streak?In a zone that observes daylight saving, one civil day a year is 23 hours long and one is 25. In America/New_York in 2026, 8 March runs…
Does HealthKit tell me what timezone a sample was recorded in?Not reliably. HKSample carries startDate and endDate as Date values, which are absolute instants with no calendar or zone attached. There…
Why does a daily rollup built on a UTC time bucket give the wrong number for users outside UTC?Because a time bucket over a timestamp-with-time-zone column aligns to UTC, which Timescale's own documentation states explicitly. A…
What breaks when a provider returns a bare date string instead of a timestamp?Two things. First, the instant is unrecoverable: a date with no offset cannot be converted back into a point in time, so any code that…

Missing Data and Gaps in Health Metrics

Should a day with no step data be stored as zero?No. Store it as unknown, with a reason code. A zero is only legitimate when you have evidence that some source was present and reporting…
Can I tell whether a user denied HealthKit read access or simply has no data?No, and Apple documents this as deliberate. Apple states that your app cannot determine whether the user granted permission to read data,…
Is it ever acceptable to interpolate missing health data?Only at render time, in code with no write path, and never as an input to anything derived. The reason interpolation is worse for health…
Why does Health Connect show nothing before a certain date?Because of the default history window, not because the user was inactive. Google documents that by default an app can read Health Connect…
Should a missing day break a user's streak?No. A day you have no data for should suspend the streak, not break it, and the copy should say so. Telling someone we do not have data for…

How Should You Store Health Time-Series Data?

How long can plain Postgres handle wearable sample data before I need a time-series database?Longer than most teams assume. PostgreSQL's own documentation gives a rule of thumb that the size of the table should exceed the physical…
Why can a unique index not stop duplicate samples in a time-partitioned table?PostgreSQL documents that to create a unique or primary key constraint on a partitioned table, the constraint's columns must include all of…
Should a user's daily step total be a stored counter or recomputed from raw samples?Recomputed. A counter cannot be proved correct: a webhook retry, a full replay after a client lost its sync cursor, or a platform…
Can I delete raw health samples once the daily rollups are computed?Usually not, and the reason is recompute rather than sentiment. The rollup is only trustworthy because it can be regenerated from raw, so…
Why is a TimescaleDB continuous aggregate wrong after a user edits last month's data?Continuous aggregates are built around an invalidation threshold that the documentation describes as deliberately lagging behind the point…

Resolving Sync Conflicts in an Offline-First Workout Log

Is last-write-wins good enough for sets and reps logged offline?Usually not, and the reason is that it fails silently. Last-write-wins imposes a total order on operations that were not ordered and then…
Why is conflict resolution different for device samples than for data the user types?Because there is no semantic disagreement in a measurement. When a watch reports a heart rate, the device is authoritative and the only…
How should an offline workout record get an ID before the server has seen it?Generate a UUID on the client at the moment the record is created, and treat it as the record's real identity for the rest of its life.…
Do I need CRDTs for a fitness app, or is an append-only event log enough?For one user logging their own sets and meals, an event log is our default and CRDTs are usually more machinery than the problem needs. The…
When should a sync conflict be shown to the user instead of resolved automatically?Only when both branches contain deliberate human input that cannot coexist: two different weights on the same set, an edit racing a delete,…

Versioning Derived Metrics and Recomputing Health History

If we improve our calorie formula, does last year's number change?Both answers are defensible and the choice is a product decision, not an engineering one. Recomputing everything gives you a series that is…
What do we store next to a derived health metric so we can reproduce it later?At minimum: the formula id and version that produced the value, the source-resolution policy used, the civil date and the instant window…
What are the two triggers that make a derived health metric stale?Dirty inputs and a formula change, and they should not share a policy. Dirty inputs are late-arriving, retro-edited or deleted samples that…
Does updating a user's body weight mean recomputing their calorie history?It is the question people forget to ask, and yes for most calorie models. Any metric that consumes a profile field such as body weight, age…
Is every part of a health history recomputable if we kept the raw samples?No, and you should know exactly which ranges are not. Retention policies and erasure requests can remove raw data you would need, which…

Monitoring a Health Data Pipeline for Silent Failures

How do I detect that a provider silently changed units on a field?Distribution monitoring, because type validation catches none of it. A kilojoule-for-kilocalorie swap, metres becoming feet, or seconds…
Should a single 100,000-step day trigger an alert?No, and treating it as one detector is the mistake. A 100,000-step day is usually not a sensor error at all: it is a manual entry with an…
Why can't one freshness threshold cover every wearable provider?Because the providers have structurally different sync cadences. Apple's data reaches your server when the user opens the app or a…
Is it worth reconciling my daily totals against the platform's own aggregate?Yes, but as a drift detector rather than a correctness target, because you will not match and should not try to. Apple's statistics queries…
How do I notice one provider going dark when total ingest volume looks normal?You cannot, from an aggregate chart, and that is the point of splitting every signal by provider. If one provider represents eight percent…

Deleting and Exporting a User's Health Data

If I delete a user's rows but leave their wearable OAuth grant active, what happens?You start collecting them again. Wearable backends push: the provider does not know you deleted anything, it knows there is a live grant…
Can I surgically delete one user out of my database backups?Realistically no, and a design that claims to is either rewriting backups, which destroys their value as a recovery point, or quietly…
A user unlinks one wearable but keeps their account. What has to change beyond deleting that provider's rows?Every merged number derived from that source. A daily total is a resolution across overlapping sources rather than a sum of one, so…
Does a health data export have to include derived metrics like daily rollups and computed scores?In our judgement yes, and this is where most exports fall down. Nobody makes a decision from a heart-rate sample at 07:42:13; they act on…
How do I stop a deleted user reappearing from a queue or a dead-letter queue?Write a positive tombstone rather than relying on the absence of a row, and check it at consume time. A missing user row is exactly what an…

Caching Fitness API Responses Without Serving Stale Health Data

Which parts of a health API response are actually safe to cache for a long time?The parts that are not about a person. Exercise catalogue rows, demo media, unit conversion tables and a provider's capability metadata…
Should invalidation be driven by expiry times or by provider events?By events, with expiry kept only as a backstop. A time-to-live is a guess about how long a value stays true, made before you know anything…
Can a cache be my answer to a provider's rate limit?It stretches the quota, but it is not the strategy, and three other things matter more than the hit rate. Coalesce concurrent misses so…
What goes wrong with a cached daily total when the user crosses midnight?It stops being an answer to the question that was asked. A total cached under a key meaning today does not decay gracefully; at local…
Does a purge of a user's health data have to reach the cache?Yes, and the cache is one of the stores most often left off the list, because it is filed under performance rather than under data. A…

Back to the Architecture hub, or see every question this site answers.