docs: add multi-provider SDK architecture plan

[bartmichalak]

Architecture plan for expanding the SDK from Apple Health-only to multi-provider (Apple Health, Google Health Connect, Samsung Health) across Flutter and React Native.

Feel free to leave comments and join the discussion!

[bartmichalak]

not sure about that. Since we have specific types for each provider, shouldn't we have separate schemas (for records, sleep, workouts) - to be able to define custom enums for each provider?

Alternatives:

• not validate types completely (don't think that's a good idea)
• enums aggregating types from all providers (also doesn't seem to be a good idea)

[KaliszS]

Or we can just create mapping (provider type -> our unified type), which will do validation anyway (we can raise exception if mapping won't recognize type).

[bartmichalak]

Yeah, that might be a good approach too 👍

I wanted to use an enum in the API spec mostly for documentation purposes, to explicitly show what we accept on the BE side:

But maybe just mentioning that we accept native types and linking to the Apple / Samsung / Google documentation would be enough?

[bartmichalak]

I would add that it's not only in the case of sleep sessions that it differs.

Samsung and Google have the concept of a 'master record' also for health metrics, example:

      // ----- BLOOD_PRESSURE -----
      {
        "uid": "bp-uuid-001",
        "dataType": "BLOOD_PRESSURE",
        "startTime": 1706774400000,
        "endTime": null,
        "dataSource": { "appId": "com.sec.android.app.shealth", "deviceId": "phone-001" },
        "device": { /* ... */ },
        "values": [
          {"type": "SYSTOLIC", "value": 120.0},    // mmHg - systolic pressure (Float)
          {"type": "DIASTOLIC", "value": 80.0},    // mmHg - diastolic pressure (Float)
          {"type": "PULSE", "value": 72.0}         // BPM - pulse during measurement (Float, optional)
        ]
      },

[bartmichalak]

very preliminary review and just two thoughts off the top of my head, will come back to it tomorrow

[KaliszS]

Would be useful to have here comparison of what we can get from all 3 providers (in form of table).

[KaliszS]

Or we can just create mapping (provider type -> our unified type), which will do validation anyway (we can raise exception if mapping won't recognize type).

[kmlpiekarz]

I attached a document with full explanation, examples, and comparisons.

Main idea:

• We normalize data from Health Connect and Samsung to match the Apple Health structure.
• Sleep data: In Health Connect and Samsung, one record contains stages[]. We split them into separate records to match Apple’s flat structure.
• Workouts: If a workout contains sessions[], we also split them into separate records (like in Apple).
• Other records - If a record contains nested samples or seriesData, we split them into separate records too.

In short, we flatten all nested arrays into individual records to keep one consistent internal structure across all providers.

[bartmichalak]

@kmlpiekarz could you please review the document or just run the agant against current implementation, update the spec and merge? 🙏

[kmlpiekarz]

@kmlpiekarz could you please review the document or just run the agant against current implementation, update the spec and merge? 🙏

Yes, starting working on docs now