# shravansuthar2/smart-crowd-safety architecture

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

- Interactive diagram: https://gitdiagram.com/shravansuthar2/smart-crowd-safety
- Repository: https://github.com/shravansuthar2/smart-crowd-safety

## Overview

1. **Overall shape**
   - This repository is a two-part system: a **FastAPI backend** that performs AI inference and alerting, and a **static dashboard frontend** that consumes the backend APIs.
   - A separate **training workspace** produces or fine-tunes the models used at runtime.

2. **Runtime request flow**
   - User actions in the dashboard trigger HTTP requests to the backend.
   - The backend receives image/video payloads, runs one or more detectors, stores or updates alert/person state, and returns annotated results plus metadata for display.

3. **Backend entry point and API boundary**
   - `backend/main.py` is the application entry point and API host.
   - The API is organized into routers under `backend/routers/`:
     - `detection.py` for crowd, fire, heatmap, and video processing endpoints
     - `persons.py` for missing-person registration and lookup
     - `alerts.py` for alert listing and clearing
   - This is the main boundary between external clients and internal ML/business logic.

4. **Detection subsystem**
   - `backend/modules/crowd_density.py` handles people counting and overcrowding detection using YOLOv8.
   - `backend/modules/emergency.py` handles fire/emergency detection using a custom YOLOv8 fire model.
   - `backend/modules/face_finder.py` handles missing-person search using InsightFace embeddings and similarity matching.
   - These modules are the inference layer and likely operate frame-by-frame on uploaded media.

5. **Video processing pipeline**
   - The system is designed for **real-time or batch video processing** rather than just single-image inference.
   - OpenCV is used for reading frames, running detections, and producing annotated output video.
   - The backend exposes progress/status and download endpoints for long-running video jobs, indicating asynchronous or staged processing within the server.

6. **Alerting and event state**
   - `backend/modules/alert_manager.py` centralizes alert creation, acknowledgment, resolution, and clearing.
   - Alerts are generated from detection outcomes, such as overcrowding, fire, or a matched missing person.
   - This subsystem forms the operational event layer above raw model predictions.

7. **Persistence and Firebase boundary**
   - `backend/firebase_config.py` and `dashboard/firebase-config.js` show an optional Firebase integration on both backend and frontend sides.
   - The README states the database is **Firebase Firestore optional and works locally**, so persistence is likely abstracted to allow either remote Firebase storage or local fallback behavior.
   - This is the main data persistence boundary for alerts and registered persons.

8. **Frontend/dashboard**
   - `dashboard/index.html`, `dashboard/style.css`, and `dashboard/app.js` implement a static, dark-themed UI.
   - The dashboard is not a separate application server; it is a client that talks to the backend APIs and may also use Firebase configuration for remote data access or auth-related behavior.
   - The README notes it is accessible at `/dashboard` when served by FastAPI, which means the backend also serves the static frontend.

9. **Model assets and runtime dependencies**
   - The fire model weights live in `backend/fire_model.pt` and are tracked via Git LFS because of size.
   - YOLOv8 person detection and InsightFace face models are downloaded automatically at runtime, while the fire detector is bundled with the repo.
   - This creates a split between **runtime-supplied models** and **repo-bundled custom weights**.

10. **Training subsystem**
   - `training/train_crowd_yolo.py` and `training/train_fire.py` are offline model-training scripts.
   - `training/download_dataset.py` and the included `backend/datasets/coco128/` directory provide training data support.
   - The training subsystem is separate from production inference; it exists to regenerate weights rather than serve requests.

11. **Crowd-safety domain logic**
   - The system combines three safety signals into one operational workflow: **crowd density**, **missing persons**, and **fire/emergency detection**.
   - These are not isolated features; they converge in the same alert system and video-processing pipeline, which is the core domain composition of the repo.

12. **Configuration and thresholds**
   - `backend/config.py` contains operational thresholds such as crowd density, confidence, image size, and face-similarity settings.
   - These values control detection sensitivity and directly affect when alerts are emitted, so they are part of the runtime policy layer.

13. **Deployment/container boundary**
   - The repo includes a `Dockerfile` and a Hugging Face Space-style README header indicating containerized deployment.
   - The documented deployment path is a single backend service serving APIs and the dashboard, with optional Firebase and model artifacts bundled or downloaded at startup.

14. **What an architecture diagram should emphasize**
   - Show the dashboard as the client surface.
   - Show FastAPI as the central orchestrator.
   - Show three ML inference modules feeding a shared alert manager.
   - Show persistence as optional Firebase/local storage for persons and alerts.
   - Show training as a separate offline lane that outputs model artifacts into the backend runtime.

