How idkhowtocodefr/heartflow_os works
HeartFlow OS combines browser-based clinical telemetry and TinyML with a FastAPI cloud plane and embedded firmware. The principal workflow is hardware vitals entering the browser over serial, local classification, and display/audit; cloud endpoints additionally provide prediction, history, dataset exploration, explanations, export, and retraining. README diagrams document the broad dual-plane design; backend call edges are grounded in the sampled main.py and SOURCE INDEX. Unsampled frontend and firmware internals are represented only where documented.
Main entry points: main.py FastAPI Gateways · page.tsx Live Monitor · main.cpp Embedded Firmware · serial.ts Serial Bridge
Components 23
Edge Telemetry & Inference
- Embedded Firmware
firmware/src/main.cpp - Serial Bridge
frontend/src/lib/edge/serial.ts - Browser TinyML
frontend/src/lib/edge/inference.ts - Telemetry Simulator
frontend/src/lib/edge/simulator.ts
Clinical Browser
- Live Monitor
frontend/src/app/monitor/page.tsx - Telemetry Context
frontend/src/context/TelemetryContext.tsx - Resilient Socket
frontend/src/hooks/useResilientSocket.ts - Clinical History
frontend/src/app/history/page.tsx - Dataset Explorer
frontend/src/app/dataset/page.tsx - Analytics View
frontend/src/app/analytics/page.tsx - MLOps Console
frontend/src/app/mlops/page.tsx
Cloud API & Analytics
- FastAPI Gateways
backend/main.py - Feature Explanations
frontend/src/lib/edge/explain.ts - Dataset Analytics
backend/dataset_analytics.py
Models & Operations
- Feature Preprocessing
backend/preprocessing.py - Cloud Inference
backend/inference.py - Voting Ensemble
backend/ensemble.py - Retrain Pipeline
backend/mlops.py - C Code Export
backend/export.py
Clinical Data
- Prediction History
backend/database.py - Clinical Dataset
backend/build_dataset_profile.py
Other components
- Vitals Hardware
- Clinical User
Connections 25
- Vitals Hardware → Embedded Firmware: senses vitals
- Embedded Firmware → Serial Bridge: streams frames
- Serial Bridge → Live Monitor: feeds telemetry
- Live Monitor → Browser TinyML: classifies locally
- Browser TinyML → Live Monitor: returns predictions
- Live Monitor → Telemetry Context: shares state
- Live Monitor → Resilient Socket: receives cloud feed
- Telemetry Simulator → Live Monitor: supplies samples
- Clinical User → Live Monitor: views telemetry
- Clinical User → Clinical History: reviews records
- Clinical History → Prediction History: loads archive
- FastAPI Gateways → Prediction History: logs predictions
backend/main.py - FastAPI Gateways → Feature Preprocessing: uses features
backend/main.py - FastAPI Gateways → Cloud Inference: evaluates predictions
backend/main.py - FastAPI Gateways → Voting Ensemble: gets ensemble
backend/main.py - FastAPI Gateways → Retrain Pipeline: starts retraining
backend/main.py - FastAPI Gateways → Telemetry Simulator: streams simulated vitals
backend/main.py - FastAPI Gateways → Dataset Analytics: profiles and pages
backend/main.py - FastAPI Gateways → Clinical Dataset: reads dataset
backend/main.py - FastAPI Gateways → C Code Export: generates C code
backend/main.py - Clinical User → Dataset Explorer: explores records
- Clinical User → Analytics View: views analytics
- Clinical User → MLOps Console: manages models
- Clinical User → Feature Explanations: requests explanation
- Clinical User → FastAPI Gateways: uses cloud services