# vlad12-k/oncovax-iot-platform architecture

> Architecture diagram of the GitHub repository vlad12-k/oncovax-iot-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vlad12-k/oncovax-iot-platform
- Repository: https://github.com/vlad12-k/oncovax-iot-platform

## Overview

OncoVax monitors simulated cold-storage devices: telemetry is published over MQTT, normalized and checked for temperature excursions, then persisted for observability and operator handling. Operators review and acknowledge alerts through the dashboard and API. Optional Node-RED controls can change simulator scenarios and inject temporary events. The main runtime and control links are supported by the README and sampled source; unsampled subsystem internals are represented only at documented boundaries.

Main entry points: [`infra/mosquitto/mosquitto.conf`](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/infra/mosquitto/mosquitto.conf) (MQTT broker), [`services/worker/worker.py`](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py) (Telemetry worker), [`services/api/main.py`](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/api/main.py) (FastAPI service), [`services/web/app.js`](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/web/app.js) (Operator dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telemetry["Telemetry pipeline"]
  node_device_fleet["Simulated fleet<br/>[main.py]"]
  node_mqtt["MQTT broker<br/>[mosquitto.conf]"]
  node_worker["Telemetry worker<br/>[worker.py]"]
  node_normalize["Normalize and validate<br/>[worker.py]"]
  node_excursion["Excursion detection<br/>[worker.py]"]
  node_influx[("InfluxDB")]
end

subgraph group_operations["Alert operations"]
  node_mongo[("MongoDB alerts")]
  node_api["FastAPI service<br/>[main.py]"]
  node_alert_routes["Alert workflows<br/>[alerts.py]"]
  node_dashboard["Operator dashboard<br/>[app.js]"]
end

subgraph group_control["Simulator control"]
  node_nodered["Node-RED controls"]
  node_adapter["Orchestration adapter<br/>[main.py]"]
  node_runtime["Runtime controller<br/>[runtime_control.py]"]
end

subgraph group_observability["Observability"]
  node_grafana["Grafana dashboards"]
end

node_operator(("Operator"))

node_device_fleet -->|"publishes telemetry"| node_mqtt
node_mqtt -->|"dispatches telemetry"| node_worker
node_worker -->|"processes payload"| node_normalize
node_normalize -->|"evaluates records"| node_excursion
node_worker -->|"writes telemetry and alerts"| node_influx
node_worker -->|"inserts alert records"| node_mongo
node_grafana -->|"queries metrics"| node_influx
node_operator -->|"reviews alerts"| node_dashboard
node_dashboard -->|"requests and acknowledges"| node_api
node_api -->|"dispatches requests"| node_alert_routes
node_alert_routes -->|"reads and updates alerts"| node_mongo
node_api -->|"serves dashboard"| node_dashboard
node_nodered -.->|"publishes controls"| node_mqtt
node_mqtt -.->|"dispatches controls"| node_adapter
node_adapter -.->|"publishes mapped commands"| node_mqtt
node_mqtt -.->|"dispatches runtime commands"| node_runtime
node_runtime -.->|"controls scenario generation"| node_device_fleet

click node_device_fleet "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/simulator/main.py"
click node_mqtt "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/infra/mosquitto/mosquitto.conf"
click node_worker "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py"
click node_normalize "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py"
click node_excursion "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py"
click node_api "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/api/main.py"
click node_alert_routes "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/api/routes/alerts.py"
click node_dashboard "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/web/app.js"
click node_grafana "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/grafana/dashboards/oncovax-observability-final.v1.json"
click node_nodered "https://github.com/vlad12-k/oncovax-iot-platform/tree/main/flows/nodered"
click node_adapter "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/orchestration_adapter/main.py"
click node_runtime "https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/simulator/runtime_control.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_device_fleet,node_mqtt,node_worker,node_normalize,node_excursion,node_influx toneBlue
class node_mongo,node_api,node_alert_routes,node_dashboard toneAmber
class node_nodered,node_adapter,node_runtime toneMint
class node_grafana toneRose
class node_operator toneIndigo
```

## Components

### Telemetry pipeline

- [Simulated fleet](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/simulator/main.py): `services/simulator/main.py`
- [MQTT broker](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/infra/mosquitto/mosquitto.conf): `infra/mosquitto/mosquitto.conf`
- [Telemetry worker](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py): `services/worker/worker.py`
- [Normalize and validate](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py): `services/worker/worker.py`
- [Excursion detection](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/worker/worker.py): `services/worker/worker.py`
- **InfluxDB**

### Alert operations

- **MongoDB alerts**
- [FastAPI service](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/api/main.py): `services/api/main.py`
- [Alert workflows](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/api/routes/alerts.py): `services/api/routes/alerts.py`
- [Operator dashboard](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/web/app.js): `services/web/app.js`

### Simulator control

- [Node-RED controls](https://github.com/vlad12-k/oncovax-iot-platform/tree/main/flows/nodered): `flows/nodered`
- [Orchestration adapter](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/orchestration_adapter/main.py): `services/orchestration_adapter/main.py`
- [Runtime controller](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/services/simulator/runtime_control.py): `services/simulator/runtime_control.py`

### Observability

- [Grafana dashboards](https://github.com/vlad12-k/oncovax-iot-platform/blob/main/grafana/dashboards/oncovax-observability-final.v1.json): `grafana/dashboards/oncovax-observability-final.v1.json`

### Other components

- **Operator**

## Connections

- Simulated fleet → MQTT broker: publishes telemetry
- MQTT broker → Telemetry worker: dispatches telemetry
- Telemetry worker → Normalize and validate: processes payload
- Normalize and validate → Excursion detection: evaluates records
- Telemetry worker → InfluxDB: writes telemetry and alerts
- Telemetry worker → MongoDB alerts: inserts alert records
- Grafana dashboards → InfluxDB: queries metrics
- Operator → Operator dashboard: reviews alerts
- Operator dashboard → FastAPI service: requests and acknowledges
- FastAPI service → Alert workflows: dispatches requests
- Alert workflows → MongoDB alerts: reads and updates alerts
- FastAPI service → Operator dashboard: serves dashboard
- Node-RED controls → MQTT broker: publishes controls
- MQTT broker → Orchestration adapter: dispatches controls
- Orchestration adapter → MQTT broker: publishes mapped commands
- MQTT broker → Runtime controller: dispatches runtime commands
- Runtime controller → Simulated fleet: controls scenario generation