Apple Health and Health Connect

The trainee app reads daily step counts from Apple Health on iOS and from Health Connect on Android, and sends one total per day to the backend. Steps are the only metric read today. All of the app code is in mobile/src/features/health.

File	Role
`lib/provider.ts`	`getHealthProvider()` returns the HealthKit provider on iOS, the Health Connect provider on Android, and `null` elsewhere.
`lib/types.ts`	The `HealthProvider` interface both platforms implement.
`lib/healthKit.ts`	iOS provider, on `@kingstinct/react-native-healthkit`.
`lib/healthConnect.ts`	Android provider, on `react-native-health-connect`.
`lib/sources.ts`	`highestSourcePerDay`, the dedup rule.
`lib/sync.ts`	`syncHealthData()`, the one sync routine.
`lib/connect.ts`	`connectHealth()` and `promptForHealthAccessOnce()`.
`lib/backgroundTask.ts`	The background task.
`lib/constants.ts`	Look-back window, cursor version, runtime gates.
`data/healthApi.ts`	The two API calls.
`hooks/useHealthSync.ts`, `hooks/useForegroundHealthSync.ts`, `hooks/useHealthSummary.ts`	React hooks.
`presentation/HealthConnectCard.tsx`	The connect card in the profile.

Permissions and build configuration

From mobile/app.json:

Platform	Setting
iOS entitlements	`com.apple.developer.healthkit` and `com.apple.developer.healthkit.background-delivery`
iOS usage string	`NSHealthShareUsageDescription`. The app only reads, so there is no write usage string.
Android permissions	`android.permission.health.READ_STEPS` and `android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND`
Config plugins	`@kingstinct/react-native-healthkit`, `react-native-health-connect`, and two local plugins

The two local plugins in mobile/plugins:

withHealthConnectPermissionDelegate edits MainActivity to import and register HealthConnectPermissionDelegate after super.onCreate. The Health Connect permission dialog needs it.
withHealthConnectPermissionsRationale adds the permissions rationale entry Health Connect requires.

Both libraries are native modules. A change to any of this needs a new native build. It cannot ship as an over-the-air update.

Loading native modules safely

Each provider loads its library with a dynamic import inside a try:

async function loadHealthKit(): Promise<HealthKitModule | null> {
  try {
    return (await import('@kingstinct/react-native-healthkit')) as unknown as HealthKitModule;
  } catch {
    return null;
  }
}

When the module is missing, as in Expo Go, every provider method returns a safe default (false, or an empty result). The same pattern guards expo-task-manager and expo-background-task in backgroundTask.ts. Follow it for any native-only import in this feature.

The aggregation rule

Never sum raw step samples. A phone and a watch both record the same walk, and each writes its own samples. Adding them double counts.

Both providers ask the platform for per-day statistics and never read individual samples.

iOS

collect queries a statistics collection for HKQuantityTypeIdentifierStepCount, with a cumulative sum, a daily interval and a start date 30 days back.

When the library offers queryStatisticsCollectionForQuantitySeparateBySource, the app gets one bucket per day per source and keeps the highest source for each day with highestSourcePerDay.
Otherwise it falls back to queryStatisticsCollectionForQuantity, where HealthKit has already merged the sources.

Android

collect calls aggregateGroupByPeriod on the Steps record with a one-day slicer and reads COUNT_TOTAL.

If the combined result names fewer than two data origins, the combined totals are used as they are.
With two or more origins it re-runs the aggregate once per origin, using dataOriginFilter, and keeps the highest origin per day.

`highestSourcePerDay`

export function highestSourcePerDay(entries: readonly HealthSourceDayTotal[]): HealthDayTotal[] {
  const best = new Map<string, number>();
  for (const entry of entries) {
    if (entry.steps <= 0) {
      continue;
    }
    const current = best.get(entry.date);
    if (current === undefined || entry.steps > current) {
      best.set(entry.date, entry.steps);
    }
  }
  return [...best].map(([date, steps]) => ({ date, steps }));
}

The day’s total is the largest single source, not the sum across sources. Days with zero steps are dropped. Dates are the device’s local calendar day (localIsoDate), in YYYY-MM-DD form.

Sync

syncHealthData() in lib/sync.ts is the only routine that sends data. It returns a HealthSyncResult with a reason:

`reason`	Meaning
`ok`	Done. `days` is how many days were collected, `updated` how many the server accepted.
`unavailable`	No provider on this platform, or the health store is not available on the device.
`not-connected`	The trainee has not connected health in the app.
`permission`	Step access is not granted.
`auth`	No session token.
`network`	The API call failed with no HTTP status.
`error`	Anything else. `detail` carries the message.

Steps:

Check the provider is available, the app-side “connected” flag is set, and permission is granted.
Make sure there is an auth token. A background run has no in-memory token, so it is loaded from secure storage.
Load the stored cursor. A cursor whose version is not HEALTH_CURSOR_VERSION (currently 3) is discarded.
provider.collect(cursor) returns day totals for the last 30 days (HEALTH_SYNC_LOOKBACK_DAYS).
Post them with ingestHealthDays.
Store the new cursor, which records lastSyncAt.

The sync always re-sends the whole 30 day window. That is safe because the server upserts per day. Bumping HEALTH_CURSOR_VERSION is how a release forces every install to forget its stored cursor.

Triggers

Trigger	Where
App start while signed in, and every return to the foreground	`useForegroundHealthSync`, mounted in the app layout
Right after connecting	`connectHealth`
Background, at most every 15 minutes	The task `perform-health-sync`, registered with `expo-background-task` and `minimumInterval` 15
iOS background delivery	`enableBackgroundDelivery` for step count with immediate frequency
A manual “sync now”	`useHealthSync().syncNow`

