# rd7597/belloscope-ui architecture

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

- Interactive diagram: https://gitdiagram.com/rd7597/belloscope-ui
- Repository: https://github.com/rd7597/belloscope-ui

## Overview

1. **Overall shape**
   BelloScope is a Raspberry Pi–oriented, local-first medical device application. The main app is a Python + PySide2/QML desktop UI that sits on top of hardware drivers, signal-processing code, and a few connectivity services.

2. **App entry and UI shell**
   The visible application starts from `main.py` and `main.qml`. The QML side provides the shell, navigation, and visual design; the Python side provides the data and device operations that those pages consume.

3. **Page-driven UI structure**
   The repository is organized as a set of feature pages rather than a single screen: home, splash, settings, Wi‑Fi, Bluetooth, brightness, volume, shutdown, updates, QR, device info, profile, diagnosis, notes, and about. The medical workflows are separated into domain-specific QML groups such as `heartQML`, `hrateQML`, `spo2QML`, `temperatureQML`, `skinQML`, `entQML`, `consultQML`, and `widgetsQML`.

4. **Reusable UI components**
   `widgetsQML` contains shared building blocks like progress bars, battery icons, camera streamer UI, swipe/swap containers, text fields, and busy indicators. These are the presentation boundary between the shell and each feature page.

5. **Sensor and measurement layer**
   The Python modules under `modules/` and top-level scripts implement hardware access for the core measurements:
   - `modules/sensors/max30102.py` for pulse/SpO2 sensing
   - `modules/sensors/mlx90614.py` and `modules/temperature.py` for infrared temperature sensing
   - `modules/ads_1115.py` / `ads1115_battery.py` for analog/battery readings
   - `modules/battery.py` for power status
   - `i2cread.py` and `modules/sensors/spo2helpers.py` for low-level I2C and algorithm support  
   These modules feed measurement values into the UI pages.

6. **Signal processing and analysis boundary**
   Heart-rate and SpO2 are not just raw sensor reads; they pass through processing code such as `hrcalc.py`, `spo2.py`, `features.py`, and `modules/sensors/spo2helpers.py`. The repo also includes copies of external analysis libraries under `maindata/New/heartrate_analysis_python-master` and `maindata/New/max30102*-master`, showing that the app relies on algorithmic post-processing before displaying results.

7. **Audio subsystem**
   Audio capture and playback are handled by scripts like `sound_recording.py`, `modules/recorder.py`, `modules/test_audio.py`, and the vendored `SoundCard-master` tree. The app stores recordings such as `output.wav` and per-session files under `HR_recording/`, which suggests the UI can record, review, and analyze heart sounds or microphone input.

8. **Camera and streaming subsystem**
   Video/camera functionality is split across `modules/camera.py`, `streamer.py`, `modules/streamer.py`, `streamtest.py`, and the vendored `picamera2-main` repository. This indicates a separate media path for previewing, recording, or streaming camera frames, likely used by the QML `CameraStreamer` widget and related pages.

9. **Connectivity and device provisioning**
   The app has multiple outbound/inbound communication paths:
   - `BLE.py`, `BLE_on_off.py`, `modules/qrserialble.py`, and `modules/bluetooth-server.py` handle Bluetooth/BLE pairing or data exchange
   - `modules/ConnectWifi.py` and the various `ConnectWifi.py` copies handle Wi‑Fi setup
   - `mqttclient.py` and `modules/mqttclient.py` indicate MQTT-based messaging or upload
   - `modules/qrgen.py` plus the `PageQR` UI imply QR-based device provisioning or session handoff  
   The `aws_certificates/` folder shows a TLS-backed cloud connection path, likely for secure MQTT or device authentication.

10. **Local state and flat-file storage**
    The app keeps some operational state in simple files rather than a database: `users.txt`, `config.txt`, `adc_data.txt`, `response_data.csv`, and recording folders under `maindata/`. That points to a lightweight embedded architecture where local files hold user profiles, calibration/configuration, and measurement output.

11. **Update, device, and maintenance flow**
    Pages like `PageUpdates`, `PageUpdate2`, `PageDeviceinfo`, `PageDiagnose`, and `PageShutdown` form the maintenance/admin side of the product. These screens likely read system state from the Python backend and expose device lifecycle operations separate from the measurement workflow.

12. **Repo layout and dependency boundary**
    The root contains the active app, but there are also many archived or vendor trees under `maindata/New/` and `modules/`:
    - third-party source mirrors for camera, audio, and heart-rate processing
    - older application snapshots and test recordings
    - QML feature variants and experiments  
    For an architecture diagram, treat these as supporting libraries and historical branches, not as a single runtime subsystem.