Main entry points: [`backend/routers/detection.py`](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/detection.py) (Detection API), [`dashboard/app.js`](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/app.js) (Dashboard app), [`backend/main.py`](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/main.py) (FastAPI app), [`backend/routers/persons.py`](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/persons.py) (Persons API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>api host<br/>[main.py]"]
  node_router_detection["Detection API<br/>router<br/>[detection.py]"]
  node_router_persons["Persons API<br/>router<br/>[persons.py]"]
  node_router_alerts["Alerts API<br/>router<br/>[alerts.py]"]
  node_crowd_density{{"Crowd density<br/>inference module<br/>[crowd_density.py]"}}
  node_emergency{{"Fire detect<br/>inference module<br/>[emergency.py]"}}
  node_face_finder{{"Face finder<br/>matching module<br/>[face_finder.py]"}}
  node_pickpocket{{"Pickpocket<br/>aux detector<br/>[pickpocket.py]"}}
  node_alert_manager[("Alert manager<br/>event state<br/>[alert_manager.py]")]
  node_schemas["Schemas<br/>data contracts<br/>[schemas.py]"]
  node_config["Config<br/>[config.py]"]
  node_firebase_config["Firebase config<br/>persistence boundary<br/>[firebase_config.py]"]
  node_fire_module{{"Fire module<br/>custom model stack<br/>[fire_detection.py]"}}
  node_fire_model[("Fire weights<br/>model artifact<br/>[fire_model.pt]")]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard UI<br/>static client<br/>[index.html]"]
  node_dashboard_app["Dashboard app<br/>client logic<br/>[app.js]"]
  node_dashboard_firebase["Firebase client<br/>client config<br/>[firebase-config.js]"]
end

subgraph group_training["Training"]
  node_train_crowd["Crowd train<br/>training script"]
  node_train_fire["Fire train<br/>training script<br/>[train_fire.py]"]
  node_dataset_prep["Dataset prep<br/>training data"]
end

node_firebase_service[("Firebase<br/>external service")]

node_backend_main -->|"mounts"| node_router_detection
node_backend_main -->|"mounts"| node_router_persons
node_backend_main -->|"mounts"| node_router_alerts
node_backend_main -->|"serves"| node_dashboard_ui
node_dashboard_ui -->|"loads"| node_dashboard_app
node_dashboard_app -->|"calls"| node_router_detection
node_dashboard_app -->|"calls"| node_router_persons
node_dashboard_app -->|"calls"| node_router_alerts
node_dashboard_app -->|"uses"| node_dashboard_firebase
node_router_detection -->|"runs"| node_crowd_density
node_router_detection -->|"runs"| node_emergency
node_router_detection -->|"runs"| node_face_finder
node_router_detection -->|"runs"| node_pickpocket
node_router_detection -->|"uses"| node_schemas
node_router_persons -->|"uses"| node_face_finder
node_router_persons -->|"persists"| node_firebase_config
node_router_alerts -->|"uses"| node_alert_manager
node_crowd_density -->|"reads"| node_config
node_emergency -->|"reads"| node_config
node_face_finder -->|"reads"| node_config
node_alert_manager -->|"stores"| node_firebase_config
node_firebase_config -->|"connects"| node_firebase_service
node_dashboard_firebase -->|"connects"| node_firebase_service
node_fire_module -->|"loads"| node_fire_model
node_fire_module -->|"implements"| node_emergency
node_train_crowd -->|"produces"| node_crowd_density
node_train_fire -->|"produces"| node_fire_module
node_dataset_prep -->|"feeds"| node_train_crowd
node_dataset_prep -->|"feeds"| node_train_fire

click node_backend_main "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/main.py"
click node_router_detection "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/detection.py"
click node_router_persons "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/persons.py"
click node_router_alerts "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/alerts.py"
click node_crowd_density "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/crowd_density.py"
click node_emergency "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/emergency.py"
click node_face_finder "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/face_finder.py"
click node_pickpocket "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/pickpocket.py"
click node_alert_manager "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/alert_manager.py"
click node_schemas "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/models/schemas.py"
click node_config "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/config.py"
click node_firebase_config "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/firebase_config.py"
click node_fire_module "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/fire_module/fire_detection.py"
click node_fire_model "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/fire_model.pt"
click node_dashboard_ui "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/index.html"
click node_dashboard_app "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/app.js"
click node_dashboard_firebase "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/firebase-config.js"
click node_train_crowd "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/training/train_crowd_yolo.py"
click node_train_fire "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/training/train_fire.py"
click node_dataset_prep "https://github.com/shravansuthar2/smart-crowd-safety/blob/main/training/download_dataset.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_backend_main,node_router_detection,node_router_persons,node_router_alerts,node_crowd_density,node_emergency,node_face_finder,node_pickpocket,node_alert_manager,node_schemas,node_config,node_firebase_config,node_fire_module,node_fire_model toneBlue
class node_dashboard_ui,node_dashboard_app,node_dashboard_firebase toneAmber
class node_train_crowd,node_train_fire,node_dataset_prep toneMint
class node_firebase_service toneNeutral
```

## Components

### Backend

FastAPI server, routers, inference modules, and runtime config.

- [FastAPI app](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/main.py): api host · Application entry point and server for APIs and static dashboard assets. · `backend/main.py`
- [Detection API](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/detection.py): router · Endpoints for crowd, fire, heatmap, and video processing. · `backend/routers/detection.py`
- [Persons API](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/persons.py): router · Endpoints for missing-person registration and lookup. · `backend/routers/persons.py`
- [Alerts API](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/routers/alerts.py): router · Endpoints for listing, acknowledging, and clearing alerts. · `backend/routers/alerts.py`
- [Crowd density](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/crowd_density.py): inference module · People counting and overcrowding detection using YOLOv8. · `backend/modules/crowd_density.py`
- [Fire detect](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/emergency.py): inference module · Fire and emergency detection using the bundled custom model. · `backend/modules/emergency.py`
- [Face finder](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/face_finder.py): matching module · Missing-person search using embeddings and similarity matching. · `backend/modules/face_finder.py`
- [Pickpocket](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/pickpocket.py): aux detector · Additional safety detector for suspicious activity. · `backend/modules/pickpocket.py`
- [Alert manager](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/modules/alert_manager.py): event state · Centralizes alert creation, acknowledgement, resolution, and clearing. · `backend/modules/alert_manager.py`
- [Schemas](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/models/schemas.py): data contracts · Shared request and response models for API and runtime data. · `backend/models/schemas.py`
- [Config](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/config.py): policy config · Runtime thresholds and sensitivity settings that control detection behavior. · `backend/config.py`
- [Firebase config](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/firebase_config.py): persistence boundary · Backend-side Firebase/Firestore integration and local fallback boundary. · `backend/firebase_config.py`
- [Fire module](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/fire_module/fire_detection.py): custom model stack · Bundled fire-model loading and detection implementation used at runtime. · `backend/fire_module/fire_detection.py`
- [Fire weights](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/backend/fire_model.pt): model artifact · Custom fire detector weights bundled with the repository. · `backend/fire_model.pt`

### Dashboard

Static client served by the backend.

- [Dashboard UI](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/index.html): static client · Dark-themed dashboard shell and controls for operators. · `dashboard/index.html`
- [Dashboard app](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/app.js): client logic · Frontend logic that calls backend APIs and renders results. · `dashboard/app.js`
- [Firebase client](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/dashboard/firebase-config.js): client config · Frontend-side Firebase configuration for optional remote persistence. · `dashboard/firebase-config.js`

### Training

Offline model-training and dataset preparation lane.

- [Crowd train](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/training/train_crowd_yolo.py): training script · Offline training script for the crowd-density detector. · `training/train_crowd_yolo.py`
- [Fire train](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/training/train_fire.py): training script · Offline training script for the fire detector. · `training/train_fire.py`
- [Dataset prep](https://github.com/shravansuthar2/smart-crowd-safety/blob/main/training/download_dataset.py): training data · Dataset download and preparation support for model training. · `training/download_dataset.py`

### Other components

- **Firebase**: external service · Optional Firestore persistence used by backend and dashboard.

## Connections

- FastAPI app → Detection API: mounts · Registers detection routes.
- FastAPI app → Persons API: mounts · Registers person-management routes.
- FastAPI app → Alerts API: mounts · Registers alert routes.
- FastAPI app → Dashboard UI: serves · Hosts the static dashboard.
- Dashboard UI → Dashboard app: loads · Browser loads client logic.
- Dashboard app → Detection API: calls · Sends media and detection requests.
- Dashboard app → Persons API: calls · Submits person registration and lookup requests.
- Dashboard app → Alerts API: calls · Fetches and clears alert state.
- Dashboard app → Firebase client: uses · Optional frontend Firebase integration.
- Detection API → Crowd density: runs · Crowd and overcrowding inference.
- Detection API → Fire detect: runs · Fire/emergency inference.
- Detection API → Face finder: runs · Missing-person image matching.
- Detection API → Pickpocket: runs · Additional safety detection path.
- Detection API → Schemas: uses · Request and response payloads.
- Persons API → Face finder: uses · Registers and searches faces.
- Persons API → Firebase config: persists · Stores registered-person data when enabled.
- Alerts API → Alert manager: uses · Queries and mutates alert state.
- Crowd density → Config: reads · Uses crowd thresholds and sensitivity settings.
- Fire detect → Config: reads · Uses runtime confidence and image settings.
- Face finder → Config: reads · Uses face-similarity thresholds.
- Alert manager → Firebase config: stores · Writes alert state through the persistence boundary.
- Firebase config → Firebase: connects · Optional Firestore backend.
- Firebase client → Firebase: connects · Optional client-side Firebase access.
- Fire module → Fire weights: loads · Uses bundled fire weights at runtime.
- Fire module → Fire detect: implements · Backend emergency detection wraps the custom fire stack.
- Crowd train → Crowd density: produces · Retrains the crowd detector used in runtime.
- Fire train → Fire module: produces · Trains the custom fire detector stack.
- Dataset prep → Crowd train: feeds · Provides dataset setup for training.
- Dataset prep → Fire train: feeds · Provides dataset setup for training.