Apple Health & Google Health Connect Observations

[janoliver20]

Feature: Apple Health & Google Health Connect Observations

Summary

Add Apple Health and Google Health Connect as new observation sources in the MORE app.

Health data from both platforms should be transformed in the KMM shared module into a common, provider-independent API model and sent to the DataGateway.

As part of this feature, the existing Garmin-oriented API model should be refined into a generic health data model that can represent observations from Garmin, Apple Health, and Google Health Connect without assuming provider-specific semantics.

The corresponding new observation types also need to be added to the StudyManager backend, allowing studies to configure and use Apple Health and Google Health Connect observations.

First two metrics:

• Steps
• Heartrate

Goals

• Add Apple Health integration on iOS.
• Add Google Health Connect integration on Android.
• Expose the new integrations as configurable observations in the MORE app.
• Introduce/refine a provider-independent health API model.
• Transform native Apple Health / Health Connect data into this model inside the KMM shared module.
• Send normalized observations through the existing DataGateway.
• Add the required observation types and configuration support to the StudyManager backend.
• Keep the model extensible for Garmin and potential future health data providers.

Proposed Architecture

The platform-specific integrations are responsible for retrieving the native health data. The KMM shared module then maps the retrieved data into the common API model before sending it to the DataGateway.

iOS
Apple Health / HealthKit
        │
        ▼
Platform-specific integration
        │
        ▼
KMM Shared Module
        │
        ├── validation
        ├── normalization
        └── transformation
                │
                ▼
        Health API Model
                │
                ▼
           DataGateway


Android
Google Health Connect
        │
        ▼
Platform-specific integration
        │
        ▼
KMM Shared Module
        │
        ├── validation
        ├── normalization
        └── transformation
                │
                ▼
        Health API Model
                │
                ▼
           DataGateway

The DataGateway should therefore not need to understand the native Apple Health or Health Connect representations.

API Model

The existing GarminDataPoint model should be reviewed and refactored into a provider-independent health observation model.

Common concepts should be represented independently of their source provider, for example:

• timestamps and duration
• heart rate
• steps
• distance
• activity
• blood pressure
• sleep duration
• sleep stages
• SpO2
• naps, where available
• source/provenance information

Provider-specific concepts should not be presented as equivalent measurements when their semantics differ.

For example, Garmin-specific sleep scores or derived metrics should either remain optional/provider-specific or be represented together with sufficient provenance information.

The model should also explicitly identify the source of an observation, e.g.:

GARMIN
APPLE_HEALTH
HEALTH_CONNECT

Where possible, the model should preserve information about the original source/device so that downstream consumers can determine where a measurement originated.

KMM Transformation

The transformation into the DataGateway API model should live in the KMM shared module.

Conceptually:

Apple Health data ─────┐
                       │
Health Connect data ───┼──> Shared transformation ──> API model ──> DataGateway
                       │
Garmin data ───────────┘

Provider-specific mappings should normalize equivalent concepts while preserving differences where no reliable 1:1 mapping exists.

Examples include:

Apple Health asleepDeep  -> DEEP
Apple Health asleepCore  -> LIGHT
Apple Health asleepREM   -> REM

Health Connect DEEP      -> DEEP
Health Connect LIGHT     -> LIGHT
Health Connect REM       -> REM

Garmin deep              -> DEEP
Garmin light             -> LIGHT
Garmin rem               -> REM

The transformation must not invent values for provider-specific metrics that are unavailable from another provider.

StudyManager

The StudyManager backend needs to support the new observation types so that studies can configure Apple Health and Health Connect data collection.

This includes:

• Adding the required Apple Health observation type(s).
• Adding the required Google Health Connect observation type(s).
• Making the new types available in study configuration.
• Ensuring existing Garmin observation configurations remain backwards compatible.

Acceptance Criteria

• Apple Health is available as an observation source in the MORE iOS app.
• Google Health Connect is available as an observation source in the MORE Android app.
• Required platform permissions/authorizations are requested and handled correctly.
• Apple Health data can be retrieved and passed to the KMM shared module.
• Health Connect data can be retrieved and passed to the KMM shared module.
• The current Garmin-focused API model is refined into a provider-independent health model.
• Common health concepts have documented mappings between Garmin, Apple Health, and Health Connect.
• Provider-specific values are preserved or omitted rather than incorrectly normalized.
• Transformation into the API model happens in the KMM shared module.
• Normalized observations can be sent successfully to the DataGateway.
• Apple Health observation type(s) are supported by the StudyManager backend.
• Health Connect observation type(s) are supported by the StudyManager backend.
• The new observation types can be configured for a study.
• Existing Garmin observation functionality remains compatible.
• Tests cover provider-specific transformations and the common API representation.

Open Questions

• How should provider-specific derived values such as Garmin sleep scores be represented?
• How much source/device metadata should be persisted?
• Should historical data be imported when an observation is enabled, and if so, for what time range?
• How should duplicate observations from multiple providers/devices be handled?