HealthEx → Folio · Ingestion Architecture (working doc)

EDITED

1 · Goals and non-goals

Goals

Replace manual record gathering on mikeshealth.app with automated IAS sync through HealthEx.
Define one ingestion pipeline that serves both the prototype and, later, multi-patient client onboarding.
Preserve Folio's core differentiator end to end: provenance-first — every datum keeps its source, date, and original document; nothing is merged silently.

Non-goals

The foliohealth.app demo stays frozen as a synthetic sales asset — it is not the substrate for this work.
No clinical decision support; the AI layer stays organizational and preparatory, as pitched.

EDITED

2 · What HealthEx actually provides

Patient flow: identity proofing via CLEAR (NIST IAL2/AAL2-certified) → consent granted to a receiving organization through HealthEx "projects" (auditable, revocable any time) → queries across TEFCA QHINs (MedAllies + CommonWell confirmed; Epic patient-directed access partnership announced Sep 2025) → records flow to the consented org.

Capability	Detail
Auth	JWT bearer; token scope = patients who consented to your org
Full record	`GET /FHIR/R4/Person/{id}/$everything` → FHIR R4 Bundle
Filtering	`_type=` any R4 resource; USCDIv3 / US Core recommended
Incremental sync	`_since={timestamp}` — only new/modified since last pull
Paging	`_count` / `_offset` + next/first/last links, streamed
Unified document	`DocumentReference?type=60591-5` → full-record PDF (base64)
Consent signal	HTTP 403 = consent absent or revoked (our disconnect trigger)
Not documented	Webhooks (assume polling), rate limits, pricing

Design consequence: HealthEx normalizes to FHIR R4 for us — no raw C-CDA parsing in v1. Folio's effort goes where it differentiates: provenance, conflict surfacing, and the AI layer.

EDITED

3 · End-to-end flows

3.1 Enrollment (once per patient)

Patient taps Connect my records → redirected into HealthEx's flow.
CLEAR identity proofing (IAL2) — owned entirely by HealthEx/CLEAR.
Patient grants consent to the Folio project; scope and revocability live in HealthEx.
Folio stores the binding: {folio_user_id ↔ healthex_patient_id, consented_at, scope}.
First sync runs immediately (full $everything).

3.2 Sync (recurring)

trigger (nightly cron + manual "Refresh records")
  → GET $everything?_since={last_sync}   (paged)
  → RAW STORE      bundle + unified PDF, content-hashed, immutable
  → NORMALIZE      FHIR resources → folio_records (§4)
  → DEDUP          within-org by id/version; cross-org by (code, date, value)
                   near-duplicates are LINKED, never deleted
  → CONFLICTS      same concept, active, differing values → "Needs review"
  → AI ENRICH      plain-language context, action-item re-rank, brief regen
  → STAGE REVIEW   "new since last sync" — patient accepts into record
  → advance last_sync watermark

3.3 Revocation, export, deletion

403 → mark source Disconnected; already-imported data is the patient's copy and stays unless they delete it.
TEFCA IAS duties: self-service export (raw bundles + PDFs + normalized JSON) and hard deletion, logged.

EDITED

4 · The provenance-first record model

Layer 0 — Raw (immutable). Every bundle and PDF as received: {id, patient, source_org, retrieved_at, content_hash, payload}. Never edited; backs every "view source" drill-down.

Layer 1 — Normalized (folio_records). One row per clinical fact: {type, effective_date, source_org, source_doc → L0 ref, body, status}.

FHIR resource	Folio section
Condition	Conditions / Meds → condition status
MedicationRequest / MedicationStatement	Medication list — per-source rows; dose conflicts become visible here
Observation (laboratory)	Results → Labs (+ trend series by LOINC)
Observation (vital-signs)	Health snapshot (merged with Apple Health)
DiagnosticReport / ImagingStudy	Results → Imaging
Immunization	Immunizations — "no record found" stays a first-class state
DocumentReference	Documents (incl. the unified PDF)
Encounter · Procedure · CarePlan	Timeline / care-plan inputs
AllergyIntolerance	Allergy chip + print packet

Layer 2 — Derived (AI findings). Every AI output stored as its own record: {generated_at, model+version, input_record_refs[], guideline_refs[], body}. "Your findings stay yours," made structural: portable, vendor-labeled, never overwriting Layer 1. Conflict resolutions (patient-verified, provider-confirmed) live here with full history.

5 · Design decisions — pick, note why, done

D1

Backend for the mikeshealth prototype

OPEN

Where raw bundles, normalized records, and sync state live. The repo already carries Firebase config.

Firebase / Firestore + scheduled Cloud FunctionsRECOMMENDED — already in the stack; sync worker is one scheduled function. Supabase (Postgres) — better relational fit for record queries; new infra to run. Vercel functions + hosted Postgres — matches deploy story; more assembly.

D2

Sync cadence

OPEN

No webhooks documented — polling with _since is the mechanism either way.

