# HERMES_Apple-Health-Bridge-Plan.md

## Purpose
Create the next Hygieia connector after Oura: an Apple Health / Apple Watch bridge that gets exportable device data into Hygieia honestly and repeatably.

## Why Apple Health next
Recommended next after Oura because it can provide broad value across:
- heart rate
- resting heart rate
- HRV
- sleep
- steps/activity
- workouts
- weight and selected body metrics if present

Unlike Oura, Apple Health is usually not a simple VPS-to-cloud OAuth connector. It is best treated as a **device export bridge** first.

## Recommended first implementation model
**Bridge import, not direct cloud login.**

That means:
1. export data from iPhone / Apple Health side
2. land it into a Hygieia source-specific intake path
3. parse and normalize into Hygieia collections
4. track import runs and freshness in `/connectors` and `/wearables`

## Honest connector state model
Use these states only:
- `not-configured`
- `sample`
- `trial`
- `ready`
- `live`

For Apple Health:
- `trial` = bridge defined and tested with real export file manually
- `live` = repeatable real bridge workflow is working, even if user-triggered

Do **not** imply direct Apple cloud OAuth if the implementation is actually export-based.

## Phase A — planning/build scaffold
1. create `lib/connectors/apple_health.js`
2. create `routes/connectors_apple_health.js`
3. mount it under `/connectors`
4. add Apple Health state panel actions:
   - sample import
   - import uploaded/exported file
   - bridge instructions
5. add an intake folder/reference for Apple Health bridge imports

## Phase B — data shape
Support a first-pass normalized import for these metrics where present:
- Heart Rate
- Resting HR
- HRV
- Sleep duration
- Steps
- VO2 Max
- Weight
- Workouts summary

Collections to feed:
- `wearable_metrics`
- `wearable_sessions`
- possibly `document_ingest_queue` for unsupported/ambiguous payload parts

## Phase C — source workflow
Initial user workflow:
1. export Apple Health data from device
2. place the export in the agreed Apple Health intake location
3. trigger manual import from Hygieia
4. show import-run result in `/connectors`
5. show freshness and imported metrics in `/wearables`

## Phase D — later improvements
Possible later upgrades:
- repeatable phone-to-VPS bridge
- shortcut/export automation
- selective health-export tooling
- more frequent sync process

## Implementation notes
- keep Apple Health explicit as a **bridge** source, not fake direct login
- preserve provenance/source labels on imported rows
- show freshness clearly in `/wearables`
- route all ingest bookkeeping through the existing shared connector helpers

## Immediate next coding task
Create the Apple Health connector scaffolding and wire it into `/connectors` so progress continues even while Oura is blocked in the new developer portal.