# abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system architecture

> Architecture diagram of the GitHub repository abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system
- Repository: https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system

## Overview

CrowdSafe accepts citizen crowd reports or media, estimates headcount and density, analyzes trends and hazard risk, persists reports and telemetry, and alerts responders when risk is high. Authorities monitor zones and alerts, acknowledge incidents, and issue manual dispatches; analytics and heatmaps provide the documented historical and spatial views. The graph combines sampled route/service behavior with README-documented frontend and analytics capabilities; those unsampled links are shown only where the product workflow is explicit. Details of analytics and auxiliary services are not verified from source excerpts.

Main entry points: [`backend/app/routes/report_routes.py`](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/report_routes.py) (Report routes), [`frontend/src/App.jsx`](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/App.jsx) (Web application), [`backend/app/database.py`](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/database.py) (CrowdSafe database), [`frontend/src/pages/AuthorityDashboard.jsx`](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/AuthorityDashboard.jsx) (Authority dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_citizen_upload["Citizen upload<br/>[CitizenUpload.jsx]"]
  node_authority_ui["Authority dashboard"]
  node_analytics_ui["Analytics view<br/>[Analytics.jsx]"]
  node_heatmap["Heatmap view<br/>[HeatmapView.jsx]"]
  node_alerts_ui["Alert banner<br/>[AlertBanner.jsx]"]
end

subgraph group_api["Backend API"]
  node_auth_api["Authentication routes<br/>[auth_routes.py]"]
  node_reports_api["Report routes<br/>[report_routes.py]"]
  node_authority_api["Authority routes"]
  node_analytics_api["Analytics routes"]
end

subgraph group_analysis["Crowd analysis"]
  node_frames["Frame extraction<br/>[frame_extractor.py]"]
  node_counter["Crowd counter<br/>[crowd_counter.py]"]
  node_trends["Trend analysis<br/>[trend_analyzer.py]"]
  node_risk["Risk classification<br/>[risk_classifier.py]"]
  node_heatmap_gen["Heatmap generation"]
  node_geo["Zone matching<br/>[geo_matcher.py]"]
  node_queue["Background task queue<br/>[task_queue.py]"]
end

subgraph group_state["Persistence"]
  node_database[("CrowdSafe database<br/>[database.py]")]
end

subgraph group_response["Alerts and operations"]
  node_rate_limit["Alert cooldown<br/>[rate_limiter.py]"]
  node_notifier["Notification dispatch<br/>[notifier.py]"]
end

node_citizens(("Citizens"))
node_authorities(("Authorities"))
node_postgres[("PostgreSQL")]
node_responders(("Emergency responders"))

node_citizens -->|"use"| node_webapp
node_authorities -->|"use"| node_webapp
node_webapp -->|"offers reporting"| node_citizen_upload
node_webapp -->|"offers monitoring"| node_authority_ui
node_webapp -->|"offers analytics"| node_analytics_ui
node_citizen_upload -->|"submits reports"| node_reports_api
node_authority_ui -->|"fetches and dispatches"| node_authority_api
node_authority_ui -->|"shows alerts"| node_alerts_ui
node_authority_ui -->|"shows zones"| node_heatmap
node_analytics_ui -->|"requests trends"| node_analytics_api
node_auth_api -->|"reads and writes"| node_database
node_reports_api -->|"reads and writes"| node_database
node_authority_api -->|"reads and writes"| node_database
node_analytics_api -->|"reads"| node_database
node_database -->|"queries"| node_postgres
node_reports_api -->|"extracts video frame"| node_frames
node_reports_api -->|"estimates crowd"| node_counter
node_frames -->|"provides frames"| node_counter
node_reports_api -->|"records and analyzes"| node_trends
node_reports_api -->|"classifies hazard"| node_risk
node_reports_api -->|"checks cooldown"| node_rate_limit
node_reports_api -->|"dispatches alert"| node_notifier
node_notifier -->|"sends notification"| node_responders

click node_webapp "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/App.jsx"
click node_citizen_upload "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/CitizenUpload.jsx"
click node_authority_ui "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/AuthorityDashboard.jsx"
click node_analytics_ui "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/Analytics.jsx"
click node_heatmap "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/components/HeatmapView.jsx"
click node_alerts_ui "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/components/AlertBanner.jsx"
click node_auth_api "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/auth_routes.py"
click node_reports_api "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/report_routes.py"
click node_authority_api "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/authority_routes.py"
click node_analytics_api "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/analytics_routes.py"
click node_frames "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/frame_extractor.py"
click node_counter "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/crowd_counter.py"
click node_trends "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/trend_analyzer.py"
click node_risk "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/risk_classifier.py"
click node_heatmap_gen "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/heatmap_generator.py"
click node_geo "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/geo_matcher.py"
click node_queue "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/task_queue.py"
click node_rate_limit "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/rate_limiter.py"
click node_notifier "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/notifier.py"
click node_database "https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/database.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_webapp,node_citizen_upload,node_authority_ui,node_analytics_ui,node_heatmap,node_alerts_ui toneBlue
class node_auth_api,node_reports_api,node_authority_api,node_analytics_api,node_postgres toneAmber
class node_frames,node_counter,node_trends,node_risk,node_heatmap_gen,node_geo,node_queue toneMint
class node_database toneRose
class node_rate_limit,node_notifier,node_citizens,node_authorities,node_responders toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Citizen upload](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/CitizenUpload.jsx): `frontend/src/pages/CitizenUpload.jsx`
- [Authority dashboard](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/AuthorityDashboard.jsx): `frontend/src/pages/AuthorityDashboard.jsx`
- [Analytics view](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/pages/Analytics.jsx): `frontend/src/pages/Analytics.jsx`
- [Heatmap view](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/components/HeatmapView.jsx): `frontend/src/components/HeatmapView.jsx`
- [Alert banner](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/frontend/src/components/AlertBanner.jsx): `frontend/src/components/AlertBanner.jsx`

