Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

synheart-wear ships a stable adapter layer per vendor. This page is the reference for what each adapter does, what it produces, and how it interacts with cloud streaming.

​
Adapter matrix

VendorLocal sourceCloud / push sourceRAMEN delivery hintStatus
Apple WatchHealthKit (apple_healthkit)—n/aReady
Health Connect (Android)Health Connect API—n/aReady
BLE HRM (any)GATT 0x180D Heart Rate Profile—n/aReady
WHOOPBroadcast HR via BLEOAuth + webhooksstream (full payload inline)Ready
Garmin (Cloud)—OAuth + Connect API webhooksping (REST pull required)Ready
Garmin Health SDK (RTS)Native real-time streaming—n/aOn-demand, license-gated
Fitbit—OAuth + webhooks (planned)pingPlanned
OuraHealthKit / Health Connect proxyOAuth (planned)pingVia HK/HC
Samsung Watch(planned)—n/aPlanned
The Dart DeviceAdapter enum lists platformHealth, fitbit, garmin, whoop, samsungHealth. The Swift and Kotlin enums additionally include bleHrm / BLE_HRM. Across all three platforms, Oura has no enum entry and is reached via OuraProvider; BLE HRM on Dart is reached via BleHrmBridge.

​
Apple HealthKit

Capabilities:
  • HR (instantaneous + samples).
  • HRV (RMSSD, SDNN; SDNN derived on-device when only RR is exposed).
  • Steps, calories, distance.
  • RR intervals via the HealthKit RR channel (workout-mode only on most Apple Watch models).
  • Health profile snapshot (DOB, sex, height, weight) for personalization context.
  • Workout events.
Permissions: standard HealthKit HKObjectType set, requested once via requestPermissions. source field on WearMetrics: "apple_healthkit".

​
Health Connect (Android)

Capabilities:
  • HR, HRV (when the recording app provides it; otherwise SDNN/RMSSD are unavailable).
  • Steps, calories, distance.
  • Sleep records (sleep stages from compatible apps).
Health Connect retention is capped per record type by the platform (typically ~30 days for HR, longer for sleep). Hosts that need older data must use the Apple XML backfill path (Apple users) or an OAuth cloud adapter. source field: "health_connect".

​
BLE HRM

Direct connection over BLE GATT Heart Rate Profile (0x180D). No vendor cloud, no OAuth. Compatible devices:
  • WHOOP (Broadcast HR mode).
  • Polar chest straps (H10, OH1).
  • Wahoo TICKR family.
  • Garmin HRM-Pro / HRM-Dual.
  • Any HRM advertising 0x180D Heart Rate Service.
Capabilities:
  • HR (every second per Bluetooth profile).
  • RR intervals when the device advertises the optional RR field.
The bridge runs its own permission/scan/connect/disconnect lifecycle independent of requestPermissions. See BLE Heart Rate Monitor for the detailed flow. source field: "ble_hrm".

​
WHOOP

Two modes:
ModePath
OAuth + webhooksCloud-side handles OAuth + webhook ingest, publishes wear.events, RAMEN delivers to client. DeliveryHint.stream (full payload inline).
BLE Broadcast HRLocal-only via BleHrmBridge. No cloud round-trip; no recovery/strain/sleep.
WhoopProvider exposes:
  • fetchRawDataForFlux(start, end) — pulls raw vendor data for HSI 1.3 transformation.
  • Real-time HR via webhooks (mode A) or BLE (mode B).
  • Workout events.
source field: "whoop" for the OAuth path. The cloud-vs-BLE distinction lives in meta.source_type ("whoop_cloud"); WHOOP via BLE Broadcast HR uses the shared BLE HRM adapter (source = "ble_hrm").

​
Garmin (Cloud)

Path: OAuth → Garmin Connect API webhooks → cloud → RAMEN. Delivery hint: ping — vendor only sends a notification; client must pull the full record via REST when needed. GarminProvider exposes:
  • fetchRawDataForFlux(start, end) — REST pull for Flux input.
  • Wellness, sleep, activity data classes (GarminWellnessData, GarminSleepData, GarminActivityData).
  • Connection state (GarminConnectionState) for UI.
  • Realtime data shape (GarminRealtimeData) when a session is active.
source field: "garmin" for the OAuth Connect API path; meta.source_type carries the more specific "garmin_cloud".

​
Garmin Health SDK (Real-Time Streaming)

Native RTS path — direct device pairing without going through Garmin Connect cloud. Requires a separate Garmin license and is bundled on demand for licensed integrations only. The underlying Garmin Health SDK code is proprietary; this SDK exposes a GarminHealth provider façade that wraps it. source field: "garmin_sdk" (the adapter id from GarminSdkAdapter).

​
Fitbit (planned)

OAuth + webhooks pattern, DeliveryHint.ping. Currently scaffolding; not production. source field: "fitbit".

​
Oura

Today the Oura ring data flows through HealthKit (iOS) and Health Connect (Android) — the SDK’s OuraProvider is a thin classifier over those data sources. A direct OAuth path is planned. source field: "oura" (the underlying HK / Health Connect proxy is captured via the data path, not a different source string).

​
Apple Health XML backfill

When a user exports export.zip from the iOS Health app: 
User exports export.zip from iOS Health app
        │
        ▼
parse via AppleHealthXmlParser
        │
        ▼
batch into AppleHealthSample records
        │
        ▼
synheart_core_backfill_open(db_path, import_id)
        │
        ▼ insert_batch (batched)
synheart_core_backfill_insert_batch(import_id, samples_json)
        │
        ▼
synheart_core_backfill_finalize(import_id)
Idempotency keys ensure repeated imports don’t duplicate samples in the runtime’s SQLite store. The high-level path through synheart-core aggregates samples per day and replays them via Synheart.srmPushWearableDaily(...) so the imported data populates the user’s runtime baselines.

​
RAMEN 🍜 integration

Each cloud adapter participates in the RAMEN stream when the cloud wear-service publishes events: 
vendor webhook
    ↓
wear-service ingests, persists, publishes wear.events
    ↓
RAMEN gRPC stream → synheart-stream-runtime client
    ↓
Synheart runtime broadcasts RamenEvent
    ↓
synheart-core wires WearableEventProcessor onto WearModule
    ↓
WearModule routes by vendor → adapter handler
    ↓
WearMetrics emitted on streamHR / streamHRV / readMetrics
Each adapter handler decides how to consume RamenEvent.payload_json:
  • DeliveryHint.stream: parse inline, emit immediately.
  • DeliveryHint.ping: schedule a REST pull (via the adapter’s provider) to fetch the body.
  • DeliveryHint.unknown: treat as stream (best-effort) and log.

​
Permission flow

SynheartWear.requestPermissions(permissions, reason):
  1. Maps Synheart PermissionType values to OS permission scopes.
  2. Routes to the appropriate adapter (HealthKit on iOS, Health Connect on Android, OAuth flow for cloud adapters).
  3. Returns Map<PermissionType, ConsentStatus> per type.
Adapters that don’t have OS-level permissions (BLE HRM relies on Bluetooth Manager prompts; cloud OAuth requires app navigation) handle their own UX outside this method.