Build a longitudinal patient record with TypeScript.

Updated: 2026-08-25 · 11 min read

The bottom line

Ingest records per source and category, retain stable source identities, map them to typed timeline events, and rebuild projections deterministically. Clinical time, source update time, and ingestion time should remain separate fields.

Key takeaways

• Use a stable source-aware key so refreshes update existing events instead of duplicating them.
• Sort by clinical time for display while retaining update and ingestion timestamps for operations.
• Treat uncertain dates and missing provenance as visible data-quality states.

Evidence boundary: Uses synthetic examples and source-aware record practices; it does not provide clinical decision support.

Author: FinchNode Engineering

Define one timeline event without flattening the record

type TimelineEvent = {
  key: string;
  kind: 'lab' | 'condition' | 'medication' | 'encounter' | 'immunization';
  clinicalTime?: string;
  recordedTime?: string;
  ingestedAt: string;
  title: string;
  summary?: string;
  source: { organization: string; resourceType: string; resourceId?: string };
  confidence: 'exact' | 'derived' | 'unknown';
};

Build stable, source-aware keys

Prefer a stable business identifier within its namespace. Otherwise use the source connection, resource type, and logical ID. A content hash can help detect changes, but it should not be the sole real-world identity because clinically distinct events can contain identical data.

Make refreshes incremental and reversible

1. 1. Read the next change window

   Use a source cursor, supported history, or bounded updated-since query.

2. 2. Upsert source records

   Preserve version, last-updated, and the raw-to-normalized mapping.

3. 3. Rebuild affected events

   Regenerate projections deterministically for changed source records.

4. 4. Mark removals explicitly

   Use tombstones or lifecycle state rather than silently deleting history.

5. 5. Commit the cursor

   Advance progress only after the data and projection transaction succeeds.

Design the timeline for uncertainty

• Group events with date-only precision separately from exact timestamps when ordering could mislead.
• Show source organization and freshness in the detail view.
• Do not infer clinical causality from adjacent events.
• Allow users to inspect the underlying coded concept and original text.
• Indicate when one source or category is unavailable or still syncing.

More FinchNode interoperability guides

• What we learned building patient-authorized FHIR connections across EHRs.
• SMART on FHIR OAuth with PKCE in React and Node.js.
• Fetch patient data with a FHIR API: Patient, labs, conditions, and medications.
• Epic and MyChart FHIR integration for patient-facing applications.
• Oracle Health FHIR integration: discovery, authorization, and tenant routing.
• How to normalize FHIR data across EHRs without losing the source.

Frequently asked questions