### Backend API

- [Authentication routes](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/auth_routes.py): `backend/app/routes/auth_routes.py`
- [Report routes](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/report_routes.py): `backend/app/routes/report_routes.py`
- [Authority routes](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/authority_routes.py): `backend/app/routes/authority_routes.py`
- [Analytics routes](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/routes/analytics_routes.py): `backend/app/routes/analytics_routes.py`

### Crowd analysis

- [Frame extraction](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/frame_extractor.py): `backend/app/services/frame_extractor.py`
- [Crowd counter](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/crowd_counter.py): `backend/app/services/crowd_counter.py`
- [Trend analysis](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/trend_analyzer.py): `backend/app/services/trend_analyzer.py`
- [Risk classification](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/risk_classifier.py): `backend/app/services/risk_classifier.py`
- [Heatmap generation](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/heatmap_generator.py): `backend/app/services/heatmap_generator.py`
- [Zone matching](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/geo_matcher.py): `backend/app/services/geo_matcher.py`
- [Background task queue](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/task_queue.py): `backend/app/services/task_queue.py`

### Persistence

- [CrowdSafe database](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/database.py): `backend/app/database.py`

### Alerts and operations

- [Alert cooldown](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/rate_limiter.py): `backend/app/services/rate_limiter.py`
- [Notification dispatch](https://github.com/abhijith-cel/crowdsafe-ai-based-stampede-risk-reporting-system/blob/main/backend/app/services/notifier.py): `backend/app/services/notifier.py`

### Other components

- **Citizens**
- **Authorities**
- **PostgreSQL**
- **Emergency responders**

## Connections

- Citizens → Web application: use
- Authorities → Web application: use
- Web application → Citizen upload: offers reporting
- Web application → Authority dashboard: offers monitoring
- Web application → Analytics view: offers analytics
- Citizen upload → Report routes: submits reports
- Authority dashboard → Authority routes: fetches and dispatches
- Authority dashboard → Alert banner: shows alerts
- Authority dashboard → Heatmap view: shows zones
- Analytics view → Analytics routes: requests trends
- Authentication routes → CrowdSafe database: reads and writes
- Report routes → CrowdSafe database: reads and writes
- Authority routes → CrowdSafe database: reads and writes
- Analytics routes → CrowdSafe database: reads
- CrowdSafe database → PostgreSQL: queries
- Report routes → Frame extraction: extracts video frame
- Report routes → Crowd counter: estimates crowd
- Frame extraction → Crowd counter: provides frames
- Report routes → Trend analysis: records and analyzes
- Report routes → Risk classification: classifies hazard
- Report routes → Alert cooldown: checks cooldown
- Report routes → Notification dispatch: dispatches alert
- Notification dispatch → Emergency responders: sends notification