Proposal: optional Apple Health bridge using Yuvomi’s existing API

[KevinvFeng]

I would like to explore an optional Apple Health integration for Yuvomi.

This is not a proposal to replace the PWA or build a second native Yuvomi client. I have read #255 and understand the maintenance and architectural concerns around a full Flutter/native application.

Yuvomi already handles the Apple data that is available through open server-side protocols:

• Calendar through CalDAV
• Contacts through CardDAV
• Reminders through CalDAV/VTODO, mapped to Tasks or Shopping

The remaining gap is health data stored locally in HealthKit. A self-hosted Yuvomi server cannot access HealthKit directly, so users currently need to enter vitals manually or configure an external exporter and custom middleware.

Proposed direction

Create an optional, narrowly scoped bridge that:

1. Reads selected HealthKit samples with explicit user permission.
2. Converts them to Yuvomi’s health data model.
3. Uploads only new samples through a scoped health:write API token.
4. Keeps source identifiers locally to prevent duplicate imports.
5. Remains separate from the main Yuvomi web client.

The bridge could initially be either:

• Compatibility with an existing exporter such as Health Auto Export, using a small Yuvomi import adapter; or
• A small community-maintained iOS companion app focused only on HealthKit synchronization.

Suggested MVP

Initially support the vital types Yuvomi already displays:

• Weight
• Blood pressure
• Blood glucose
• Oxygen saturation
• Body temperature

Possible follow-ups could include sleep and activity data if the Yuvomi health model gains support for them.

Possible core API improvements

The existing vitals endpoint accepts one measurement per request. Reliable synchronization may benefit from:

• A batch health-import endpoint
• external_source and external_id fields with a uniqueness constraint
• Clear per-user token ownership for health imports
• An idempotent response for samples that were already imported
• Documented timestamp and unit normalization rules

These changes would be useful for other integrations as well, including Android Health Connect and wearable-provider APIs.

Non-goals

• Replacing the Yuvomi PWA
• Reimplementing Yuvomi’s user interface
• Duplicating CalDAV/CardDAV synchronization
• Synchronizing Apple Notes or financial data in the first version
• Requiring a mobile framework inside the Yuvomi repository

Questions

1. Would this direction fit Yuvomi’s architecture and project scope?
2. Would you prefer the bridge to live in a separate community repository?
3. Would a generic import endpoint be acceptable in Yuvomi core?
4. Should the first implementation target an existing REST exporter, or would a dedicated HealthKit companion be preferable?
5. What ownership model should an import token use when a household contains multiple members?

I am willing to prototype and maintain the integration, but I would like to confirm the preferred architecture before starting implementation.

[ulsklyc]

Thank you for reading #255 first and framing this around the existing API instead of against it - that is what makes this proposal answerable.

Your premise checks out. There is an API token system with per-area scopes, and health is one of them, so a bridge can be granted access to exactly the health endpoints and nothing else. That is the right shape: the bridge is a client, Yuvomi stays a server, and nothing about the PWA changes.

One thing the current API does not offer, and it matters for anything that syncs rather than posts once: the health endpoints are write and read, not a change feed. A bridge can push a weight or a workout, but it has no way to ask "what happened since I last checked", so a two-way or resumable sync would need something that does not exist yet. Push-only from Apple Health into Yuvomi works today.

The other half is not technical: a bridge that talks to Apple Health has to run on Apple's platform, which means a shortcut, an app, or something the household installs and keeps working across iOS releases. That is exactly the maintenance surface #255 was cautious about - it does not go away by living outside this repo, it moves.

Which is why I would keep this outside the project and supported by it rather than owned by it: the API is the contract, and the bridge is somebody's companion tool. #743 asks for the same thing from the Google/Fitbit side, and the same reasoning applies to both.

Staying open, and if you build something against the health scope I would like to hear how the API holds up - the missing change feed is the part I would expect to hurt first.

[ulsklyc]

The reasoning here is written down now rather than repeated per thread: docs/SCOPE.md, section 2.

Both premises were re-checked before that went in. The health scope is real - it is one of the canonical scopeable modules in server/scopes.js, so a bridge can be granted exactly the health endpoints and nothing else. And the missing change feed is real, so it has a ticket instead of a remark in three threads: #1002.

That ticket also carries the API improvements you listed and I did not actually answer at the time: a batch import endpoint, external_source / external_id with a uniqueness constraint, an idempotent response for samples already imported, and documented timestamp and unit normalisation. None of those columns exist today. They are the ingest half of the same bridge, and they were worth more than the silence they got.

[ulsklyc]

@KevinvFeng Closing this, and not as a no: the direction you proposed is the one the project settled on. I wrote "staying open" in August; what was open then has a place of its own now.

docs/SCOPE.md, section 2 "Integrations with other people's services", entry "Health providers", puts Apple Health outside the core and supported by the API: Yuvomi stays the server, the bridge is a client with a health-scoped token, in a repository of its own. The reason it is not in the core is the one from August - a HealthKit bridge has to run on Apple's platform and keep working across iOS releases, and one provider in the core serves only the households on that provider.

The core's share lives in #1002, which is open and not started: the change feed, and the ingest side you listed (batch import, external_source / external_id, idempotent responses, normalisation rules). Two of your questions never got an answer here. Exporter or dedicated companion is yours to choose, since the bridge is your tool. And on token ownership: a token acts as one member of the household. It writes that member's own entries, and with user_id in the body it can write for a person that member is a caregiver for; anyone else needs a token of their own.

Push-only works today. If you build against it, #1002 is where I would like to hear how the API holds up.