# sai8143/safenex architecture

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

- Interactive diagram: https://gitdiagram.com/sai8143/safenex
- Repository: https://github.com/sai8143/safenex

## Overview

SafeNex detects road collisions from uploaded images or continuous CCTV streams, confirms incidents, stores evidence and accident records, then dispatches location-aware alerts to emergency departments. The mobile app provides a camera/GPS reporting flow plus department and history interfaces. The graph follows the documented workflow and relationships visible in the supplied excerpts and SOURCE INDEX; portal page files and several service implementations were not included in the file tree or sampled source.

Main entry points: [`backend/app/main.py`](https://github.com/sai8143/safenex/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/services/rtsp_stream.py`](https://github.com/sai8143/safenex/blob/main/backend/app/services/rtsp_stream.py) (RTSP stream worker), [`backend/app/services/video_detector.py`](https://github.com/sai8143/safenex/blob/main/backend/app/services/video_detector.py) (Stream frame pipeline), [`mobile-app/src/services/api.js`](https://github.com/sai8143/safenex/blob/main/mobile-app/src/services/api.js) (Mobile API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile reporting"]
  node_mobile_app["Mobile tabs<br/>[App.js]"]
  node_camera_screen["Camera and GPS<br/>[CameraScreen.js]"]
  node_mobile_api["Mobile API client<br/>[api.js]"]
  node_app_config["Backend URL config<br/>[config.js]"]
  node_impact["Impact trigger<br/>[impactDetector.js]"]
  node_dept_screens["Department portals"]
  node_history_screen["Accident history<br/>[HistoryScreen.js]"]
  node_settings_screen["Connection settings<br/>[SettingsScreen.js]"]
end

subgraph group_ingest["Detection and ingest"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_stream_worker["RTSP stream worker<br/>[rtsp_stream.py]"]
end

subgraph group_analysis["Incident analysis"]
  node_video_pipeline["Stream frame pipeline<br/>[video_detector.py]"]
  node_vehicle_detector["Vehicle and damage detection<br/>[ai_detector.py]"]
  node_tracker["Vehicle tracking<br/>[tracker.py]"]
  node_temporal["Temporal verification<br/>[temporal_filter.py]"]
  node_decision["Accident decision and severity<br/>[decision_engine.py]"]
end

subgraph group_dispatch["Persistence and response"]
  node_notifier["Emergency alert builder<br/>[notifier.py]"]
  node_location["Facility distance and ETA<br/>[location.py]"]
  node_websocket["WebSocket broadcaster"]
  node_database[("Accident database<br/>[database.py]")]
  node_records["Accident records<br/>[models.py]"]
end

node_mobile_user(("Camera operator"))
node_cctv(("CCTV / webcam"))
node_responders(("Hospital / police / EMS"))
node_surveillance["Surveillance dashboard<br/>[main.py]"]

node_mobile_user -->|"uses"| node_mobile_app
node_mobile_app -->|"shows"| node_camera_screen
node_mobile_app -->|"shows"| node_dept_screens
node_mobile_app -->|"shows"| node_settings_screen
node_camera_screen -->|"sends image"| node_mobile_api
node_camera_screen -->|"uses"| node_impact
node_mobile_api -->|"gets endpoint"| node_app_config
node_mobile_api -->|"posts alert"| node_api
node_dept_screens -->|"uses"| node_mobile_api
node_history_screen -->|"uses"| node_mobile_api
node_settings_screen -->|"uses"| node_mobile_api
node_cctv -->|"provides frames"| node_stream_worker
node_cctv -->|"uploads frames"| node_api
node_api -->|"analyzes image"| node_vehicle_detector
node_api -->|"analyzes frame"| node_video_pipeline
node_api -->|"starts stream"| node_stream_worker
node_stream_worker -->|"processes frames"| node_video_pipeline
node_stream_worker -->|"analyzes evidence"| node_vehicle_detector
node_video_pipeline -->|"detects vehicles"| node_vehicle_detector
node_video_pipeline -->|"tracks vehicles"| node_tracker
node_video_pipeline -->|"verifies persistence"| node_temporal
node_video_pipeline -->|"evaluates incident"| node_decision
node_vehicle_detector -->|"classifies evidence"| node_decision
node_api -->|"uses sessions"| node_database
node_api -->|"reads and writes"| node_records
node_stream_worker -->|"persists incident"| node_database
node_stream_worker -->|"creates record"| node_records
node_api -->|"dispatches confirmed"| node_notifier
node_stream_worker -->|"notifies on confirmation"| node_notifier
node_notifier -->|"calculates facilities"| node_location
node_notifier -->|"broadcasts alerts"| node_websocket
node_websocket -->|"pushes alerts"| node_responders
node_api -->|"serves dashboard"| node_surveillance
node_surveillance -->|"receives live alerts"| node_websocket
node_notifier -->|"dispatches response"| node_responders
node_api -->|"lists history"| node_records
node_api -->|"routes socket clients"| node_websocket

click node_mobile_app "https://github.com/sai8143/safenex/blob/main/mobile-app/App.js"
click node_camera_screen "https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/CameraScreen.js"
click node_mobile_api "https://github.com/sai8143/safenex/blob/main/mobile-app/src/services/api.js"
click node_app_config "https://github.com/sai8143/safenex/blob/main/mobile-app/src/config.js"
click node_impact "https://github.com/sai8143/safenex/blob/main/mobile-app/src/utils/impactDetector.js"
click node_dept_screens "https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/DepartmentScreens.js"
click node_history_screen "https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/HistoryScreen.js"
click node_settings_screen "https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/SettingsScreen.js"
click node_api "https://github.com/sai8143/safenex/blob/main/backend/app/main.py"
click node_stream_worker "https://github.com/sai8143/safenex/blob/main/backend/app/services/rtsp_stream.py"
click node_video_pipeline "https://github.com/sai8143/safenex/blob/main/backend/app/services/video_detector.py"
click node_vehicle_detector "https://github.com/sai8143/safenex/blob/main/backend/app/services/ai_detector.py"
click node_tracker "https://github.com/sai8143/safenex/blob/main/backend/app/services/tracker.py"
click node_temporal "https://github.com/sai8143/safenex/blob/main/backend/app/services/temporal_filter.py"
click node_decision "https://github.com/sai8143/safenex/blob/main/backend/app/services/decision_engine.py"
click node_notifier "https://github.com/sai8143/safenex/blob/main/backend/app/services/notifier.py"
click node_location "https://github.com/sai8143/safenex/blob/main/backend/app/services/location.py"
click node_websocket "https://github.com/sai8143/safenex/blob/main/backend/app/services/websocket_manager.py"
click node_database "https://github.com/sai8143/safenex/blob/main/backend/app/database.py"
click node_records "https://github.com/sai8143/safenex/blob/main/backend/app/models.py"
click node_surveillance "https://github.com/sai8143/safenex/blob/main/backend/app/main.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_mobile_app,node_camera_screen,node_mobile_api,node_app_config,node_impact,node_dept_screens,node_history_screen,node_settings_screen toneBlue
class node_api,node_stream_worker toneAmber
class node_video_pipeline,node_vehicle_detector,node_tracker,node_temporal,node_decision toneMint
class node_notifier,node_location,node_websocket,node_database,node_records toneRose
class node_mobile_user,node_cctv,node_responders toneIndigo
class node_surveillance toneTeal
```

## Components

### Mobile reporting

- [Mobile tabs](https://github.com/sai8143/safenex/blob/main/mobile-app/App.js): `mobile-app/App.js`
- [Camera and GPS](https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/CameraScreen.js): `mobile-app/src/screens/CameraScreen.js`
- [Mobile API client](https://github.com/sai8143/safenex/blob/main/mobile-app/src/services/api.js): `mobile-app/src/services/api.js`
- [Backend URL config](https://github.com/sai8143/safenex/blob/main/mobile-app/src/config.js): `mobile-app/src/config.js`
- [Impact trigger](https://github.com/sai8143/safenex/blob/main/mobile-app/src/utils/impactDetector.js): `mobile-app/src/utils/impactDetector.js`
- [Department portals](https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/DepartmentScreens.js): `mobile-app/src/screens/DepartmentScreens.js`
- [Accident history](https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/HistoryScreen.js): `mobile-app/src/screens/HistoryScreen.js`
- [Connection settings](https://github.com/sai8143/safenex/blob/main/mobile-app/src/screens/SettingsScreen.js): `mobile-app/src/screens/SettingsScreen.js`

### Detection and ingest

- [FastAPI routes](https://github.com/sai8143/safenex/blob/main/backend/app/main.py): `backend/app/main.py`
- [RTSP stream worker](https://github.com/sai8143/safenex/blob/main/backend/app/services/rtsp_stream.py): `backend/app/services/rtsp_stream.py`

### Incident analysis

- [Stream frame pipeline](https://github.com/sai8143/safenex/blob/main/backend/app/services/video_detector.py): `backend/app/services/video_detector.py`
- [Vehicle and damage detection](https://github.com/sai8143/safenex/blob/main/backend/app/services/ai_detector.py): `backend/app/services/ai_detector.py`
- [Vehicle tracking](https://github.com/sai8143/safenex/blob/main/backend/app/services/tracker.py): `backend/app/services/tracker.py`
- [Temporal verification](https://github.com/sai8143/safenex/blob/main/backend/app/services/temporal_filter.py): `backend/app/services/temporal_filter.py`
- [Accident decision and severity](https://github.com/sai8143/safenex/blob/main/backend/app/services/decision_engine.py): `backend/app/services/decision_engine.py`

### Persistence and response

- [Emergency alert builder](https://github.com/sai8143/safenex/blob/main/backend/app/services/notifier.py): `backend/app/services/notifier.py`
- [Facility distance and ETA](https://github.com/sai8143/safenex/blob/main/backend/app/services/location.py): `backend/app/services/location.py`
- [WebSocket broadcaster](https://github.com/sai8143/safenex/blob/main/backend/app/services/websocket_manager.py): `backend/app/services/websocket_manager.py`
- [Accident database](https://github.com/sai8143/safenex/blob/main/backend/app/database.py): `backend/app/database.py`
- [Accident records](https://github.com/sai8143/safenex/blob/main/backend/app/models.py): `backend/app/models.py`

### Other components

- **Camera operator**
- **CCTV / webcam**
- **Hospital / police / EMS**
- [Surveillance dashboard](https://github.com/sai8143/safenex/blob/main/backend/app/main.py): `backend/app/main.py`

## Connections

- Camera operator → Mobile tabs: uses (evidence: `mobile-app/App.js`)
- Mobile tabs → Camera and GPS: shows (evidence: `mobile-app/App.js`)
- Mobile tabs → Department portals: shows (evidence: `mobile-app/App.js`)
- Mobile tabs → Connection settings: shows (evidence: `mobile-app/App.js`)
- Camera and GPS → Mobile API client: sends image (evidence: `mobile-app/src/screens/CameraScreen.js`)
- Camera and GPS → Impact trigger: uses (evidence: `mobile-app/src/screens/CameraScreen.js`)
- Mobile API client → Backend URL config: gets endpoint (evidence: `mobile-app/src/services/api.js`)
- Mobile API client → FastAPI routes: posts alert (evidence: `mobile-app/src/services/api.js`)
- Department portals → Mobile API client: uses (evidence: `mobile-app/src/screens/DepartmentScreens.js`)
- Accident history → Mobile API client: uses (evidence: `mobile-app/src/services/api.js`)
- Connection settings → Mobile API client: uses (evidence: `mobile-app/src/screens/SettingsScreen.js`)
- CCTV / webcam → RTSP stream worker: provides frames (evidence: `README.md`)
- CCTV / webcam → FastAPI routes: uploads frames (evidence: `README.md`)
- FastAPI routes → Vehicle and damage detection: analyzes image (evidence: `backend/app/main.py`)
- FastAPI routes → Stream frame pipeline: analyzes frame (evidence: `backend/app/main.py`)
- FastAPI routes → RTSP stream worker: starts stream (evidence: `backend/app/main.py`)
- RTSP stream worker → Stream frame pipeline: processes frames (evidence: `backend/app/services/rtsp_stream.py`)
- RTSP stream worker → Vehicle and damage detection: analyzes evidence (evidence: `backend/app/services/rtsp_stream.py`)
- Stream frame pipeline → Vehicle and damage detection: detects vehicles (evidence: `backend/app/services/video_detector.py`)
- Stream frame pipeline → Vehicle tracking: tracks vehicles (evidence: `backend/app/services/video_detector.py`)
- Stream frame pipeline → Temporal verification: verifies persistence (evidence: `backend/app/services/video_detector.py`)
- Stream frame pipeline → Accident decision and severity: evaluates incident (evidence: `backend/app/services/video_detector.py`)
- Vehicle and damage detection → Accident decision and severity: classifies evidence (evidence: `backend/app/services/ai_detector.py`)
- FastAPI routes → Accident database: uses sessions (evidence: `backend/app/main.py`)
- FastAPI routes → Accident records: reads and writes (evidence: `backend/app/main.py`)
- RTSP stream worker → Accident database: persists incident (evidence: `backend/app/services/rtsp_stream.py`)
- RTSP stream worker → Accident records: creates record (evidence: `backend/app/services/rtsp_stream.py`)
- FastAPI routes → Emergency alert builder: dispatches confirmed (evidence: `README.md`)
- RTSP stream worker → Emergency alert builder: notifies on confirmation (evidence: `backend/app/services/rtsp_stream.py`)
- Emergency alert builder → Facility distance and ETA: calculates facilities (evidence: `backend/app/services/notifier.py`)
- Emergency alert builder → WebSocket broadcaster: broadcasts alerts (evidence: `backend/app/services/notifier.py`)
- WebSocket broadcaster → Hospital / police / EMS: pushes alerts (evidence: `README.md`)
- FastAPI routes → Surveillance dashboard: serves dashboard (evidence: `backend/app/main.py`)
- Surveillance dashboard → WebSocket broadcaster: receives live alerts (evidence: `README.md`)
- Emergency alert builder → Hospital / police / EMS: dispatches response (evidence: `README.md`)
- FastAPI routes → Accident records: lists history (evidence: `backend/app/main.py`)
- FastAPI routes → WebSocket broadcaster: routes socket clients (evidence: `backend/app/main.py`)