13. **Runtime and platform assumptions**
    The project is built around Python 3, PySide2/Qt Quick, and Raspberry Pi hardware access via I2C, audio, camera, and wireless modules. The README’s dependency list confirms that the UI and hardware layers are tightly coupled to the Qt/QML stack and Raspberry Pi device libraries.

Main entry points: [`main.qml`](https://github.com/rd7597/belloscope-ui/blob/main/main.qml) (main.qml), [`backend.py`](https://github.com/rd7597/belloscope-ui/blob/main/backend.py) (backend.py), [`maindata/New/hrcalc.py`](https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/hrcalc.py) (Analysis), [`modules/camera.py`](https://github.com/rd7597/belloscope-ui/blob/main/modules/camera.py) (Media)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI shell"]
  node_main_py["main.py<br/>app entry<br/>[main.py]"]
  node_main_qml["main.qml<br/>QML shell<br/>[main.qml]"]
  node_widgets_qml["widgetsQML<br/>shared widgets"]
end

subgraph group_workflows["Clinical flows"]
  node_home_page["Home<br/>dashboard page<br/>[PageHome.qml]"]
  node_settings_pages["Settings<br/>[PageSettings.qml]"]
  node_updates_admin["Maintenance<br/>admin pages<br/>[PageUpdates.qml]"]
  node_qr_profile["Identity<br/>provisioning pages<br/>[PageQR.qml]"]
  node_heart_flow["Heart pages<br/>measurement pages"]
  node_hrate_flow["HR pages<br/>measurement pages<br/>[PageHR1.qml]"]
  node_spo2_flow["SpO2 pages<br/>measurement pages<br/>[PageSPO21.qml]"]
  node_temp_flow["Temp pages<br/>measurement pages"]
  node_skin_ent_flow["Skin/ENT pages<br/>clinical pages<br/>[PageSkin1.qml]"]
  node_consult_flow["Consultation<br/>clinical pages"]
end

subgraph group_device["Device services"]
  node_backend_py["backend.py<br/>Qt backend<br/>[backend.py]"]
  node_sensors["Sensors<br/>hardware drivers<br/>[max30102.py]"]
  node_connectivity["Connectivity<br/>radio/network<br/>[ConnectWifi.py]"]
  node_media["Media<br/>audio/video<br/>[camera.py]"]
  node_storage_state["Local state<br/>flat-file state<br/>[users.txt]"]
end

subgraph group_analysis["Signal processing"]
  node_signal_processing["Analysis<br/>signal processing<br/>[hrcalc.py]"]
end

subgraph group_vendor["Vendored support"]
  node_vendor_heartrate["HeartPy copy<br/>vendored library<br/>[heartpy.py]"]
  node_vendor_camera["Picamera2 copy<br/>vendored library<br/>[picamera2.py]"]
  node_vendor_audio["SoundCard copy<br/>vendored library<br/>[__init__.py]"]
end

node_main_py -->|"loads"| node_main_qml
node_main_py -->|"exposes"| node_backend_py
node_main_qml -->|"composes"| node_widgets_qml
node_main_qml -->|"navigates"| node_home_page
node_main_qml -->|"navigates"| node_settings_pages
node_main_qml -->|"navigates"| node_updates_admin
node_main_qml -->|"navigates"| node_qr_profile
node_main_qml -->|"navigates"| node_heart_flow
node_main_qml -->|"navigates"| node_hrate_flow
node_main_qml -->|"navigates"| node_spo2_flow
node_main_qml -->|"navigates"| node_temp_flow
node_main_qml -->|"navigates"| node_skin_ent_flow
node_main_qml -->|"navigates"| node_consult_flow
node_backend_py -->|"reads"| node_sensors
node_backend_py -->|"controls"| node_connectivity
node_backend_py -->|"controls"| node_media
node_backend_py -->|"persists"| node_storage_state
node_sensors -->|"feeds"| node_signal_processing
node_signal_processing -->|"results"| node_heart_flow
node_signal_processing -->|"results"| node_spo2_flow
node_media -->|"renders"| node_widgets_qml
node_storage_state -->|"supplies"| node_qr_profile
node_connectivity -->|"supports"| node_updates_admin
node_vendor_heartrate -.->|"supports"| node_signal_processing
node_vendor_camera -.->|"supports"| node_media
node_vendor_audio -.->|"supports"| node_media

click node_main_py "https://github.com/rd7597/belloscope-ui/blob/main/main.py"
click node_main_qml "https://github.com/rd7597/belloscope-ui/blob/main/main.qml"
click node_widgets_qml "https://github.com/rd7597/belloscope-ui/tree/main/widgetsQML"
click node_home_page "https://github.com/rd7597/belloscope-ui/blob/main/PageHome.qml"
click node_settings_pages "https://github.com/rd7597/belloscope-ui/blob/main/PageSettings.qml"
click node_updates_admin "https://github.com/rd7597/belloscope-ui/blob/main/PageUpdates.qml"
click node_qr_profile "https://github.com/rd7597/belloscope-ui/blob/main/PageQR.qml"
click node_heart_flow "https://github.com/rd7597/belloscope-ui/blob/main/heartQML/PageHeart_Lungs1.qml"
click node_hrate_flow "https://github.com/rd7597/belloscope-ui/blob/main/hrateQML/PageHR1.qml"
click node_spo2_flow "https://github.com/rd7597/belloscope-ui/blob/main/spo2QML/PageSPO21.qml"
click node_temp_flow "https://github.com/rd7597/belloscope-ui/blob/main/temperatureQML/PageTemperature1.qml"
click node_skin_ent_flow "https://github.com/rd7597/belloscope-ui/blob/main/skinQML/PageSkin1.qml"
click node_consult_flow "https://github.com/rd7597/belloscope-ui/blob/main/consultQML/PageConsultation1.qml"
click node_backend_py "https://github.com/rd7597/belloscope-ui/blob/main/backend.py"
click node_sensors "https://github.com/rd7597/belloscope-ui/blob/main/modules/sensors/max30102.py"
click node_connectivity "https://github.com/rd7597/belloscope-ui/blob/main/modules/ConnectWifi.py"
click node_media "https://github.com/rd7597/belloscope-ui/blob/main/modules/camera.py"
click node_storage_state "https://github.com/rd7597/belloscope-ui/blob/main/users.txt"
click node_signal_processing "https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/hrcalc.py"
click node_vendor_heartrate "https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/heartrate_analysis_python-master/heartpy/heartpy.py"
click node_vendor_camera "https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/picamera2-main/picamera2/picamera2.py"
click node_vendor_audio "https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/SoundCard-master/soundcard/__init__.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_main_py,node_main_qml,node_widgets_qml toneBlue
class node_home_page,node_settings_pages,node_updates_admin,node_qr_profile,node_heart_flow,node_hrate_flow,node_spo2_flow,node_temp_flow,node_skin_ent_flow,node_consult_flow toneAmber
class node_backend_py,node_sensors,node_connectivity,node_media,node_storage_state toneMint
class node_signal_processing toneRose
class node_vendor_heartrate,node_vendor_camera,node_vendor_audio toneIndigo
```

## Components

### UI shell

Qt/QML application shell and shared presentation widgets.

- [main.py](https://github.com/rd7597/belloscope-ui/blob/main/main.py): app entry · Python entrypoint that boots the Qt runtime and backend bridge. · `main.py`
- [main.qml](https://github.com/rd7597/belloscope-ui/blob/main/main.qml): QML shell · Top-level Qt Quick shell that drives navigation and app layout. · `main.qml`
- [widgetsQML](https://github.com/rd7597/belloscope-ui/tree/main/widgetsQML): shared widgets · Reusable QML controls used across feature pages. · `widgetsQML`

### Clinical flows

Feature pages for measurement and device workflows.

- [Home](https://github.com/rd7597/belloscope-ui/blob/main/PageHome.qml): dashboard page · Landing page for the main user flows. · `PageHome.qml`
- [Settings](https://github.com/rd7597/belloscope-ui/blob/main/PageSettings.qml): device settings · Settings, pairing, brightness, volume, Wi‑Fi, and shutdown pages. · `PageSettings.qml`
- [Maintenance](https://github.com/rd7597/belloscope-ui/blob/main/PageUpdates.qml): admin pages · Update, device info, diagnostics, and shutdown workflows. · `PageUpdates.qml`
- [Identity](https://github.com/rd7597/belloscope-ui/blob/main/PageQR.qml): provisioning pages · QR, profile, note, pair, and related user/session pages. · `PageQR.qml`
- [Heart pages](https://github.com/rd7597/belloscope-ui/blob/main/heartQML/PageHeart_Lungs1.qml): measurement pages · Heart and lung measurement screens. · `heartQML/PageHeart_Lungs1.qml`
- [HR pages](https://github.com/rd7597/belloscope-ui/blob/main/hrateQML/PageHR1.qml): measurement pages · Heart-rate workflow pages. · `hrateQML/PageHR1.qml`
- [SpO2 pages](https://github.com/rd7597/belloscope-ui/blob/main/spo2QML/PageSPO21.qml): measurement pages · Pulse oximetry workflow pages. · `spo2QML/PageSPO21.qml`
- [Temp pages](https://github.com/rd7597/belloscope-ui/blob/main/temperatureQML/PageTemperature1.qml): measurement pages · Temperature workflow pages. · `temperatureQML/PageTemperature1.qml`
- [Skin/ENT pages](https://github.com/rd7597/belloscope-ui/blob/main/skinQML/PageSkin1.qml): clinical pages · Specialty examination pages for skin, ENT, body, ear, face, and throat. · `skinQML/PageSkin1.qml`
- [Consultation](https://github.com/rd7597/belloscope-ui/blob/main/consultQML/PageConsultation1.qml): clinical pages · Consultation and clinical review pages. · `consultQML/PageConsultation1.qml`

### Device services

Python backend, hardware drivers, and connectivity services.

- [backend.py](https://github.com/rd7597/belloscope-ui/blob/main/backend.py): Qt backend · Python bridge exposing state and device actions to QML. · `backend.py`
- [Sensors](https://github.com/rd7597/belloscope-ui/blob/main/modules/sensors/max30102.py): hardware drivers · Core sensor drivers for pulse, temperature, battery, and ADC inputs. · `modules/sensors/max30102.py`
- [Connectivity](https://github.com/rd7597/belloscope-ui/blob/main/modules/ConnectWifi.py): radio/network · Wi‑Fi, Bluetooth, QR handoff, and MQTT communication paths. · `modules/ConnectWifi.py`
- [Media](https://github.com/rd7597/belloscope-ui/blob/main/modules/camera.py): audio/video · Camera preview/streaming and audio capture/playback services. · `modules/camera.py`
- [Local state](https://github.com/rd7597/belloscope-ui/blob/main/users.txt): flat-file state · Text, CSV, and recording files used for local session and measurement storage. · `users.txt`

### Signal processing

Measurement algorithms and post-processing layers.

- [Analysis](https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/hrcalc.py): signal processing · Heart-rate and SpO2 processing plus feature extraction. · `maindata/New/hrcalc.py`

### Vendored support

Embedded upstream code and archived runtime examples.

- [HeartPy copy](https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/heartrate_analysis_python-master/heartpy/heartpy.py): vendored library · Bundled heart-rate analysis library used for processing support. · `maindata/New/heartrate_analysis_python-master/heartpy/heartpy.py`
- [Picamera2 copy](https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/picamera2-main/picamera2/picamera2.py): vendored library · Bundled camera library and examples for Pi camera integration. · `maindata/New/picamera2-main/picamera2/picamera2.py`
- [SoundCard copy](https://github.com/rd7597/belloscope-ui/blob/main/maindata/New/SoundCard-master/soundcard/__init__.py): vendored library · Bundled sound-card backend used for audio capture and playback support. · `maindata/New/SoundCard-master/soundcard/__init__.py`

## Connections

- main.py → main.qml: loads · Python boots the QML UI shell.
- main.py → backend.py: exposes · Main process publishes backend objects to QML.
- main.qml → widgetsQML: composes · Shell assembles shared UI controls into pages.
- main.qml → Home: navigates · Shell routes into the home dashboard.
- main.qml → Settings: navigates · Shell routes into device settings pages.
- main.qml → Maintenance: navigates · Shell routes into maintenance/admin flows.
- main.qml → Identity: navigates · Shell routes into user identity and provisioning pages.
- main.qml → Heart pages: navigates · Shell routes into heart workflow pages.
- main.qml → HR pages: navigates · Shell routes into heart-rate workflow pages.
- main.qml → SpO2 pages: navigates · Shell routes into SpO2 workflow pages.
- main.qml → Temp pages: navigates · Shell routes into temperature workflow pages.
- main.qml → Skin/ENT pages: navigates · Shell routes into specialty clinical pages.
- main.qml → Consultation: navigates · Shell routes into consultation pages.
- backend.py → Sensors: reads · Backend pulls measurement and power data from hardware drivers.
- backend.py → Connectivity: controls · Backend manages wireless setup, pairing, and messaging.
- backend.py → Media: controls · Backend starts camera and audio workflows.
- backend.py → Local state: persists · Backend reads and writes local state and recordings.
- Sensors → Analysis: feeds · Raw sensor streams are passed into analysis code.
- Analysis → Heart pages: results · Processed heart metrics are rendered by workflow pages.
- Analysis → SpO2 pages: results · Processed SpO2 metrics are rendered by workflow pages.
- Media → widgetsQML: renders · Camera preview is embedded through shared QML widgets.
- Local state → Identity: supplies · Local user/session files support provisioning and identity pages.
- Connectivity → Maintenance: supports · Network paths enable update and device-management flows.
- HeartPy copy → Analysis: supports · Vendored heart-rate library underpins analysis logic.
- Picamera2 copy → Media: supports · Vendored camera stack underpins capture and streaming.
- SoundCard copy → Media: supports · Vendored audio stack underpins recording and playback.