# sudhanshuxmaurya119-eng/raksha_x architecture

> Architecture diagram of the GitHub repository sudhanshuxmaurya119-eng/raksha_x, 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/sudhanshuxmaurya119-eng/raksha_x
- Repository: https://github.com/sudhanshuxmaurya119-eng/raksha_x

## Overview

RakshaX combines an Android personal-safety app with a FastAPI backend. The user workflow spans BLE emergency-button detection, location capture, SOS escalation to trusted contacts, and backend notification delivery; the app also exposes account, safety-map, incident, and safe-routing capabilities. Backend safety intelligence combines incident data with weather and other feeds. The graph uses README and SOURCE INDEX relationships where available; several implementations are unsampled, so their internal calls are not expanded.

Main entry points: [`Backend/main.py`](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/main.py) (FastAPI application), [`Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt) (Android entry), [`Frontend/app/src/main/java/com/rakshax/app/data/remote/AuroraSafeRepository.kt`](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/remote/AuroraSafeRepository.kt) (Backend client), [`Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt`](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt) (BLE listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android app"]
  node_android_entry["Android entry<br/>[MainActivity.kt]"]
  node_navigation["App navigation<br/>[RakshaXNavGraph.kt]"]
  node_screens["Safety screens"]
  node_ble["BLE connection<br/>[BleRepository.kt]"]
  node_ble_listener["BLE listener"]
  node_location["Location capture"]
  node_app_state["App safety state"]
  node_escalation["SOS escalation"]
  node_push_client["Push handling"]
  node_api_client["Backend client"]
end

subgraph group_backend_api["Backend API"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_sos_api["SOS endpoints<br/>[sos.py]"]
  node_incident_api["Incident endpoints<br/>[incidents.py]"]
  node_route_api["Safe routing<br/>[routes.py]"]
  node_safety_api["Safety endpoints<br/>[safety.py]"]
  node_dashboard_api["Dashboard endpoints<br/>[dashboard.py]"]
  node_notification_api["Notification endpoints<br/>[notifications.py]"]
  node_fcm["FCM delivery<br/>[fcm.py]"]
end

subgraph group_intelligence["Safety intelligence"]
  node_risk_model["Risk model<br/>[risk_model.py]"]
  node_classifier["Incident classifier<br/>[classifier.py]"]
  node_osm["Map data service<br/>[osm_service.py]"]
  node_weather["Weather service<br/>[weather_service.py]"]
end

subgraph group_ingestion["Data ingestion"]
  node_scheduler["Refresh scheduler<br/>[scheduler.py]"]
  node_news["News ingestion<br/>[news_fetcher.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_session["Database session<br/>[database.py]"]
  node_incident_store[("Incident records<br/>[incident.py]")]
  node_user_store[("User records<br/>[user.py]")]
  node_sos_store[("SOS records<br/>[sos_event.py]")]
  node_other_stores[("Contact and route records<br/>[sos_contact.py]")]
end

node_person(("App user"))
node_button{{"ESP32 button"}}
node_external_services["External data and push services"]

node_person -->|"uses"| node_android_entry
node_button -->|"signals over BLE"| node_ble
node_android_entry -->|"starts"| node_navigation
node_navigation -.->|"routes to"| node_screens
node_android_entry -->|"initializes"| node_ble
node_android_entry -->|"starts"| node_ble_listener
node_ble_listener -->|"uses"| node_ble
node_ble_listener -->|"captures location"| node_location
node_ble_listener -->|"triggers SOS"| node_api_client
node_ble_listener -->|"starts"| node_escalation
node_android_entry -->|"creates"| node_location
node_android_entry -->|"creates"| node_api_client
node_android_entry -->|"reads contacts"| node_app_state
node_android_entry -->|"flushes queued actions"| node_api_client
node_api_client -->|"calls API"| node_backend
node_api_client -.->|"registers push device"| node_external_services
node_backend -->|"initializes"| node_db_session
node_backend -->|"registers router"| node_auth
node_backend -->|"registers router"| node_sos_api
node_backend -->|"registers router"| node_incident_api
node_backend -->|"registers router"| node_route_api
node_backend -->|"registers router"| node_safety_api
node_backend -->|"registers router"| node_dashboard_api
node_backend -->|"registers router"| node_notification_api
node_backend -->|"starts"| node_scheduler
node_incident_api -->|"classifies reports"| node_classifier
node_incident_api -->|"scores risk"| node_risk_model
node_route_api -->|"loads red zones"| node_incident_store
node_route_api -->|"requests road routes"| node_external_services
node_scheduler -->|"schedules fetches"| node_news
node_scheduler -->|"schedules refresh"| node_weather
node_news -->|"uses map service"| node_osm
node_sos_api -->|"sends alerts"| node_fcm
node_fcm -.->|"delivers push"| node_external_services
node_sos_api -->|"records SOS"| node_sos_store
node_sos_api -->|"uses contact records"| node_other_stores
node_auth -->|"authenticates"| node_user_store
node_incident_api -->|"uses incidents"| node_incident_store
node_db_session -->|"registers model"| node_incident_store
node_db_session -->|"registers model"| node_user_store
node_push_client -->|"uses API"| node_api_client

click node_android_entry "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt"
click node_navigation "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/ui/navigation/RakshaXNavGraph.kt"
click node_screens "https://github.com/sudhanshuxmaurya119-eng/raksha_x/tree/main/Frontend/app/src/main/java/com/rakshax/app/ui/screens"
click node_ble "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/ble/BleRepository.kt"
click node_ble_listener "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt"
click node_location "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/location/LocationRepository.kt"
click node_app_state "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/repository/MockDataRepository.kt"
click node_escalation "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/service/SosEscalationService.kt"
click node_push_client "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/notification/RakshaFirebaseMessagingService.kt"
click node_api_client "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/remote/AuroraSafeRepository.kt"
click node_backend "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/main.py"
click node_auth "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/auth.py"
click node_sos_api "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/sos.py"
click node_incident_api "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/incidents.py"
click node_route_api "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/routes.py"
click node_safety_api "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/safety.py"
click node_dashboard_api "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/dashboard.py"
click node_notification_api "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/notifications.py"
click node_risk_model "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/ml/risk_model.py"
click node_classifier "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/ml/classifier.py"
click node_osm "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/osm_service.py"
click node_weather "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/weather_service.py"
click node_scheduler "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/scheduler.py"
click node_news "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/news_fetcher.py"
click node_fcm "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/fcm.py"
click node_db_session "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/database.py"
click node_incident_store "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/incident.py"
click node_user_store "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/user.py"
click node_sos_store "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/sos_event.py"
click node_other_stores "https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/sos_contact.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_android_entry,node_navigation,node_screens,node_ble,node_ble_listener,node_location,node_app_state,node_escalation,node_push_client,node_api_client,node_person toneBlue
class node_backend,node_auth,node_sos_api,node_incident_api,node_route_api,node_safety_api,node_dashboard_api,node_notification_api,node_fcm toneAmber
class node_risk_model,node_classifier,node_osm,node_weather toneMint
class node_scheduler,node_news toneRose
class node_db_session,node_incident_store,node_user_store,node_sos_store,node_other_stores,node_button,node_external_services toneIndigo
```

## Components

### Android app

- [Android entry](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt): `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`
- [App navigation](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/ui/navigation/RakshaXNavGraph.kt): `Frontend/app/src/main/java/com/rakshax/app/ui/navigation/RakshaXNavGraph.kt`
- [Safety screens](https://github.com/sudhanshuxmaurya119-eng/raksha_x/tree/main/Frontend/app/src/main/java/com/rakshax/app/ui/screens): `Frontend/app/src/main/java/com/rakshax/app/ui/screens`
- [BLE connection](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/ble/BleRepository.kt): `Frontend/app/src/main/java/com/rakshax/app/data/ble/BleRepository.kt`
- [BLE listener](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt): `Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt`
- [Location capture](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/location/LocationRepository.kt): `Frontend/app/src/main/java/com/rakshax/app/data/location/LocationRepository.kt`
- [App safety state](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/repository/MockDataRepository.kt): `Frontend/app/src/main/java/com/rakshax/app/data/repository/MockDataRepository.kt`
- [SOS escalation](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/service/SosEscalationService.kt): `Frontend/app/src/main/java/com/rakshax/app/service/SosEscalationService.kt`
- [Push handling](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/notification/RakshaFirebaseMessagingService.kt): `Frontend/app/src/main/java/com/rakshax/app/notification/RakshaFirebaseMessagingService.kt`
- [Backend client](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Frontend/app/src/main/java/com/rakshax/app/data/remote/AuroraSafeRepository.kt): `Frontend/app/src/main/java/com/rakshax/app/data/remote/AuroraSafeRepository.kt`

### Backend API

- [FastAPI application](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/main.py): `Backend/main.py`
- [Authentication](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/auth.py): `Backend/routers/auth.py`
- [SOS endpoints](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/sos.py): `Backend/routers/sos.py`
- [Incident endpoints](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/incidents.py): `Backend/routers/incidents.py`
- [Safe routing](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/routes.py): `Backend/routers/routes.py`
- [Safety endpoints](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/safety.py): `Backend/routers/safety.py`
- [Dashboard endpoints](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/dashboard.py): `Backend/routers/dashboard.py`
- [Notification endpoints](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/routers/notifications.py): `Backend/routers/notifications.py`
- [FCM delivery](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/fcm.py): `Backend/services/fcm.py`

### Safety intelligence

- [Risk model](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/ml/risk_model.py): `Backend/ml/risk_model.py`
- [Incident classifier](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/ml/classifier.py): `Backend/ml/classifier.py`
- [Map data service](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/osm_service.py): `Backend/services/osm_service.py`
- [Weather service](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/weather_service.py): `Backend/services/weather_service.py`

### Data ingestion

- [Refresh scheduler](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/scheduler.py): `Backend/services/scheduler.py`
- [News ingestion](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/services/news_fetcher.py): `Backend/services/news_fetcher.py`

### Persistence

- [Database session](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/database.py): `Backend/database.py`
- [Incident records](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/incident.py): `Backend/models/incident.py`
- [User records](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/user.py): `Backend/models/user.py`
- [SOS records](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/sos_event.py): `Backend/models/sos_event.py`
- [Contact and route records](https://github.com/sudhanshuxmaurya119-eng/raksha_x/blob/main/Backend/models/sos_contact.py): `Backend/models/sos_contact.py`

### Other components

- **App user**
- **ESP32 button**
- **External data and push services**

## Connections

- App user → Android entry: uses (evidence: `README.md`)
- ESP32 button → BLE connection: signals over BLE (evidence: `README.md`)
- Android entry → App navigation: starts (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- App navigation → Safety screens: routes to (evidence: `Frontend/app/src/main/java/com/rakshax/app/ui/navigation/RakshaXNavGraph.kt`)
- Android entry → BLE connection: initializes (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- Android entry → BLE listener: starts (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- BLE listener → BLE connection: uses (evidence: `Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt`)
- BLE listener → Location capture: captures location (evidence: `Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt`)
- BLE listener → Backend client: triggers SOS (evidence: `Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt`)
- BLE listener → SOS escalation: starts (evidence: `Frontend/app/src/main/java/com/rakshax/app/service/BleSosListenerService.kt`)
- Android entry → Location capture: creates (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- Android entry → Backend client: creates (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- Android entry → App safety state: reads contacts (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- Android entry → Backend client: flushes queued actions (evidence: `Frontend/app/src/main/java/com/rakshax/app/MainActivity.kt`)
- Backend client → FastAPI application: calls API (evidence: `README.md`)
- Backend client → External data and push services: registers push device
- FastAPI application → Database session: initializes (evidence: `Backend/main.py`)
- FastAPI application → Authentication: registers router (evidence: `Backend/main.py`)
- FastAPI application → SOS endpoints: registers router (evidence: `Backend/main.py`)
- FastAPI application → Incident endpoints: registers router (evidence: `Backend/main.py`)
- FastAPI application → Safe routing: registers router (evidence: `Backend/main.py`)
- FastAPI application → Safety endpoints: registers router (evidence: `Backend/main.py`)
- FastAPI application → Dashboard endpoints: registers router (evidence: `Backend/main.py`)
- FastAPI application → Notification endpoints: registers router (evidence: `Backend/main.py`)
- FastAPI application → Refresh scheduler: starts (evidence: `Backend/main.py`)
- Incident endpoints → Incident classifier: classifies reports (evidence: `Backend/routers/incidents.py`)
- Incident endpoints → Risk model: scores risk (evidence: `Backend/routers/incidents.py`)
- Safe routing → Incident records: loads red zones (evidence: `Backend/routers/routes.py`)
- Safe routing → External data and push services: requests road routes (evidence: `Backend/routers/routes.py`)
- Refresh scheduler → News ingestion: schedules fetches (evidence: `Backend/services/scheduler.py`)
- Refresh scheduler → Weather service: schedules refresh (evidence: `Backend/services/scheduler.py`)
- News ingestion → Map data service: uses map service (evidence: `Backend/services/news_fetcher.py`)
- SOS endpoints → FCM delivery: sends alerts (evidence: `Backend/routers/sos.py`)
- FCM delivery → External data and push services: delivers push
- SOS endpoints → SOS records: records SOS (evidence: `Backend/routers/sos.py`)
- SOS endpoints → Contact and route records: uses contact records (evidence: `Backend/routers/sos.py`)
- Authentication → User records: authenticates (evidence: `Backend/routers/auth.py`)
- Incident endpoints → Incident records: uses incidents (evidence: `Backend/routers/incidents.py`)
- Database session → Incident records: registers model (evidence: `Backend/database.py`)
- Database session → User records: registers model (evidence: `Backend/database.py`)
- Push handling → Backend client: uses API (evidence: `Frontend/app/src/main/java/com/rakshax/app/notification/RakshaFirebaseMessagingService.kt`)
