# novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor architecture

> Architecture diagram of the GitHub repository novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor
- Repository: https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor

## Overview

VALOR is an offline-first health and disaster-risk companion, with Zynq and ShrikeFi firmware platforms. Its main user-to-result path acquires physiological and environmental readings, derives clinical biomarkers, assesses clinical and disaster risk, then presents local status and can optionally publish telemetry. The README also documents FPGA-assisted PPG timing, TinyML inference, and a desktop dashboard. The sampled excerpts establish algorithms and some module references, but do not expose every runtime call; undocumented subsystem links are omitted or marked unverified.

Main entry points: [`firmware/shrikefi/main_shrikefi.c`](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/main_shrikefi.c) (ShrikeFi firmware), [`firmware/zynq/main_simulation.c`](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/zynq/main_simulation.c) (Zynq simulation), [`firmware/shrikefi/shrikefi_link_driver.c`](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/shrikefi_link_driver.c) (FPGA link driver), [`firmware/shrikefi/shrikefi_dashboard.c`](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/shrikefi_dashboard.c) (Desktop dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Device Platforms"]
  node_shrike_main["ShrikeFi firmware<br/>[main_shrikefi.c]"]
  node_zynq_sim["Zynq simulation<br/>[main_simulation.c]"]
  node_ppg_sensor["MAX30102 driver<br/>[max30102.c]"]
  node_env_sensors["Environmental drivers<br/>[bme280.c]"]
  node_pm_sensor["Particulate drivers<br/>[pms5003.c]"]
  node_fpga_link["FPGA link driver"]
  node_fpga_bitstream["FPGA bitstream"]
end

subgraph group_biomarkers["Vital Processing"]
  node_hrv["HRV analysis<br/>[hrv_analysis.h]"]
  node_spo2["SpO2 estimation<br/>[spo2_engine.c]"]
  node_resp_rate["PPG respiratory rate"]
  node_sqi["PPG signal quality<br/>[ppg_sqi.c]"]
  node_calibration["PM2.5 calibration"]
end

subgraph group_assessment["Risk Assessment"]
  node_clinical["Clinical triage"]
  node_disaster["Disaster risk engine"]
  node_nn["INT8 risk model"]
end

subgraph group_interfaces["User Interfaces"]
  node_dashboard["Desktop dashboard"]
  node_display["Device display<br/>[ssd1306.c]"]
  node_web_status["Web status<br/>[web_status.c]"]
  node_mqtt["WiFi and MQTT"]
end

node_rescue_user(("Rescue user"))
node_sensors(("Health and environment sensors"))
node_broker(("MQTT broker"))

node_sensors -.->|"supply readings"| node_shrike_main
node_shrike_main -->|"reads PPG"| node_ppg_sensor
node_shrike_main -->|"reads environment"| node_env_sensors
node_shrike_main -->|"reads particulates"| node_pm_sensor
node_shrike_main -->|"uses link"| node_fpga_link
node_shrike_main -->|"loads at boot"| node_fpga_bitstream
node_fpga_link -.->|"provides acceleration"| node_rescue_user
node_shrike_main -->|"computes HRV"| node_hrv
node_shrike_main -->|"estimates SpO2"| node_spo2
node_shrike_main -->|"estimates respiration"| node_resp_rate
node_shrike_main -->|"checks signal quality"| node_sqi
node_shrike_main -->|"calibrates PM2.5"| node_calibration
node_shrike_main -->|"assesses vitals"| node_clinical
node_shrike_main -->|"assesses disaster risk"| node_disaster
node_shrike_main -->|"runs inference"| node_nn
node_zynq_sim -->|"computes HRV"| node_hrv
node_zynq_sim -->|"assesses scenarios"| node_disaster
node_zynq_sim -->|"runs inference"| node_nn
node_shrike_main -.->|"streams telemetry"| node_dashboard
node_shrike_main -.->|"updates display"| node_display
node_shrike_main -.->|"serves status"| node_web_status
node_shrike_main -.->|"publishes telemetry"| node_mqtt
node_mqtt -.->|"optional publish"| node_broker
node_dashboard -.->|"shows assessments"| node_rescue_user
node_display -.->|"shows status"| node_rescue_user
node_web_status -.->|"shows status"| node_rescue_user

click node_shrike_main "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/main_shrikefi.c"
click node_zynq_sim "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/zynq/main_simulation.c"
click node_ppg_sensor "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/max30102.c"
click node_env_sensors "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/bme280.c"
click node_pm_sensor "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/pms5003.c"
click node_fpga_link "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/shrikefi_link_driver.c"
click node_fpga_bitstream "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/forgefpga_bitstream.h"
click node_hrv "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/hrv_analysis.h"
click node_spo2 "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/spo2_engine.c"
click node_resp_rate "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/ppg_respiratory_rate.c"
click node_sqi "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/ppg_sqi.c"
click node_calibration "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/pm25_calibration_int8.c"
click node_clinical "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/clinical_vitals_engine.c"
click node_disaster "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/disaster_risk_engine.c"
click node_nn "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/nn_risk_model_int8.c"
click node_dashboard "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/shrikefi_dashboard.c"
click node_display "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/ssd1306.c"
click node_web_status "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/web_status.c"
click node_mqtt "https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/wifi_mqtt_manager.c"

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_shrike_main,node_zynq_sim,node_ppg_sensor,node_env_sensors,node_pm_sensor,node_fpga_link,node_fpga_bitstream,node_rescue_user toneBlue
class node_hrv,node_spo2,node_resp_rate,node_sqi,node_calibration toneAmber
class node_clinical,node_disaster,node_nn toneMint
class node_dashboard,node_display,node_web_status,node_mqtt toneRose
class node_sensors,node_broker toneIndigo
```

## Components

### Device Platforms

- [ShrikeFi firmware](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/main_shrikefi.c): `firmware/shrikefi/main_shrikefi.c`
- [Zynq simulation](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/zynq/main_simulation.c): `firmware/zynq/main_simulation.c`
- [MAX30102 driver](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/max30102.c): `firmware/shrikefi/max30102.c`
- [Environmental drivers](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/bme280.c): `firmware/shrikefi/bme280.c`
- [Particulate drivers](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/pms5003.c): `firmware/shrikefi/pms5003.c`
- [FPGA link driver](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/shrikefi_link_driver.c): `firmware/shrikefi/shrikefi_link_driver.c`
- [FPGA bitstream](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/forgefpga_bitstream.h): `firmware/shrikefi/forgefpga_bitstream.h`

### Vital Processing

- [HRV analysis](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/hrv_analysis.h): `firmware/core/hrv_analysis.h`
- [SpO2 estimation](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/spo2_engine.c): `firmware/core/spo2_engine.c`
- [PPG respiratory rate](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/ppg_respiratory_rate.c): `firmware/core/ppg_respiratory_rate.c`
- [PPG signal quality](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/ppg_sqi.c): `firmware/core/ppg_sqi.c`
- [PM2.5 calibration](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/pm25_calibration_int8.c): `firmware/core/pm25_calibration_int8.c`

### Risk Assessment

- [Clinical triage](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/clinical_vitals_engine.c): `firmware/core/clinical_vitals_engine.c`
- [Disaster risk engine](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/disaster_risk_engine.c): `firmware/core/disaster_risk_engine.c`
- [INT8 risk model](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/core/nn_risk_model_int8.c): `firmware/core/nn_risk_model_int8.c`

### User Interfaces

- [Desktop dashboard](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/shrikefi_dashboard.c): `firmware/shrikefi/shrikefi_dashboard.c`
- [Device display](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/ssd1306.c): `firmware/shrikefi/ssd1306.c`
- [Web status](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/web_status.c): `firmware/shrikefi/web_status.c`
- [WiFi and MQTT](https://github.com/novafang23/fpga-accelerated-personal-health-companion-edge-disaster-monitor/blob/main/firmware/shrikefi/wifi_mqtt_manager.c): `firmware/shrikefi/wifi_mqtt_manager.c`

### Other components

- **Rescue user**
- **Health and environment sensors**
- **MQTT broker**

## Connections

- Health and environment sensors → ShrikeFi firmware: supply readings (evidence: `README.md`)
- ShrikeFi firmware → MAX30102 driver: reads PPG (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → Environmental drivers: reads environment (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → Particulate drivers: reads particulates (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → FPGA link driver: uses link (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → FPGA bitstream: loads at boot (evidence: `README.md`)
- FPGA link driver → Rescue user: provides acceleration
- ShrikeFi firmware → HRV analysis: computes HRV (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → SpO2 estimation: estimates SpO2 (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → PPG respiratory rate: estimates respiration (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → PPG signal quality: checks signal quality (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → PM2.5 calibration: calibrates PM2.5 (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → Clinical triage: assesses vitals (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → Disaster risk engine: assesses disaster risk (evidence: `firmware/shrikefi/main_shrikefi.c`)
- ShrikeFi firmware → INT8 risk model: runs inference (evidence: `firmware/shrikefi/main_shrikefi.c`)
- Zynq simulation → HRV analysis: computes HRV (evidence: `firmware/zynq/main_simulation.c`)
- Zynq simulation → Disaster risk engine: assesses scenarios (evidence: `firmware/zynq/main_simulation.c`)
- Zynq simulation → INT8 risk model: runs inference (evidence: `firmware/zynq/main_simulation.c`)
- ShrikeFi firmware → Desktop dashboard: streams telemetry (evidence: `README.md`)
- ShrikeFi firmware → Device display: updates display
- ShrikeFi firmware → Web status: serves status
- ShrikeFi firmware → WiFi and MQTT: publishes telemetry (evidence: `README.md`)
- WiFi and MQTT → MQTT broker: optional publish (evidence: `firmware/shrikefi/wifi_mqtt_manager.c`)
- Desktop dashboard → Rescue user: shows assessments (evidence: `README.md`)
- Device display → Rescue user: shows status
- Web status → Rescue user: shows status
