# andrewderango/heartflow architecture

> Architecture diagram of the GitHub repository andrewderango/heartflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andrewderango/heartflow
- Repository: https://github.com/andrewderango/heartflow

## Overview

##### Main Components
- Firmware Component – Represent the FRDM-K64F-based pacemaker firmware developed in Embedded C (compiled from Simulink models). This component handles low-level hardware control such as pulse generation and capacitor management.
- Desktop Application – Split this into two main parts:
- Backend (Electron main process and other Node.js/Python services): This layer includes Electron’s main process files (e.g., the “main” folder in dcm/src/main, which includes index.ts, index.cpp.ts, userService.ts, websockets.ts) and serial communication services (found in dcm/src/serial with both C++ and Python code).
- Frontend (Electron renderer process): Built with React and TypeScript, with its source files located under dcm/src/renderer and organized into components, pages (Dashboard, Login, Register), store, and context.
- Serial Communication Layer – This is the glue between the firmware and the desktop application. It uses a custom UART protocol (with handshake, polling, and data confirmation processes) to ensure bidirectional data transfer.

##### Relationships and Interactions
- That the backend also contains additional serial modules implemented in both C++ (e.g., websocket server code) and Python (asynchronous webserver processes) that help manage real-time telemetry data.
- A connection from the backend (or a dedicated serial module) to external hardware (the pacemaker firmware) representing the bidirectional data exchange.
- Optionally, show “Documentation” as an external resource that provides further details (e.g., refer to the docs/dcm_docs.pdf, pacemaker_docs.pdf, and serial_protocol_docs.pdf).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design clearly distinguishes between firmware (hardware-level operations) and the desktop application’s UI/backend.
- Multi-layered Architecture: Within the desktop application, note the separation between Electron’s main process (Node.js/Python handling operations/communication) and the renderer process (React-based UI).
- IPC and Asynchronous Processing: Emphasize that communication happens asynchronously using Electron’s IPC, web sockets in the backend (dcm/src/main/websockets.ts), and Python’s webserver for serial data processing.
- Modular Design: The serial communication logic is encapsulated in separate directories (dcm/src/serial/cpp and dcm/src/serial/python), underscoring a modular and extensible approach.

##### Relevant Technologies and Tools
- Frontend: React, TypeScript, PostCSS, Vite configuration (dcm/electron.vite.config.ts).
- Backend: Electron, Node.js, Electron Builder (electron-builder.yml), and Python.
- Firmware: Embedded C generated from Simulink models for the FRDM-K64F microcontroller.
- Serial Communication: Custom UART protocol with supporting modules in C++ and Python.
- Development Tools: ESLint, Prettier, and VSCode configuration tools (visible in the file tree).

##### Instructing the Principal Software Engineer – Essential Elements
- Architectural Layers: Separate concerns by illustrating how the desktop application is divided into at least three major layers – UI, application logic (backend), and communication subsystems.

- The Firmware running on the FRDM-K64F microcontroller (including pulse generation and heart emulation).
- The Desktop Application divided into the Electron backend (handling Node.js processes, serial communication, and Python-based webserver processes) and a React-based renderer.
- The Serial Communication module that bridges the desktop app and the firmware with a custom UART protocol.
- Supporting components and configuration/build resources that help manage the application development and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Firmware Layer
    subgraph "Firmware Layer"
        FW["FRDM-K64F Firmware (Embedded C from Simulink)"]:::firmware
    end

    %% Desktop Application
    subgraph "Desktop Application"
        subgraph "Backend Layer"
            EMP["Electron Main Process (dcm/src/main)"]:::backend
            SC["Serial Communication Module (dcm/src/serial)"]:::backend
        end
        subgraph "IPC / Preload Layer"
            PRE["IPC/Preload Scripts (dcm/src/preload)"]:::preload
        end
        subgraph "Frontend Layer"
            FE["React UI (Renderer) (dcm/src/renderer)"]:::frontend
        end
    end

    %% Documentation & Configuration
    subgraph "Documentation & Configuration"
        DOC["Documentation & Build Tools (docs & config files)"]:::doc
    end

    %% Interactions
    FE -->|"IPC"| PRE
    PRE -->|"IPC"| EMP
    EMP -->|"Commands/Telemetry"| SC
    SC <-->|"UART(handshake,polling,confirmation)"| FW
    DOC -->|"guides"| EMP

    %% Click Events
    click FW "https://github.com/andrewderango/heartflow/blob/main/firmware/firmware.c"
    click EMP "https://github.com/andrewderango/heartflow/tree/main/dcm/src/main"
    click SC "https://github.com/andrewderango/heartflow/tree/main/dcm/src/serial"
    click PRE "https://github.com/andrewderango/heartflow/tree/main/dcm/src/preload"
    click FE "https://github.com/andrewderango/heartflow/tree/main/dcm/src/renderer"
    click DOC "https://github.com/andrewderango/heartflow/tree/main/docs"

    %% Styles
    classDef firmware fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef preload fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef frontend fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef doc fill:#D8BFD8,stroke:#000,stroke-width:2px;
```
