# idkhowtocodefr/heartflow_os architecture

> Architecture diagram of the GitHub repository idkhowtocodefr/heartflow_os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/idkhowtocodefr/heartflow_os
- Repository: https://github.com/idkhowtocodefr/heartflow_os

## Overview

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: [`backend/main.py`](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/main.py) (FastAPI Gateways), [`frontend/src/app/monitor/page.tsx`](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/monitor/page.tsx) (Live Monitor), [`firmware/src/main.cpp`](https://github.com/idkhowtocodefr/heartflow_os/blob/main/firmware/src/main.cpp) (Embedded Firmware), [`frontend/src/lib/edge/serial.ts`](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/serial.ts) (Serial Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge Telemetry &amp; Inference"]
  node_firmware["Embedded Firmware<br/>[main.cpp]"]
  node_serial["Serial Bridge<br/>[serial.ts]"]
  node_client_inference["Browser TinyML<br/>[inference.ts]"]
  node_simulator["Telemetry Simulator<br/>[simulator.ts]"]
end

subgraph group_client["Clinical Browser"]
  node_monitor["Live Monitor<br/>[page.tsx]"]
  node_telemetry["Telemetry Context"]
  node_socket["Resilient Socket"]
  node_history_ui["Clinical History<br/>[page.tsx]"]
  node_dataset_ui["Dataset Explorer<br/>[page.tsx]"]
  node_analytics_ui["Analytics View<br/>[page.tsx]"]
  node_mlops_ui["MLOps Console<br/>[page.tsx]"]
end

subgraph group_api["Cloud API &amp; Analytics"]
  node_api["FastAPI Gateways<br/>[main.py]"]
  node_explanations["Feature Explanations<br/>[explain.ts]"]
  node_dataset_analytics["Dataset Analytics"]
end

subgraph group_mlops["Models &amp; Operations"]
  node_preprocessing["Feature Preprocessing<br/>[preprocessing.py]"]
  node_inference["Cloud Inference<br/>[inference.py]"]
  node_ensemble["Voting Ensemble<br/>[ensemble.py]"]
  node_mlops_engine["Retrain Pipeline<br/>[mlops.py]"]
  node_export["C Code Export<br/>[export.py]"]
end

subgraph group_state["Clinical Data"]
  node_database[("Prediction History<br/>[database.py]")]
  node_dataset[("Clinical Dataset")]
end

node_hardware(("Vitals Hardware"))
node_clinician(("Clinical User"))

node_hardware -->|"senses vitals"| node_firmware
node_firmware -->|"streams frames"| node_serial
node_serial -.->|"feeds telemetry"| node_monitor
node_monitor -->|"classifies locally"| node_client_inference
node_client_inference -->|"returns predictions"| node_monitor
node_monitor -.->|"shares state"| node_telemetry
node_monitor -.->|"receives cloud feed"| node_socket
node_simulator -.->|"supplies samples"| node_monitor
node_clinician -.->|"views telemetry"| node_monitor
node_clinician -.->|"reviews records"| node_history_ui
node_history_ui -->|"loads archive"| node_database
node_api -->|"logs predictions"| node_database
node_api -->|"uses features"| node_preprocessing
node_api -->|"evaluates predictions"| node_inference
node_api -->|"gets ensemble"| node_ensemble
node_api -->|"starts retraining"| node_mlops_engine
node_api -->|"streams simulated vitals"| node_simulator
node_api -->|"profiles and pages"| node_dataset_analytics
node_api -->|"reads dataset"| node_dataset
node_api -->|"generates C code"| node_export
node_clinician -.->|"explores records"| node_dataset_ui
node_clinician -.->|"views analytics"| node_analytics_ui
node_clinician -.->|"manages models"| node_mlops_ui
node_clinician -.->|"requests explanation"| node_explanations
node_clinician -.->|"uses cloud services"| node_api

click node_firmware "https://github.com/idkhowtocodefr/heartflow_os/blob/main/firmware/src/main.cpp"
click node_serial "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/serial.ts"
click node_client_inference "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/inference.ts"
click node_simulator "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/simulator.ts"
click node_monitor "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/monitor/page.tsx"
click node_telemetry "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/context/TelemetryContext.tsx"
click node_socket "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/hooks/useResilientSocket.ts"
click node_history_ui "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/history/page.tsx"
click node_dataset_ui "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/dataset/page.tsx"
click node_analytics_ui "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/analytics/page.tsx"
click node_mlops_ui "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/mlops/page.tsx"
click node_api "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/main.py"
click node_preprocessing "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/preprocessing.py"
click node_inference "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/inference.py"
click node_ensemble "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/ensemble.py"
click node_mlops_engine "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/mlops.py"
click node_export "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/export.py"
click node_explanations "https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/explain.ts"
click node_dataset_analytics "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/dataset_analytics.py"
click node_database "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/database.py"
click node_dataset "https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/build_dataset_profile.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_firmware,node_serial,node_client_inference,node_simulator,node_clinician toneBlue
class node_monitor,node_telemetry,node_socket,node_history_ui,node_dataset_ui,node_analytics_ui,node_mlops_ui toneAmber
class node_api,node_explanations,node_dataset_analytics toneMint
class node_preprocessing,node_inference,node_ensemble,node_mlops_engine,node_export toneRose
class node_database,node_dataset,node_hardware toneIndigo
```

## Components

### Edge Telemetry & Inference

- [Embedded Firmware](https://github.com/idkhowtocodefr/heartflow_os/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Serial Bridge](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/serial.ts): `frontend/src/lib/edge/serial.ts`
- [Browser TinyML](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/inference.ts): `frontend/src/lib/edge/inference.ts`
- [Telemetry Simulator](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/simulator.ts): `frontend/src/lib/edge/simulator.ts`

### Clinical Browser

- [Live Monitor](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/monitor/page.tsx): `frontend/src/app/monitor/page.tsx`
- [Telemetry Context](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/context/TelemetryContext.tsx): `frontend/src/context/TelemetryContext.tsx`
- [Resilient Socket](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/hooks/useResilientSocket.ts): `frontend/src/hooks/useResilientSocket.ts`
- [Clinical History](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/history/page.tsx): `frontend/src/app/history/page.tsx`
- [Dataset Explorer](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/dataset/page.tsx): `frontend/src/app/dataset/page.tsx`
- [Analytics View](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/analytics/page.tsx): `frontend/src/app/analytics/page.tsx`
- [MLOps Console](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/app/mlops/page.tsx): `frontend/src/app/mlops/page.tsx`

### Cloud API & Analytics

- [FastAPI Gateways](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/main.py): `backend/main.py`
- [Feature Explanations](https://github.com/idkhowtocodefr/heartflow_os/blob/main/frontend/src/lib/edge/explain.ts): `frontend/src/lib/edge/explain.ts`
- [Dataset Analytics](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/dataset_analytics.py): `backend/dataset_analytics.py`

### Models & Operations

- [Feature Preprocessing](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/preprocessing.py): `backend/preprocessing.py`
- [Cloud Inference](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/inference.py): `backend/inference.py`
- [Voting Ensemble](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/ensemble.py): `backend/ensemble.py`
- [Retrain Pipeline](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/mlops.py): `backend/mlops.py`
- [C Code Export](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/export.py): `backend/export.py`

### Clinical Data

- [Prediction History](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/database.py): `backend/database.py`
- [Clinical Dataset](https://github.com/idkhowtocodefr/heartflow_os/blob/main/backend/build_dataset_profile.py): `backend/build_dataset_profile.py`

### Other components

- **Vitals Hardware**
- **Clinical User**

## Connections

- 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 (evidence: `backend/main.py`)
- FastAPI Gateways → Feature Preprocessing: uses features (evidence: `backend/main.py`)
- FastAPI Gateways → Cloud Inference: evaluates predictions (evidence: `backend/main.py`)
- FastAPI Gateways → Voting Ensemble: gets ensemble (evidence: `backend/main.py`)
- FastAPI Gateways → Retrain Pipeline: starts retraining (evidence: `backend/main.py`)
- FastAPI Gateways → Telemetry Simulator: streams simulated vitals (evidence: `backend/main.py`)
- FastAPI Gateways → Dataset Analytics: profiles and pages (evidence: `backend/main.py`)
- FastAPI Gateways → Clinical Dataset: reads dataset (evidence: `backend/main.py`)
- FastAPI Gateways → C Code Export: generates C code (evidence: `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
