# 3bdelmoemn/fire-smoke-detection-engine architecture

> Architecture diagram of the GitHub repository 3bdelmoemn/fire-smoke-detection-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/3bdelmoemn/fire-smoke-detection-engine
- Repository: https://github.com/3bdelmoemn/fire-smoke-detection-engine

## Overview

FireGuard AI combines a React operator dashboard with a FastAPI fire/smoke detection backend. The principal workflow is live-camera or uploaded-media capture, YOLO inference, temporal confirmation and cooldown-based alerting, with event and alert records available to dashboard users. Authentication, health/KPI reporting, and evaluation assets are additional product capabilities. Relationships are grounded in the README and supplied excerpts or SOURCE INDEX references; unsampled implementation details and some frontend-to-route wiring are not inferred.

Main entry points: [`backend/app/main.py`](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/api/v1/detection_realtime.py`](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/detection_realtime.py) (Realtime Routes), [`frontend/src/App.jsx`](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/App.jsx) (Dashboard App), [`frontend/src/services/api.js`](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/services/api.js) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Operator Dashboard"]
  node_app["Dashboard App<br/>[App.jsx]"]
  node_login["Login Page<br/>[Login.jsx]"]
  node_dashboard["Live Dashboard<br/>[Dashboard.jsx]"]
  node_upload["Upload Analysis<br/>[Upload.jsx]"]
  node_evaluation["Evaluation Gallery<br/>[Evaluation.jsx]"]
  node_alertsui["Alert History<br/>[Alerts.jsx]"]
  node_clientapi["API Client<br/>[api.js]"]
end

subgraph group_api["API and Access"]
  node_server["FastAPI App<br/>[main.py]"]
  node_authroute["Auth Routes<br/>[auth.py]"]
  node_realtime["Realtime Routes"]
  node_uploadroute["Upload Routes"]
  node_evalroute["Evaluation Routes<br/>[evaluation.py]"]
  node_alertroute["Alert Routes<br/>[alerts.py]"]
  node_healthroute["Health Routes<br/>[health.py]"]
  node_authservice["Auth Service<br/>[auth_service.py]"]
end

subgraph group_detection["Detection and Alerts"]
  node_inference["YOLO Inference"]
  node_model["Model Loader<br/>[model_loader.py]"]
  node_camera_service["Camera Service<br/>[camera_service.py]"]
  node_media["Media Service<br/>[media_service.py]"]
  node_decision["Alert Decision"]
  node_temporal["Temporal Validator"]
  node_notify["Notifications"]
end

subgraph group_data["Persistence and Model"]
  node_database[("Application Database<br/>[session.py]")]
  node_detections["Detection Repository"]
  node_alerts["Alert Repository"]
  node_users["User Repository<br/>[user_repository.py]"]
  node_config["Application Settings<br/>[config.py]"]
end

node_operator(("Operator"))
node_camera(("Camera / Media"))

node_operator -->|"uses"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_upload
node_app -->|"routes to"| node_evaluation
node_app -->|"routes to"| node_alertsui
node_login -->|"calls"| node_clientapi
node_dashboard -->|"calls"| node_clientapi
node_upload -->|"calls"| node_clientapi
node_evaluation -->|"calls"| node_clientapi
node_alertsui -->|"calls"| node_clientapi
node_clientapi -->|"REST / WebSocket"| node_server
node_server -->|"registers"| node_authroute
node_server -->|"registers"| node_realtime
node_server -->|"registers"| node_uploadroute
node_server -->|"registers"| node_evalroute
node_server -->|"registers"| node_alertroute
node_server -->|"registers"| node_healthroute
node_authroute -->|"calls"| node_authservice
node_camera -->|"supplies frames"| node_realtime
node_realtime -->|"uses"| node_camera_service
node_realtime -->|"requests inference"| node_inference
node_uploadroute -->|"requests inference"| node_inference
node_camera_service -.->|"provides frames"| node_inference
node_realtime -->|"evaluates detections"| node_decision
node_decision -->|"validates over time"| node_temporal
node_decision -->|"dispatches alerts"| node_notify
node_realtime -->|"uses"| node_notify
node_uploadroute -->|"uses"| node_media
node_realtime -->|"uses"| node_media
node_server -->|"preloads"| node_model
node_inference -.->|"uses model"| node_model
node_realtime -->|"persists events"| node_detections
node_uploadroute -->|"persists events"| node_detections
node_realtime -->|"persists alerts"| node_alerts
node_alertroute -->|"queries alerts"| node_alerts
node_healthroute -->|"reads KPIs"| node_detections
node_healthroute -->|"checks alerts"| node_alerts
node_authservice -.->|"uses user model"| node_users
node_detections -.->|"reads / writes"| node_database
node_alerts -.->|"reads / writes"| node_database
node_server -->|"initializes"| node_database
node_server -->|"loads settings"| node_config
node_realtime -->|"uses settings"| node_config
node_uploadroute -->|"uses settings"| node_config
node_notify -.->|"WhatsApp alert"| node_operator

click node_app "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Login.jsx"
click node_dashboard "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Dashboard.jsx"
click node_upload "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Upload.jsx"
click node_evaluation "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Evaluation.jsx"
click node_alertsui "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Alerts.jsx"
click node_clientapi "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/main.py"
click node_authroute "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/auth.py"
click node_realtime "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/detection_realtime.py"
click node_uploadroute "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/detection_upload.py"
click node_evalroute "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/evaluation.py"
click node_alertroute "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/alerts.py"
click node_healthroute "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/health.py"
click node_authservice "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/auth_service.py"
click node_inference "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/inference_service.py"
click node_model "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/ml/model_loader.py"
click node_camera_service "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/camera_service.py"
click node_media "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/media_service.py"
click node_decision "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/alert_decision_engine.py"
click node_temporal "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/temporal_validator.py"
click node_notify "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/notification_service.py"
click node_database "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/db/session.py"
click node_detections "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/repositories/detection_repository.py"
click node_alerts "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/repositories/alert_repository.py"
click node_users "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/repositories/user_repository.py"
click node_config "https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/core/config.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_login,node_dashboard,node_upload,node_evaluation,node_alertsui,node_clientapi toneBlue
class node_server,node_authroute,node_realtime,node_uploadroute,node_evalroute,node_alertroute,node_healthroute,node_authservice toneAmber
class node_inference,node_model,node_camera_service,node_media,node_decision,node_temporal,node_notify toneMint
class node_database,node_detections,node_alerts,node_users,node_config toneRose
class node_operator,node_camera toneIndigo
```

## Components

### Operator Dashboard

- [Dashboard App](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login Page](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Live Dashboard](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Upload Analysis](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Upload.jsx): `frontend/src/pages/Upload.jsx`
- [Evaluation Gallery](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Evaluation.jsx): `frontend/src/pages/Evaluation.jsx`
- [Alert History](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/pages/Alerts.jsx): `frontend/src/pages/Alerts.jsx`
- [API Client](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and Access

- [FastAPI App](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth Routes](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Realtime Routes](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/detection_realtime.py): `backend/app/api/v1/detection_realtime.py`
- [Upload Routes](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/detection_upload.py): `backend/app/api/v1/detection_upload.py`
- [Evaluation Routes](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/evaluation.py): `backend/app/api/v1/evaluation.py`
- [Alert Routes](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/alerts.py): `backend/app/api/v1/alerts.py`
- [Health Routes](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/api/v1/health.py): `backend/app/api/v1/health.py`
- [Auth Service](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### Detection and Alerts

- [YOLO Inference](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/inference_service.py): `backend/app/services/inference_service.py`
- [Model Loader](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/ml/model_loader.py): `backend/app/ml/model_loader.py`
- [Camera Service](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/camera_service.py): `backend/app/services/camera_service.py`
- [Media Service](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/media_service.py): `backend/app/services/media_service.py`
- [Alert Decision](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/alert_decision_engine.py): `backend/app/services/alert_decision_engine.py`
- [Temporal Validator](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/temporal_validator.py): `backend/app/services/temporal_validator.py`
- [Notifications](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`

### Persistence and Model

- [Application Database](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Detection Repository](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/repositories/detection_repository.py): `backend/app/repositories/detection_repository.py`
- [Alert Repository](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/repositories/alert_repository.py): `backend/app/repositories/alert_repository.py`
- [User Repository](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/repositories/user_repository.py): `backend/app/repositories/user_repository.py`
- [Application Settings](https://github.com/3bdelmoemn/fire-smoke-detection-engine/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Operator**
- **Camera / Media**

## Connections

- Operator → Dashboard App: uses (evidence: `README.md`)
- Dashboard App → Login Page: routes to (evidence: `frontend/src/App.jsx`)
- Dashboard App → Live Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Dashboard App → Upload Analysis: routes to (evidence: `frontend/src/App.jsx`)
- Dashboard App → Evaluation Gallery: routes to (evidence: `frontend/src/App.jsx`)
- Dashboard App → Alert History: routes to (evidence: `frontend/src/App.jsx`)
- Login Page → API Client: calls (evidence: `frontend/src/pages/Login.jsx`)
- Live Dashboard → API Client: calls (evidence: `frontend/src/pages/Dashboard.jsx`)
- Upload Analysis → API Client: calls (evidence: `frontend/src/pages/Upload.jsx`)
- Evaluation Gallery → API Client: calls (evidence: `frontend/src/pages/Evaluation.jsx`)
- Alert History → API Client: calls (evidence: `frontend/src/pages/Alerts.jsx`)
- API Client → FastAPI App: REST / WebSocket (evidence: `README.md`)
- FastAPI App → Auth Routes: registers (evidence: `backend/app/main.py`)
- FastAPI App → Realtime Routes: registers (evidence: `backend/app/main.py`)
- FastAPI App → Upload Routes: registers (evidence: `backend/app/main.py`)
- FastAPI App → Evaluation Routes: registers (evidence: `backend/app/main.py`)
- FastAPI App → Alert Routes: registers (evidence: `backend/app/main.py`)
- FastAPI App → Health Routes: registers (evidence: `backend/app/main.py`)
- Auth Routes → Auth Service: calls (evidence: `backend/app/api/v1/auth.py`)
- Camera / Media → Realtime Routes: supplies frames (evidence: `README.md`)
- Realtime Routes → Camera Service: uses (evidence: `backend/app/api/v1/detection_realtime.py`)
- Realtime Routes → YOLO Inference: requests inference (evidence: `backend/app/api/v1/detection_realtime.py`)
- Upload Routes → YOLO Inference: requests inference (evidence: `backend/app/api/v1/detection_upload.py`)
- Camera Service → YOLO Inference: provides frames
- Realtime Routes → Alert Decision: evaluates detections (evidence: `backend/app/api/v1/detection_realtime.py`)
- Alert Decision → Temporal Validator: validates over time (evidence: `README.md`)
- Alert Decision → Notifications: dispatches alerts (evidence: `README.md`)
- Realtime Routes → Notifications: uses (evidence: `backend/app/api/v1/detection_realtime.py`)
- Upload Routes → Media Service: uses (evidence: `backend/app/api/v1/detection_upload.py`)
- Realtime Routes → Media Service: uses (evidence: `backend/app/api/v1/detection_realtime.py`)
- FastAPI App → Model Loader: preloads (evidence: `backend/app/main.py`)
- YOLO Inference → Model Loader: uses model
- Realtime Routes → Detection Repository: persists events (evidence: `backend/app/api/v1/detection_realtime.py`)
- Upload Routes → Detection Repository: persists events (evidence: `backend/app/api/v1/detection_upload.py`)
- Realtime Routes → Alert Repository: persists alerts (evidence: `backend/app/api/v1/detection_realtime.py`)
- Alert Routes → Alert Repository: queries alerts (evidence: `backend/app/api/v1/alerts.py`)
- Health Routes → Detection Repository: reads KPIs (evidence: `backend/app/api/v1/health.py`)
- Health Routes → Alert Repository: checks alerts (evidence: `backend/app/api/v1/health.py`)
- Auth Service → User Repository: uses user model
- Detection Repository → Application Database: reads / writes
- Alert Repository → Application Database: reads / writes
- FastAPI App → Application Database: initializes (evidence: `backend/app/main.py`)
- FastAPI App → Application Settings: loads settings (evidence: `backend/app/main.py`)
- Realtime Routes → Application Settings: uses settings (evidence: `backend/app/api/v1/detection_realtime.py`)
- Upload Routes → Application Settings: uses settings (evidence: `backend/app/api/v1/detection_upload.py`)
- Notifications → Operator: WhatsApp alert (evidence: `README.md`)
