# madhu240750/h2s-dispenser- architecture

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

- Interactive diagram: https://gitdiagram.com/madhu240750/h2s-dispenser-
- Repository: https://github.com/madhu240750/h2s-dispenser-

## Overview

SAFE-SENSE is a hackathon prototype for tracking H₂S exposure using passive colorimetric wristbands, browser-based scan analysis, worker/supervisor views, and a Raspberry Pi dispenser. The main user journey is band issuance, worker scan and exposure/risk recording, then history and safety alerts for workers and supervisors. The README also describes a standalone FastAPI alternative. Source excerpts are partial: the documented scan and calibration capabilities are included, but uncertain internal wiring and the claimed persistent Firestore storage are not represented as implemented components.

Main entry points: [`src/App.tsx`](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/App.tsx) (Application Controller), [`server.ts`](https://github.com/madhu240750/h2s-dispenser-/blob/main/server.ts) (Express API and Realtime Bus), [`src/components/Scanner.tsx`](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/Scanner.tsx) (Return Scanner), [`src/components/WorkerApp.tsx`](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/WorkerApp.tsx) (Worker App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Band and Scan Workflow"]
  node_band["Passive Dosimeter"]
  node_app["Application Controller<br/>[App.tsx]"]
  node_scanner["Return Scanner<br/>[Scanner.tsx]"]
  node_color["Color Analysis<br/>[colorPipeline.ts]"]
  node_kiosk["Dispenser Kiosk"]
end

subgraph group_operations["Worker and Supervisor Views"]
  node_workerapp["Worker App<br/>[WorkerApp.tsx]"]
  node_host["Host Safety Station"]
  node_admin["Admin Console<br/>[AdminSuite.tsx]"]
end

subgraph group_services["API and Device Services"]
  node_express["Express API and Realtime Bus<br/>[server.ts]"]
  node_fastapi["Alternative FastAPI Hub<br/>[main.py]"]
  node_pi["Raspberry Pi Station<br/>[main.py]"]
  node_state["Application State<br/>[App.tsx]"]
end

subgraph group_safety["Alerts and Calibration"]
  node_alertbanner["Risk Alert Banner"]
  node_notifications["Browser Alerts and Siren"]
  node_calibration["Calibration and Demo Data<br/>[mockEcosystem.ts]"]
end

node_environment(("H₂S Environment"))
node_worker(("Worker"))
node_supervisor(("Safety Supervisor"))

node_environment -->|"exposes chemically"| node_band
node_worker -->|"uses"| node_workerapp
node_workerapp -->|"starts scan"| node_scanner
node_band -->|"presents color patch"| node_scanner
node_scanner -->|"submits image colors"| node_color
node_color -->|"returns estimate"| node_app
node_app -->|"posts scan result"| node_express
node_express -->|"updates worker records"| node_state
node_app -->|"provides worker data"| node_workerapp
node_app -->|"provides roster and risk data"| node_host
node_supervisor -->|"reviews roster"| node_host
node_app -->|"provides management data"| node_admin
node_app -->|"shows high-risk alert"| node_alertbanner
node_app -->|"triggers emergency warning"| node_notifications
node_admin -->|"views calibration references"| node_calibration
node_worker -->|"requests wristband"| node_kiosk
node_kiosk -->|"requests dispense"| node_app
node_pi -->|"posts dispense and heartbeat"| node_express
node_express -->|"assigns band and shift"| node_state
node_fastapi -.->|"maintains separate in-memory records"| node_state

click node_app "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/App.tsx"
click node_scanner "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/Scanner.tsx"
click node_color "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/utils/colorPipeline.ts"
click node_workerapp "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/WorkerApp.tsx"
click node_host "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/HostSafetyStation.tsx"
click node_admin "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/AdminSuite.tsx"
click node_alertbanner "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/HighRiskAlertBanner.tsx"
click node_notifications "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/utils/notificationSystem.ts"
click node_calibration "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/data/mockEcosystem.ts"
click node_express "https://github.com/madhu240750/h2s-dispenser-/blob/main/server.ts"
click node_fastapi "https://github.com/madhu240750/h2s-dispenser-/blob/main/backend/main.py"
click node_pi "https://github.com/madhu240750/h2s-dispenser-/blob/main/raspberry_pi/main.py"
click node_kiosk "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/RaspberryPiKiosk.tsx"
click node_state "https://github.com/madhu240750/h2s-dispenser-/blob/main/src/App.tsx"

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_band,node_app,node_scanner,node_color,node_kiosk toneBlue
class node_workerapp,node_host,node_admin toneAmber
class node_express,node_fastapi,node_pi,node_state toneMint
class node_alertbanner,node_notifications,node_calibration,node_worker toneRose
class node_environment,node_supervisor toneIndigo
```

## Components

### Band and Scan Workflow

- **Passive Dosimeter**
- [Application Controller](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/App.tsx): `src/App.tsx`
- [Return Scanner](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/Scanner.tsx): `src/components/Scanner.tsx`
- [Color Analysis](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/utils/colorPipeline.ts): `src/utils/colorPipeline.ts`
- [Dispenser Kiosk](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/RaspberryPiKiosk.tsx): `src/components/RaspberryPiKiosk.tsx`

### Worker and Supervisor Views

- [Worker App](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/WorkerApp.tsx): `src/components/WorkerApp.tsx`
- [Host Safety Station](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/HostSafetyStation.tsx): `src/components/HostSafetyStation.tsx`
- [Admin Console](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/AdminSuite.tsx): `src/components/AdminSuite.tsx`

### API and Device Services

- [Express API and Realtime Bus](https://github.com/madhu240750/h2s-dispenser-/blob/main/server.ts): `server.ts`
- [Alternative FastAPI Hub](https://github.com/madhu240750/h2s-dispenser-/blob/main/backend/main.py): `backend/main.py`
- [Raspberry Pi Station](https://github.com/madhu240750/h2s-dispenser-/blob/main/raspberry_pi/main.py): `raspberry_pi/main.py`
- [Application State](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/App.tsx): `src/App.tsx`

### Alerts and Calibration

- [Risk Alert Banner](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/components/HighRiskAlertBanner.tsx): `src/components/HighRiskAlertBanner.tsx`
- [Browser Alerts and Siren](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/utils/notificationSystem.ts): `src/utils/notificationSystem.ts`
- [Calibration and Demo Data](https://github.com/madhu240750/h2s-dispenser-/blob/main/src/data/mockEcosystem.ts): `src/data/mockEcosystem.ts`

### Other components

- **H₂S Environment**
- **Worker**
- **Safety Supervisor**

## Connections

- H₂S Environment → Passive Dosimeter: exposes chemically
- Worker → Worker App: uses
- Worker App → Return Scanner: starts scan
- Passive Dosimeter → Return Scanner: presents color patch
- Return Scanner → Color Analysis: submits image colors
- Color Analysis → Application Controller: returns estimate
- Application Controller → Express API and Realtime Bus: posts scan result
- Express API and Realtime Bus → Application State: updates worker records
- Application Controller → Worker App: provides worker data
- Application Controller → Host Safety Station: provides roster and risk data
- Safety Supervisor → Host Safety Station: reviews roster
- Application Controller → Admin Console: provides management data
- Application Controller → Risk Alert Banner: shows high-risk alert
- Application Controller → Browser Alerts and Siren: triggers emergency warning
- Admin Console → Calibration and Demo Data: views calibration references
- Worker → Dispenser Kiosk: requests wristband
- Dispenser Kiosk → Application Controller: requests dispense
- Raspberry Pi Station → Express API and Realtime Bus: posts dispense and heartbeat
- Express API and Realtime Bus → Application State: assigns band and shift
- Alternative FastAPI Hub → Application State: maintains separate in-memory records