The background task is registered only when provider.enableBackground() succeeds. On Android that means the trainee granted BackgroundAccessPermission. The app asks for it once (hasPromptedForBackground) and does not ask again after a refusal.

Connecting

Two paths lead to the same state, by design:

The Connect button on the profile card calls connectHealth().
The first launch after sign-in calls promptForHealthAccessOnce().

Both end in grantAccess (request permission, then set the connected flag) and startSyncing (enable background, register the task, run a sync). App-side state is in secure storage (healthStorage): connected, prompted, prompted for background, install offered, and the cursor.

The first-launch prompt

Whether to ask comes from the provider.

	iOS	Android
`canPromptAutomatically()`	Always true	True only when the installed app version is new enough. See below.
`shouldPromptForAccess()`	Asks HealthKit whether its permission sheet would still appear (`getRequestStatusForAuthorization` returns `shouldRequest`)	True when the app has not prompted before on this install and step access is not granted
Repeat prompts	HealthKit decides. Once the sheet has been shown it will not appear again	One prompt per install

A trainee who declines is not asked again automatically. They can still connect from the profile.

Android version gate

permissionDialogMinRuntime() picks the minimum app version by Android API level:

Device	Minimum app version to auto-prompt
API level 34 and above (`HEALTH_CONNECT_PLATFORM_API_LEVEL`), where Health Connect is part of the platform	`1.0.6` (`HEALTH_CONNECT_PROMPT_MIN_RUNTIME`)
Below API level 34	`1.0.5` (`HEALTH_CONNECT_LEGACY_PROMPT_MIN_RUNTIME`)

runtimeIsAtLeast compares Constants.expoConfig.version against the minimum. An app below it never prompts on its own, though the profile card can still start the connection.

Android without Health Connect

On Android 13 and below, Health Connect is a separate app. When getSdkStatus() reports that the provider needs installing or updating:

offerInstall shows a one-time dialog (confirmHealthInstall).
On confirm it opens the Play Store listing, by market:// link first and the web URL as a fallback.
whenAppReturns waits for the app to come back to the foreground, then asks for access if Health Connect is now available.

When the health store is simply unavailable, the “prompted” flag is left unset on purpose, so a later OS update that adds it still gets one prompt.

Disconnecting

useHealthSync().disconnect clears the connected flag and unregisters the background task. It does not revoke the OS permission, and it does not delete anything on the server.

Backend

Routes are in apps/core-api/src/modules/trainee/trainee.routes.ts, behind trainee bearer auth and the app access check.

`POST /v1/trainee/health/days`

The live ingestion endpoint.

{
  "days": [
    { "date": "2026-10-06", "steps": 8421 },
    { "date": "2026-10-07", "steps": 3110 }
  ]
}

Validated by ingestHealthDaysBody: 1 to 90 entries (HEALTH_MAX_DAYS_PER_INGEST), date as YYYY-MM-DD, steps a non-negative integer up to 100000 (MAX_DAILY_STEPS). ingestHealthDays in trainee.service.ts:

Resolves each date in the trainee’s time zone.
Silently skips days older than 90 days or more than one day in the future.
When a date appears twice, the last one wins.
Upserts DailyMetric.steps for (clientId, date).

Response: 201 with { "days": N }, the number of days written. Because it is an upsert, a later sync with a higher total for today simply replaces the earlier value. It also replaces a value the trainee typed by hand for that day.

`GET /v1/trainee/health/summary`

Query: optional from and to dates. Defaults to the last 7 days.

{
  "range": { "from": "2026-09-30", "to": "2026-10-07" },
  "days": [{ "date": "2026-10-07", "steps": 3110, "restingHeartRate": null, "avgHeartRate": null }],
  "latestHeartRate": null
}

The heart rate fields are always null. They are kept only so older app builds that expect them keep working.

`POST /v1/trainee/health/samples` is retired

The first version of the sync sent raw samples. The route still exists so old app builds do not get an error: it validates the body with ingestHealthSamplesBody and answers 201 with a fixed result. It stores nothing. The HealthSample table and the HealthMetricType and HealthSource enums remain in the schema from that version. No current code inserts into the table. The only code that touches it is the trainee account deletion, which clears it.

Where the steps are used

DailyMetric.steps feeds the movement summary on the trainee home screen and the coach’s view of the daily steps requirement. See the training plan requirement in the data model section for how a steps goal is defined.

Limits and gotchas

Only steps are read. The HEART_RATE enum value and the heart rate columns on DailyMetric are not populated by the app.
Step counts arrive at most 30 days back on a fresh connect.
The server trusts the device’s day boundaries and the totals it sends. There is no server-side cross-check.
Health Connect totals can differ from what a wearable’s own app shows, because the rule keeps the single highest source per day.

​Permissions and build configuration

​Loading native modules safely

​The aggregation rule

​iOS

​Android

​highestSourcePerDay

​Sync

​Triggers

​Connecting

​The first-launch prompt

​Android version gate

​Android without Health Connect

​Disconnecting

​Backend

​POST /v1/trainee/health/days

​GET /v1/trainee/health/summary

​POST /v1/trainee/health/samples is retired

​Where the steps are used

​Limits and gotchas

Permissions and build configuration

Loading native modules safely

The aggregation rule

iOS

Android

`highestSourcePerDay`

Sync

Triggers

Connecting

The first-launch prompt

Android version gate

Android without Health Connect

Disconnecting

Backend

`POST /v1/trainee/health/days`

`GET /v1/trainee/health/summary`

`POST /v1/trainee/health/samples` is retired

Where the steps are used

Limits and gotchas