Nightly poll + manual refresh buttonRECOMMENDED — matches the product's mental model. Manual only — simplest possible Phase 1. More frequent (hourly+) — only worth it if per-query pricing allows.

D3

Raw document retention

OPEN

Layer 0 is the audit substrate and enables reprocessing as the normalizer improves.

Keep every raw bundle + PDF, immutableRECOMMENDED — storage is cheap; provenance is the product. Keep latest snapshot only — smaller, but loses history and reprocessability.

D4

Client app deployment

OPEN

Where new clients live once foliohealth.app takes real users.

Separate app.foliohealth.app — new repo, real auth from commit oneRECOMMENDED — demo stays frozen as the sales asset. Grow the demo codebase — fastest start, but the localStorage SPA is structurally wrong for real data.

D5

Auth for the client app

OPEN

Needed the day the first real patient signs in on foliohealth.app.

Clerk — fastest polished auth + MFA. Firebase Auth — one vendor if D1 = Firebase. Auth0 — enterprise-friendly, more setup. Decide at client-app kickoff — fine; not needed for the prototype.

D6

IAS partner

OPEN

Hinges on the pricing answer (Q1 below). Same integration shape across all three.

HealthExLEADING — CLEAR identity, documented FHIR server, Epic partnership momentum. Health Gorilla — established QHIN, own IAS offering. Flexpa — developer-first; claims/payer strength.

D7

When the SOC 2 program starts

OPEN

Pitch commitment: program during pilot, Type I after, Type II within a year of first client.

Instrument the client-app repo from its first commit; program formally starts when the first client signsRECOMMENDED Start now (during prototype) — earlier spend (~$10–25K/yr platform), earliest Type I.

EDITED

6 · Phased plan

Phase 0 (this week): the HealthEx conversation — checklist in §7. Everything downstream depends on partner terms.

Phase 1 (~2–3 weeks after access): backend per D1 · you enroll through the real CLEAR flow (Folio's first IAL2-proofed patient — itself pitch material) · nightly _since sync + manual refresh · raw + normalized layers stored · records mapped into the UI shapes the Folio design pass already established · unified PDF into Documents.

Phase 2 (~2 weeks): dedup + conflict objects + staged "new since last sync" review · AI enrichment on new data (brief regeneration, action-item re-rank).

Phase 3: a month of real use. The prototype's job is to produce the honest list of what IAS returns messy — coverage gaps, duplicate labs, undated documents — before any client sees it.

Client-product deltas (foliohealth.app): separate deployment (D4) · real auth + MFA (D5) · consent registry + patient-visible audit log · self-service export/deletion (TEFCA duty) · SOC 2 program (D7) · DUA template ready for Cone-style partners.

7 · HealthEx call checklist — capture answers as you get them

Q1Pricing model — per-member, per-query, or platform fee? Setup costs?

This hardens the $35K IAS/data budget line — 40 patients × a decade × many orgs was the pitch's flagged unknown. Get it in writing.

Q2Sandbox: test patients, credentials, terms — can we build before contracting?

Docs reference test patients; unclear what a pre-contract developer relationship looks like.

Q3Notification model — webhooks on new data, or is polling with _since the design?

Nothing in the docs suggests webhooks; confirms D2.

Q4QHIN coverage today — MedAllies + CommonWell confirmed; where does Epic Nexus stand? Cone / Atrium / Novant reachability specifically?

Determines what your own prototype sync will actually retrieve.

Q5Raw source documents (C-CDA) available alongside normalized FHIR?

For provenance display and future reprocessing; the unified PDF may be the only document form.

Q6Consent granularity — can a patient scope by category or org? How do consent changes reach us (403-only, or a consent status API)?

Shapes the Disconnected-state UX and the consent registry design.

Q7Data-use posture: their TEFCA privacy/security flow-down terms, BAA/DUA expectations for Folio.

Feeds the client-product legal stack and the Cone DUA conversation.

Q8Rate limits, SLA, and the support channel during the pilot.

Sizing the nightly sync job and knowing who to call when a source stops responding.

EDITED

8 · Risks, honestly

Risk	Mitigation
Coverage is uneven (pitch already conceded this)	Prototype measures retrieval success + source completeness on your own record first — same metrics as the Cone pilot
No webhooks → staleness	Nightly poll + manual refresh matches the product's mental model
Cross-org duplicates	Link, never delete; show both with provenance
Pricing surprises	Get the number before Phase 1 code; Health Gorilla / Flexpa are same-shaped fallbacks
Normalized FHIR hides source nuance	Store the unified PDF + push on Q5 so every number can still drill to a document

Sources: docs.healthex.io/fhir-server · healthex.io policy playbook & TEFCA privacy notice · HIT Consultant (Aug 2025) · Healthcare IT News (HealthEx + Epic) · Fierce Healthcare (HealthEx + CLEAR) · open.epic TEFCA IAS.