# bhavenkanwalu25-dev/h2sense-main architecture

> Architecture diagram of the GitHub repository bhavenkanwalu25-dev/h2sense-main, 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/bhavenkanwalu25-dev/h2sense-main
- Repository: https://github.com/bhavenkanwalu25-dev/h2sense-main

## Overview

h2sense is a passive cumulative H₂S dosimetry product: workers identify a badge, capture its colorimetric strip, receive a validated dose/TWA estimate, and save a reading to an occupational record; supervisors manage workers, badges, calibration, settings, and exposure history. The graph reflects README capabilities plus sampled call sites and the CV pipeline. Endpoint wiring beyond the sampled routes is represented at the router level where the README or application mount establishes it.

Main entry points: [`frontend/src/services/api.ts`](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/services/api.ts) (API Client), [`frontend/src/App.tsx`](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/App.tsx) (Role-based App), [`backend/app/main.py`](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/main.py) (FastAPI Application), [`backend/cv/pipeline.py`](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/pipeline.py) (Analysis Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Worker and Supervisor UI"]
  node_app["Role-based App<br/>[App.tsx]"]
  node_qr["Badge QR Scan"]
  node_camera["Camera Scan"]
  node_result["Reading Result"]
  node_api_service["API Client<br/>[api.ts]"]
end

subgraph group_api["API and Records"]
  node_main["FastAPI Application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_badge["Badge Registry<br/>[badges.py]"]
  node_cv_endpoint["CV Analyze Endpoint<br/>[cv.py]"]
  node_readings["Reading Records<br/>[readings.py]"]
  node_workers["Worker Dossiers<br/>[workers.py]"]
  node_models["Domain Models<br/>[models.py]"]
  node_database[("Dosimetry Database<br/>[database.py]")]
end

subgraph group_analysis["Dosimeter Analysis"]
  node_pipeline["Analysis Pipeline<br/>[pipeline.py]"]
  node_quality["Image Validation<br/>[validation.py]"]
  node_detector["Badge Region Detection<br/>[detector.py]"]
  node_calibrator["Optical Calibration<br/>[calibrator.py]"]
  node_color["Color Features<br/>[color_extractor.py]"]
  node_expiry["Expiry Validation<br/>[validation.py]"]
  node_exposure["Dose and TWA<br/>[exposure_engine.py]"]
  node_ml["ML Predictor<br/>[predictor.py]"]
  node_confidence["Confidence Scoring<br/>[confidence.py]"]
end

subgraph group_operations["Operations and Calibration"]
  node_dashboard["Supervisor Dashboard<br/>[DashboardView.tsx]"]
  node_workforce["Workforce Management<br/>[WorkforceView.tsx]"]
  node_calibration_lab["Calibration Lab"]
  node_settings["Safety Settings<br/>[SettingsView.tsx]"]
  node_demo["Demo Scenarios<br/>[demo.py]"]
  node_calibration_api["Calibration API<br/>[calibration.py]"]
  node_settings_api["Settings API<br/>[settings.py]"]
end

node_worker(("Worker"))
node_supervisor(("Supervisor"))

node_worker -->|"uses"| node_app
node_supervisor -->|"uses"| node_app
node_app -->|"opens scan"| node_qr
node_app -->|"opens scan"| node_camera
node_qr -->|"verifies badge"| node_api_service
node_camera -->|"submits image"| node_api_service
node_camera -.->|"requests preset"| node_demo
node_api_service -->|"REST requests"| node_main
node_main -->|"dispatches"| node_auth
node_main -->|"dispatches"| node_badge
node_main -->|"dispatches"| node_cv_endpoint
node_main -->|"dispatches"| node_readings
node_main -->|"dispatches"| node_workers
node_main -->|"dispatches"| node_calibration_api
node_main -->|"dispatches"| node_settings_api
node_cv_endpoint -->|"analyzes image"| node_pipeline
node_pipeline -->|"validates image"| node_quality
node_pipeline -->|"detects regions"| node_detector
node_pipeline -->|"calibrates colors"| node_calibrator
node_pipeline -->|"extracts features"| node_color
node_pipeline -->|"checks integrity"| node_expiry
node_pipeline -->|"estimates dose"| node_exposure
node_pipeline -->|"scores result"| node_confidence
node_exposure -->|"predicts dose"| node_ml
node_cv_endpoint -->|"returns analysis"| node_api_service
node_api_service -->|"provides estimate"| node_result
node_result -->|"saves reading"| node_api_service
node_api_service -->|"posts record"| node_readings
node_readings -->|"reads and writes"| node_database
node_workers -->|"reads and writes"| node_database
node_badge -->|"reads and writes"| node_database
node_auth -->|"reads and writes"| node_database
node_database -->|"persists entities"| node_models
node_app -->|"shows operations"| node_dashboard
node_app -->|"manages workers"| node_workforce
node_app -->|"opens calibration"| node_calibration_lab
node_app -->|"opens settings"| node_settings
node_app -->|"loads summaries"| node_api_service
node_dashboard -->|"loads metrics"| node_api_service
node_workforce -->|"manages dossiers"| node_api_service
node_calibration_lab -->|"uses calibration"| node_api_service
node_api_service -->|"calibration requests"| node_calibration_api
node_settings -->|"updates thresholds"| node_api_service
node_api_service -->|"settings requests"| node_settings_api
node_api_service -.->|"loads scenarios"| node_demo
node_demo -.->|"seeds demo data"| node_database

click node_app "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/App.tsx"
click node_qr "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/worker/WorkerQrScanView.tsx"
click node_camera "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/worker/WorkerCameraScanView.tsx"
click node_result "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/worker/WorkerScanResultView.tsx"
click node_api_service "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/services/api.ts"
click node_main "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/main.py"
click node_auth "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/auth.py"
click node_badge "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/badges.py"
click node_cv_endpoint "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/cv.py"
click node_readings "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/readings.py"
click node_workers "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/workers.py"
click node_models "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/database/models.py"
click node_database "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/database/database.py"
click node_pipeline "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/pipeline.py"
click node_quality "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/validation.py"
click node_detector "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/detector.py"
click node_calibrator "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/calibrator.py"
click node_color "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/color_extractor.py"
click node_expiry "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/validation.py"
click node_exposure "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/exposure_engine.py"
click node_ml "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/ml/predictor.py"
click node_confidence "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/confidence.py"
click node_dashboard "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/DashboardView.tsx"
click node_workforce "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/WorkforceView.tsx"
click node_calibration_lab "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/CalibrationLabView.tsx"
click node_settings "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/SettingsView.tsx"
click node_demo "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/demo.py"
click node_calibration_api "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/calibration.py"
click node_settings_api "https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/settings.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_app,node_qr,node_camera,node_result,node_api_service toneBlue
class node_main,node_auth,node_badge,node_cv_endpoint,node_readings,node_workers,node_models,node_database toneAmber
class node_pipeline,node_quality,node_detector,node_calibrator,node_color,node_expiry,node_exposure,node_ml,node_confidence toneMint
class node_dashboard,node_workforce,node_calibration_lab,node_settings,node_demo,node_calibration_api,node_settings_api,node_worker toneRose
class node_supervisor toneIndigo
```

## Components

### Worker and Supervisor UI

- [Role-based App](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Badge QR Scan](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/worker/WorkerQrScanView.tsx): `frontend/src/components/worker/WorkerQrScanView.tsx`
- [Camera Scan](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/worker/WorkerCameraScanView.tsx): `frontend/src/components/worker/WorkerCameraScanView.tsx`
- [Reading Result](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/worker/WorkerScanResultView.tsx): `frontend/src/components/worker/WorkerScanResultView.tsx`
- [API Client](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and Records

- [FastAPI Application](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/auth.py): `backend/app/api/endpoints/auth.py`
- [Badge Registry](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/badges.py): `backend/app/api/endpoints/badges.py`
- [CV Analyze Endpoint](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/cv.py): `backend/app/api/endpoints/cv.py`
- [Reading Records](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/readings.py): `backend/app/api/endpoints/readings.py`
- [Worker Dossiers](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/workers.py): `backend/app/api/endpoints/workers.py`
- [Domain Models](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/database/models.py): `backend/app/database/models.py`
- [Dosimetry Database](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/database/database.py): `backend/app/database/database.py`

### Dosimeter Analysis

- [Analysis Pipeline](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/pipeline.py): `backend/cv/pipeline.py`
- [Image Validation](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/validation.py): `backend/cv/validation.py`
- [Badge Region Detection](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/detector.py): `backend/cv/detector.py`
- [Optical Calibration](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/calibrator.py): `backend/cv/calibrator.py`
- [Color Features](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/color_extractor.py): `backend/cv/color_extractor.py`
- [Expiry Validation](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/validation.py): `backend/cv/validation.py`
- [Dose and TWA](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/exposure_engine.py): `backend/cv/exposure_engine.py`
- [ML Predictor](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/ml/predictor.py): `backend/ml/predictor.py`
- [Confidence Scoring](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/cv/confidence.py): `backend/cv/confidence.py`

### Operations and Calibration

- [Supervisor Dashboard](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/DashboardView.tsx): `frontend/src/components/DashboardView.tsx`
- [Workforce Management](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/WorkforceView.tsx): `frontend/src/components/WorkforceView.tsx`
- [Calibration Lab](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/CalibrationLabView.tsx): `frontend/src/components/CalibrationLabView.tsx`
- [Safety Settings](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/frontend/src/components/SettingsView.tsx): `frontend/src/components/SettingsView.tsx`
- [Demo Scenarios](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/demo.py): `backend/app/api/endpoints/demo.py`
- [Calibration API](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/calibration.py): `backend/app/api/endpoints/calibration.py`
- [Settings API](https://github.com/bhavenkanwalu25-dev/h2sense-main/blob/main/backend/app/api/endpoints/settings.py): `backend/app/api/endpoints/settings.py`

### Other components

- **Worker**
- **Supervisor**

## Connections

- Worker → Role-based App: uses
- Supervisor → Role-based App: uses
- Role-based App → Badge QR Scan: opens scan
- Role-based App → Camera Scan: opens scan
- Badge QR Scan → API Client: verifies badge
- Camera Scan → API Client: submits image
- Camera Scan → Demo Scenarios: requests preset
- API Client → FastAPI Application: REST requests
- FastAPI Application → Authentication: dispatches
- FastAPI Application → Badge Registry: dispatches
- FastAPI Application → CV Analyze Endpoint: dispatches
- FastAPI Application → Reading Records: dispatches
- FastAPI Application → Worker Dossiers: dispatches
- FastAPI Application → Calibration API: dispatches
- FastAPI Application → Settings API: dispatches
- CV Analyze Endpoint → Analysis Pipeline: analyzes image
- Analysis Pipeline → Image Validation: validates image
- Analysis Pipeline → Badge Region Detection: detects regions
- Analysis Pipeline → Optical Calibration: calibrates colors
- Analysis Pipeline → Color Features: extracts features
- Analysis Pipeline → Expiry Validation: checks integrity
- Analysis Pipeline → Dose and TWA: estimates dose
- Analysis Pipeline → Confidence Scoring: scores result
- Dose and TWA → ML Predictor: predicts dose
- CV Analyze Endpoint → API Client: returns analysis
- API Client → Reading Result: provides estimate
- Reading Result → API Client: saves reading
- API Client → Reading Records: posts record
- Reading Records → Dosimetry Database: reads and writes
- Worker Dossiers → Dosimetry Database: reads and writes
- Badge Registry → Dosimetry Database: reads and writes
- Authentication → Dosimetry Database: reads and writes
- Dosimetry Database → Domain Models: persists entities
- Role-based App → Supervisor Dashboard: shows operations
- Role-based App → Workforce Management: manages workers
- Role-based App → Calibration Lab: opens calibration
- Role-based App → Safety Settings: opens settings
- Role-based App → API Client: loads summaries
- Supervisor Dashboard → API Client: loads metrics
- Workforce Management → API Client: manages dossiers
- Calibration Lab → API Client: uses calibration
- API Client → Calibration API: calibration requests
- Safety Settings → API Client: updates thresholds
- API Client → Settings API: settings requests
- API Client → Demo Scenarios: loads scenarios
- Demo Scenarios → Dosimetry Database: seeds demo data