# hamzainayat20/smart-safety-helmet architecture

> Architecture diagram of the GitHub repository hamzainayat20/smart-safety-helmet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamzainayat20/smart-safety-helmet
- Repository: https://github.com/hamzainayat20/smart-safety-helmet

## Overview

Smart-Safety-Helmet combines ESP32 telemetry, Firebase ingestion and safety assessments, inference services, alert handling, and an AI assistant. The intended flow is helmet measurements through secure upload, backend validation and assessment, then stored risk results and alerts. The README also identifies a Flutter application, but no Flutter/Dart source appears in the supplied tree, so its implementation and connections are not mapped. Some firmware and backend wiring is unsampled; dashed edges mark dependencies whose exact runtime calls are not shown.

Main entry points: [`functions/src/telemetry_ingestion.js`](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/telemetry_ingestion.js) (Telemetry ingestion), [`functions/src/assessment_pipeline.js`](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/assessment_pipeline.js) (Assessment pipeline), [`aws/assistant/runtime.js`](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/aws/assistant/runtime.js) (Assistant runtime), [`firmware/src/MotionPipeline.cpp`](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/MotionPipeline.cpp) (Motion pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_helmet["Helmet firmware"]
  node_sensors["Sensor acquisition<br/>[SensorManager.cpp]"]
  node_motion["Motion pipeline<br/>[MotionPipeline.cpp]"]
  node_fall["Fall detection"]
  node_telemetry["Telemetry builder"]
  node_upload["Secure uploader"]
end

subgraph group_firebase["Firebase backend"]
  node_telemetry_api["Telemetry ingestion"]
  node_auth["Device authentication<br/>[device_auth.js]"]
  node_contracts["Telemetry contract"]
  node_assessment["Assessment pipeline"]
  node_storage[("Assessment storage")]
  node_alerts["Alerts and actions<br/>[alert_logic.js]"]
end

subgraph group_inference["Risk inference"]
  node_inference_client["Inference client"]
  node_risk["Risk engine<br/>[risk_engine.py]"]
  node_models["Model registry<br/>[model_registry.py]"]
end

subgraph group_integrations["Assistant services"]
  node_assistant_runtime["Assistant runtime<br/>[runtime.js]"]
  node_assistant["Safety assistant"]
end

node_endpoint(("Ingestion endpoint"))
node_groq["Groq service"]

node_motion -.->|"evaluates windows"| node_fall
node_sensors -.->|"supplies samples"| node_motion
node_telemetry -.->|"encodes payload"| node_upload
node_upload -->|"posts telemetry"| node_endpoint
node_endpoint -.->|"routes request"| node_telemetry_api
node_telemetry_api -.->|"authenticates device"| node_auth
node_telemetry_api -.->|"validates telemetry"| node_contracts
node_assessment -->|"requests assessment"| node_inference_client
node_assessment -->|"persists result"| node_storage
node_inference_client -.->|"requests inference"| node_risk
node_risk -->|"uses models"| node_models
node_assistant_runtime -.->|"dispatches requests"| node_assistant
node_assistant_runtime -.->|"calls provider"| node_groq

click node_sensors "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/SensorManager.cpp"
click node_motion "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/MotionPipeline.cpp"
click node_fall "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/FallDetectionEngine.cpp"
click node_telemetry "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/TelemetryBuilder.cpp"
click node_upload "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/SecureIngestionClient.cpp"
click node_telemetry_api "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/telemetry_ingestion.js"
click node_auth "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/device_auth.js"
click node_contracts "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/telemetry_contract.js"
click node_assessment "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/assessment_pipeline.js"
click node_storage "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/assessment_storage.js"
click node_alerts "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/alert_logic.js"
click node_inference_client "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/inference_client.js"
click node_risk "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/inference_service/app/risk_engine.py"
click node_models "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/inference_service/app/model_registry.py"
click node_assistant_runtime "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/aws/assistant/runtime.js"
click node_assistant "https://github.com/hamzainayat20/smart-safety-helmet/blob/main/aws/assistant/assistant_service.js"

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_sensors,node_motion,node_fall,node_telemetry,node_upload toneBlue
class node_telemetry_api,node_auth,node_contracts,node_assessment,node_storage,node_alerts toneAmber
class node_inference_client,node_risk,node_models toneMint
class node_assistant_runtime,node_assistant toneRose
class node_endpoint,node_groq toneIndigo
```

## Components

### Helmet firmware

- [Sensor acquisition](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/SensorManager.cpp): `firmware/src/SensorManager.cpp`
- [Motion pipeline](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/MotionPipeline.cpp): `firmware/src/MotionPipeline.cpp`
- [Fall detection](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/FallDetectionEngine.cpp): `firmware/src/FallDetectionEngine.cpp`
- [Telemetry builder](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/TelemetryBuilder.cpp): `firmware/src/TelemetryBuilder.cpp`
- [Secure uploader](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/firmware/src/SecureIngestionClient.cpp): `firmware/src/SecureIngestionClient.cpp`

### Firebase backend

- [Telemetry ingestion](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/telemetry_ingestion.js): `functions/src/telemetry_ingestion.js`
- [Device authentication](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/device_auth.js): `functions/src/device_auth.js`
- [Telemetry contract](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/telemetry_contract.js): `functions/src/telemetry_contract.js`
- [Assessment pipeline](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/assessment_pipeline.js): `functions/src/assessment_pipeline.js`
- [Assessment storage](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/assessment_storage.js): `functions/src/assessment_storage.js`
- [Alerts and actions](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/alert_logic.js): `functions/src/alert_logic.js`

### Risk inference

- [Inference client](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/functions/src/inference_client.js): `functions/src/inference_client.js`
- [Risk engine](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/inference_service/app/risk_engine.py): `inference_service/app/risk_engine.py`
- [Model registry](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/inference_service/app/model_registry.py): `inference_service/app/model_registry.py`

### Assistant services

- [Assistant runtime](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/aws/assistant/runtime.js): `aws/assistant/runtime.js`
- [Safety assistant](https://github.com/hamzainayat20/smart-safety-helmet/blob/main/aws/assistant/assistant_service.js): `aws/assistant/assistant_service.js`

### Other components

- **Ingestion endpoint**
- **Groq service**

## Connections

- Motion pipeline → Fall detection: evaluates windows
- Sensor acquisition → Motion pipeline: supplies samples
- Telemetry builder → Secure uploader: encodes payload
- Secure uploader → Ingestion endpoint: posts telemetry (evidence: `firmware/src/SecureIngestionClient.cpp`)
- Ingestion endpoint → Telemetry ingestion: routes request
- Telemetry ingestion → Device authentication: authenticates device (evidence: `functions/src/telemetry_ingestion.js`)
- Telemetry ingestion → Telemetry contract: validates telemetry (evidence: `functions/src/telemetry_ingestion.js`)
- Assessment pipeline → Inference client: requests assessment (evidence: `functions/src/assessment_pipeline.js`)
- Assessment pipeline → Assessment storage: persists result (evidence: `functions/src/assessment_pipeline.js`)
- Inference client → Risk engine: requests inference
- Risk engine → Model registry: uses models (evidence: `inference_service/app/risk_engine.py`)
- Assistant runtime → Safety assistant: dispatches requests (evidence: `aws/assistant/runtime.js`)
- Assistant runtime → Groq service: calls provider
