# HEARTFLOW_OS // System Architecture & Engineering Topography

## 📌 Executive Summary

HeartFlow OS is a distributed, edge-optimized telemetry pipeline designed for clinical-grade cardiovascular inference. The architecture addresses the inherent tension between heavy-compute machine learning paradigms and the constrained environments of low-power microcontrollers (TinyML).

By aggressively decoupling the presentation layer (Client), the orchestration and modeling engine (Core), and the physical target execution (Edge), the system achieves strict separation of concerns, high-throughput asynchronous concurrency, and near-zero downtime deployment of predictive models.

---

## 🏗 High-Level Architecture Diagram

```mermaid
graph TD
    %% Define styles
    classDef frontend fill:#111,stroke:#111,stroke-width:2px,color:#fff,font-family:monospace;
    classDef backend fill:#fff,stroke:#111,stroke-width:2px,color:#111,font-family:monospace;
    classDef ml_node fill:#e61919,stroke:#e61919,stroke-width:2px,color:#fff,font-family:monospace;
    classDef edge_tech fill:#f3f3f2,stroke:#111,stroke-width:2px,color:#111,font-family:monospace;
    classDef data fill:#94a3b8,stroke:#475569,stroke-width:2px,color:#fff,font-family:monospace;

    subgraph Client [Client Application / Next.js 16]
        direction TB
        UI["Views<br/>(page.tsx)"]:::frontend
        WS_Client["WebSocket<br/>(TelemetryContext.tsx)"]:::frontend
        HTTP_Client["HTTP Fetch"]:::frontend
    end

    subgraph Core [FastAPI Core / Python 3.10+]
        direction TB
        WS_Server["WebSocket Broker<br/>(main.py)"]:::backend
        REST_API["REST API Router<br/>(main.py)"]:::backend
        Simulator["Vitals Simulator<br/>(simulator.py)"]:::backend
        DB["SQLite & aiosqlite<br/>(database.py)"]:::backend
    end

    subgraph ML_Layer [Intelligence Pipeline / Scikit-Learn]
        direction TB
        Inference["Inference<br/>(inference.py)"]:::ml_node
        Ensemble["Soft-Voting<br/>(ensemble.py)"]:::ml_node
        Training["Model Training<br/>(models.py)"]:::ml_node
        EdgeCompiler["C-Code Exporter<br/>(export.py)"]:::ml_node
    end

    subgraph Storage [Persistence & Hardware]
        direction TB
        ModelWeights["Model Artifacts<br/>(model/)"]:::data
        CSV["Patient Dataset<br/>(patient_dataset.csv)"]:::data
        MCU["Edge Silicon<br/>(tinyml_model.h)"]:::edge_tech
    end

    %% Flows
    UI --> WS_Client
    UI --> HTTP_Client
    
    WS_Client <--> WS_Server
    HTTP_Client --> REST_API
    
    WS_Server --> Inference
    Simulator --> WS_Server
    REST_API --> DB
    REST_API --> Training
    REST_API --> EdgeCompiler
    
    Inference --> Ensemble
    Training --> ModelWeights
    Training --> CSV
    Ensemble --> ModelWeights
    EdgeCompiler --> Ensemble
    EdgeCompiler -.-> MCU
```

---

## 1. The Presentation Layer (Client Plane)
Engineered using **Next.js 16 (App Router)** and **React 19**.

- **Rendering Strategy:** Heavily leverages React Server Components (RSC) where applicable, while isolating stateful, high-frequency telemetry updates to optimized Client Components.
- **WebSocket Triage:** Bypasses standard HTTP overhead by multiplexing telemetry streams via native WebSockets (`ws://`). The stream is mapped into a React Context provider, aggressively memoized using `useMemo` and `useCallback` to prevent unnecessary DOM re-renders and React thrashing at 60Hz.
- **Visual Engineering:** Implements an Industrial Brutalist design language. All animations and Layout Transitions are hardware-accelerated (`transform`/`opacity` driven) utilizing `framer-motion` to maintain 60fps even under heavy CPU charting loads.

## 2. The Orchestration Engine (Core Plane)
Built entirely asynchronously on top of **FastAPI** (Python 3.10+).

- **Asynchronous Throughput:** Utilizing the `asyncio` event loop and `uvicorn`, the backend comfortably supports multiple concurrent clinical WebSocket connections. I/O-bound operations (database writes) are completely non-blocking.
- **Stateful Preprocessing:** Live data must match the exact multi-dimensional space the models were trained on. The backend retains a persistent `SimpleImputer` and `StandardScaler`, ensuring live inference vectors are identical in scale to the offline batch data without runtime data leakage.
- **Event-Driven Database:** Implements `aiosqlite` for non-blocking audit logging of predictions, ensuring the primary telemetry event loop is never stalled by disk I/O.

## 3. Intelligence Pipeline & MLOps
Designed for precision and zero-downtime deployment.

- **Distributed Soft-Voting:** Rather than relying on a monolithic architecture, inference is distributed across five orthogonal models (`RandomForest`, `SVM`, `KNN`, `LogisticRegression`, `MLPClassifier`). A soft-voting aggregator calculates the weighted probability distribution, offering a confidence interval rather than a binary black-box output.
- **Live Background Retraining:** The `/retrain` pipeline exposes an API for ingesting new clinical datasets. Upon payload validation, it spins up a `fastapi.BackgroundTasks` thread. The system dynamically updates imputers, recalculates decision boundaries across all 5 models, serializes the updated weights to disk (`.pkl`), and critically—hot-swaps the active `EnsembleModel` object in RAM. This ensures active patient telemetry sessions are never dropped during model redeployments.

## 4. The Edge Compilation Pipeline (TinyML)
The most critical engineering bottleneck in telemetry is getting heavy Python models onto $2 silicon.

- **AST-Based C-Transpilation:** Instead of running a heavyweight Python interpreter (like MicroPython) on the edge device, the backend parses the scikit-learn model's internal Abstract Syntax Trees (AST) and transpiles them directly into pure, statically typed `C` functions.
- **Zero-Dependency Guarantee:** The resulting `tinyml_model.h` file requires no external libraries. It bypasses `malloc()` completely, relying entirely on static stack allocation, eliminating the risk of heap fragmentation or memory leaks in long-running embedded nodes.
- **INT8 Quantization:** 64-bit floating point weights are mathematically clamped and scaled into 8-bit integers (`int8_t`). This quantization dramatically reduces flash storage requirements by up to ~75% and massively accelerates inference execution time on ALU architectures lacking dedicated floating-point hardware (FPU).