# awrs1-ai/bput-hackathon architecture

> Architecture diagram of the GitHub repository awrs1-ai/bput-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awrs1-ai/bput-hackathon
- Repository: https://github.com/awrs1-ai/bput-hackathon

## Overview

Industrial Safety Monitor combines edge vision-based PPE and fire detection with thermal and smoke telemetry, then fuses evidence into safety states and incident responses. The main workflow is camera and sensor input → hazard analysis → persisted or dispatched response → operator interfaces. The README documents several capabilities beyond the sampled excerpts; those are represented at their documented subsystem paths, while uncertain internal wiring is omitted.

Main entry points: [`run_system.py`](https://github.com/awrs1-ai/bput-hackathon/blob/main/run_system.py) (System Orchestrator), [`core/vision.py`](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/vision.py) (Vision Pipeline), [`services/db.py`](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/db.py) (Incident Store), [`core/fusion_engine.py`](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/fusion_engine.py) (Sensor Fusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Edge Inputs"]
  node_vision["Vision Pipeline<br/>[vision.py]"]
  node_fire["Fire Detection<br/>[fire_detector.py]"]
  node_hardware["ESP32 Bridge<br/>[hardware_bridge.py]"]
  node_thermal["Thermal Sensor<br/>[thermal_sensor.py]"]
  node_smoke["Smoke Sensor<br/>[smoke_sensor.py]"]
end

subgraph group_analysis["Hazard Analysis"]
  node_spatial["PPE Association<br/>[spatial.py]"]
  node_debounce["Violation Debounce<br/>[debounce.py]"]
  node_risk["Risk &amp; Evidence<br/>[risk_engine.py]"]
  node_fusion["Sensor Fusion<br/>[fusion_engine.py]"]
  node_states["Safety States<br/>[safety_states.py]"]
  node_runner["System Orchestrator<br/>[run_system.py]"]
end

subgraph group_response["Response Services"]
  node_db[("Incident Store<br/>[db.py]")]
  node_queue["Priority Alert Queue<br/>[alert_queue.py]"]
  node_telegram["Telegram Alerts<br/>[telegram_alert.py]"]
  node_actuation["Plant Actuation<br/>[hardware_bridge.py]"]
end

subgraph group_interfaces["Operator Interfaces"]
  node_api["REST &amp; WebSockets<br/>[api.py]"]
  node_analytics["Safety Analytics<br/>[analytics.py]"]
  node_dashboard["Command Dashboard<br/>[app.py]"]
  node_portal["Supervisor Portal<br/>[app.py]"]
end

node_camera(("Camera Feed"))
node_esp32(("ESP32 Sensors<br/>[esp32_firmware.ino]"))
node_operator(("Safety Operator"))

node_camera -->|"provides frames"| node_runner
node_runner -->|"processes frames"| node_vision
node_vision -->|"associates PPE"| node_spatial
node_vision -->|"confirms violations"| node_debounce
node_vision -->|"evaluates incidents"| node_risk
node_vision -->|"detects hazards"| node_fire
node_esp32 -->|"sends telemetry"| node_hardware
node_runner -->|"polls readings"| node_thermal
node_runner -->|"polls readings"| node_smoke
node_runner -->|"supplies evidence"| node_fusion
node_fire -->|"supplies fire scores"| node_fusion
node_thermal -->|"supplies readings"| node_fusion
node_smoke -->|"supplies readings"| node_fusion
node_fusion -->|"returns risk result"| node_runner
node_runner -->|"updates state"| node_states
node_risk -->|"logs incidents"| node_db
node_risk -->|"enqueues alerts"| node_queue
node_queue -->|"dispatches alerts"| node_telegram
node_states -.->|"sets alarm state"| node_actuation
node_actuation -.->|"commands actuators"| node_esp32
node_db -->|"serves event data"| node_api
node_db -->|"provides records"| node_analytics
node_db -->|"reads incidents"| node_dashboard
node_db -->|"reads incidents"| node_portal
node_dashboard -->|"shows status"| node_operator
node_portal -->|"shows alerts"| node_operator
node_portal -->|"requests status"| node_api

click node_vision "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/vision.py"
click node_fire "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/fire_detector.py"
click node_hardware "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/hardware_bridge.py"
click node_esp32 "https://github.com/awrs1-ai/bput-hackathon/blob/main/hardware/esp32_firmware/esp32_firmware.ino"
click node_thermal "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/thermal_sensor.py"
click node_smoke "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/smoke_sensor.py"
click node_spatial "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/spatial.py"
click node_debounce "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/debounce.py"
click node_risk "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/risk_engine.py"
click node_fusion "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/fusion_engine.py"
click node_states "https://github.com/awrs1-ai/bput-hackathon/blob/main/core/safety_states.py"
click node_runner "https://github.com/awrs1-ai/bput-hackathon/blob/main/run_system.py"
click node_db "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/db.py"
click node_queue "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/alert_queue.py"
click node_telegram "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/telegram_alert.py"
click node_actuation "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/hardware_bridge.py"
click node_api "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/api.py"
click node_analytics "https://github.com/awrs1-ai/bput-hackathon/blob/main/services/analytics.py"
click node_dashboard "https://github.com/awrs1-ai/bput-hackathon/blob/main/app.py"
click node_portal "https://github.com/awrs1-ai/bput-hackathon/blob/main/alert_app/app.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_vision,node_fire,node_hardware,node_thermal,node_smoke toneBlue
class node_spatial,node_debounce,node_risk,node_fusion,node_states,node_runner toneAmber
class node_db,node_queue,node_telegram,node_actuation toneMint
class node_api,node_analytics,node_dashboard,node_portal toneRose
class node_camera,node_operator toneIndigo
class node_esp32 toneTeal
```

## Components

### Edge Inputs

- [Vision Pipeline](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/vision.py): `core/vision.py`
- [Fire Detection](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/fire_detector.py): `core/fire_detector.py`
- [ESP32 Bridge](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/hardware_bridge.py): `services/hardware_bridge.py`
- [Thermal Sensor](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/thermal_sensor.py): `core/thermal_sensor.py`
- [Smoke Sensor](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/smoke_sensor.py): `core/smoke_sensor.py`

### Hazard Analysis

- [PPE Association](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/spatial.py): `core/spatial.py`
- [Violation Debounce](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/debounce.py): `core/debounce.py`
- [Risk & Evidence](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/risk_engine.py): `core/risk_engine.py`
- [Sensor Fusion](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/fusion_engine.py): `core/fusion_engine.py`
- [Safety States](https://github.com/awrs1-ai/bput-hackathon/blob/main/core/safety_states.py): `core/safety_states.py`
- [System Orchestrator](https://github.com/awrs1-ai/bput-hackathon/blob/main/run_system.py): `run_system.py`

### Response Services

- [Incident Store](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/db.py): `services/db.py`
- [Priority Alert Queue](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/alert_queue.py): `services/alert_queue.py`
- [Telegram Alerts](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/telegram_alert.py): `services/telegram_alert.py`
- [Plant Actuation](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/hardware_bridge.py): `services/hardware_bridge.py`

### Operator Interfaces

- [REST & WebSockets](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/api.py): `services/api.py`
- [Safety Analytics](https://github.com/awrs1-ai/bput-hackathon/blob/main/services/analytics.py): `services/analytics.py`
- [Command Dashboard](https://github.com/awrs1-ai/bput-hackathon/blob/main/app.py): `app.py`
- [Supervisor Portal](https://github.com/awrs1-ai/bput-hackathon/blob/main/alert_app/app.py): `alert_app/app.py`

### Other components

- **Camera Feed**
- [ESP32 Sensors](https://github.com/awrs1-ai/bput-hackathon/blob/main/hardware/esp32_firmware/esp32_firmware.ino): `hardware/esp32_firmware/esp32_firmware.ino`
- **Safety Operator**

## Connections

- Camera Feed → System Orchestrator: provides frames
- System Orchestrator → Vision Pipeline: processes frames
- Vision Pipeline → PPE Association: associates PPE
- Vision Pipeline → Violation Debounce: confirms violations
- Vision Pipeline → Risk & Evidence: evaluates incidents
- Vision Pipeline → Fire Detection: detects hazards
- ESP32 Sensors → ESP32 Bridge: sends telemetry
- System Orchestrator → Thermal Sensor: polls readings
- System Orchestrator → Smoke Sensor: polls readings
- System Orchestrator → Sensor Fusion: supplies evidence
- Fire Detection → Sensor Fusion: supplies fire scores
- Thermal Sensor → Sensor Fusion: supplies readings
- Smoke Sensor → Sensor Fusion: supplies readings
- Sensor Fusion → System Orchestrator: returns risk result
- System Orchestrator → Safety States: updates state
- Risk & Evidence → Incident Store: logs incidents
- Risk & Evidence → Priority Alert Queue: enqueues alerts
- Priority Alert Queue → Telegram Alerts: dispatches alerts
- Safety States → Plant Actuation: sets alarm state
- Plant Actuation → ESP32 Sensors: commands actuators
- Incident Store → REST & WebSockets: serves event data
- Incident Store → Safety Analytics: provides records
- Incident Store → Command Dashboard: reads incidents
- Incident Store → Supervisor Portal: reads incidents
- Command Dashboard → Safety Operator: shows status
- Supervisor Portal → Safety Operator: shows alerts
- Supervisor Portal → REST & WebSockets: requests status