This document tracks the design decisions and architecture for handling high-frequency health data (IoT devices, wearables, continuous monitors) in Health Assistant.
The Problem
Standard clinical data maps beautifully to the HL7 FHIR Observation model. A blood test taken once every 3 months is easily stored in the fhir_observations PostgreSQL table. However, devices like the Apple Watch, Oura Ring, or continuous glucose monitors (CGMs) can generate health measurements every 1 to 5 minutes. Routing this data into standard FHIR structures results in massive table bloat, drastically degrading dashboard performance and slowing down routine clinical queries.
The Solution: Split Architecture
Health Assistant Implements a Frequency-based Routing Architecture
Low-Frequency (Clinical) Data -> FHIR Observations
Stored in standard fhir_observations table.
Used for blood panels, point-in-time weight, diagnostic results.
High-Frequency (Telemetry) Data -> TimescaleDB
Stored in the telemetry_data hypertable.
Extremely high ingestion limits and heavily compressed.
Energetic Routing via Biomarker Definitions
Instead Of Hardcoding Which Metrics Go To Which Database, Routing Is Configurable. The Biomarker_definitions Table Includes An Is_telemetry Boolean Flag. When Integration Webhooks Push Data To The Backend, The Parser Resolves The Data To a Standard Biomarker. The Core Sync Engine Then Inspects This Flag
If is_telemetry = true: Data is mapped to a TelemetryDataModel and saved to TimescaleDB.
If is_telemetry = false: Data is mapped to an Observation and saved to FHIR.
Automated Data Migration: System administrators can toggle this flag via the UI, making the system infinitely expandable for future IoT devices without requiring code changes (see "Long-Format Storage" below for why this is now truly zero-code). When the flag is toggled on an existing biomarker, the Celery task migrate_biomarker_data performs an automatic, batched (5000 ro