# hamsaraj875-del/personal_safety_and_emergency_response_platform architecture

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

- Interactive diagram: https://gitdiagram.com/hamsaraj875-del/personal_safety_and_emergency_response_platform
- Repository: https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform

## Overview

Jaagruth is a personal safety and emergency-response platform: citizens trigger SOS and follow dispatch in the Android app, while authorities monitor incidents through a web command deck; a Node/MongoDB server coordinates response. The documented flow includes a cancel buffer, timed contact/responder escalation, live tracking, and an ERSS handoff. The README also describes duress alerts, triage, responder matching, and a tamper-evident ledger. Source excerpts show server incident-to-ledger/realtime calls and UI entry points; several other links are documented capabilities or remain unverified because their implementation was not sampled.

Main entry points: [`server/src/index.js`](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/index.js) (API Server), [`website/src/components/authority/AuthorityDashboard.jsx`](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityDashboard.jsx) (Authority Dashboard), [`server/src/services/incidentService.js`](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/incidentService.js) (Incident Orchestration), [`app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt`](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt) (Incident Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen Android App"]
  node_android_entry["Android Entry<br/>[MainActivity.kt]"]
  node_android_ui["Citizen Screens"]
  node_android_incident["Incident Repository"]
  node_android_models["Incident Models<br/>[Incident.kt]"]
  node_android_mock[("Offline Data<br/>[MockDataSource.kt]")]
  node_android_api["API Client<br/>[ApiService.kt]"]
  node_android_network["Network Setup<br/>[NetworkClient.kt]"]
  node_android_tokens[("Token Store<br/>[TokenStore.kt]")]
  node_android_location["Location Tracking<br/>[LocationService.kt]"]
end

subgraph group_backend["Response Backend"]
  node_server_entry["API Server<br/>[index.js]"]
  node_server_auth["Authentication Routes<br/>[auth.js]"]
  node_server_incidents["Incident Routes<br/>[incidents.js]"]
  node_server_tracking["Tracking Routes<br/>[track.js]"]
  node_server_ws["Realtime WebSocket<br/>[ws.js]"]
  node_server_db[("MongoDB<br/>[connect.js]")]
  node_server_config["Runtime Configuration<br/>[env.js]"]
  node_server_limiter["Rate Limiting<br/>[rateLimit.js]"]
  node_server_seed["Demo Data Seed<br/>[seed.js]"]
end

subgraph group_authority["Authority Command Deck"]
  node_citizen_web["Authority Website<br/>[App.jsx]"]
  node_authority_login["Officer Access"]
  node_dashboard["Authority Dashboard"]
  node_authority_map["Incident Map<br/>[AuthorityMap.jsx]"]
  node_incident_drawer["Incident Inspector"]
  node_web_api["Web API Service<br/>[api.js]"]
  node_web_socket["WebSocket Service<br/>[socket.js]"]
end

subgraph group_domain["Response Domain Services"]
  node_incident_service["Incident Orchestration<br/>[incidentService.js]"]
  node_escalation["Timed Escalation"]
  node_matching["Responder Matching"]
  node_triage["Severity Triage<br/>[triageService.js]"]
  node_ledger[("Cryptographic Ledger<br/>[ledgerService.js]")]
  node_erss["ERSS Handoff<br/>[erssHandoff.js]"]
end

node_citizen_user(("Citizen"))
node_officer(("Authority Officer"))
node_erss_external(("112 / ERSS"))

node_citizen_user -->|"uses"| node_android_entry
node_android_entry -->|"launches"| node_android_ui
node_android_ui -.->|"triggers SOS"| node_android_incident
node_android_incident -.->|"calls API"| node_android_api
node_android_api -.->|"sends requests"| node_server_entry
node_android_incident -->|"uses"| node_android_models
node_android_incident -->|"falls back"| node_android_mock
node_android_network -.->|"uses credentials"| node_android_tokens
node_android_location -->|"uses fallback data"| node_android_mock
node_server_entry -->|"loads settings"| node_server_config
node_server_entry -->|"applies limits"| node_server_limiter
node_server_entry -->|"connects"| node_server_db
node_server_entry -->|"initializes"| node_server_ws
node_server_entry -->|"seeds optionally"| node_server_seed
node_server_entry -->|"mounts routes"| node_server_auth
node_server_entry -->|"mounts routes"| node_server_incidents
node_server_entry -->|"mounts routes"| node_server_tracking
node_server_incidents -.->|"handles incidents"| node_incident_service
node_incident_service -->|"appends blocks"| node_ledger
node_incident_service -->|"broadcasts updates"| node_server_ws
node_incident_service -.->|"schedules escalation"| node_escalation
node_escalation -.->|"dispatches ranked responder"| node_matching
node_incident_service -.->|"requests severity triage"| node_triage
node_escalation -.->|"prepares handoff"| node_erss
node_erss -->|"hands off"| node_erss_external
node_officer -->|"opens"| node_citizen_web
node_citizen_web -->|"shows access"| node_authority_login
node_citizen_web -->|"shows after authorization"| node_dashboard
node_dashboard -->|"renders"| node_authority_map
node_dashboard -->|"renders"| node_incident_drawer
node_dashboard -->|"fetches incident data"| node_web_api
node_dashboard -->|"receives live updates"| node_web_socket
node_server_ws -.->|"streams events"| node_web_socket
node_incident_service -->|"alerts authorities"| node_dashboard
node_dashboard -.->|"verifies incident integrity"| node_ledger

click node_android_entry "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/MainActivity.kt"
click node_android_ui "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/ui/JagrathAppContainer.kt"
click node_android_incident "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt"
click node_android_models "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/models/Incident.kt"
click node_android_mock "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/local/MockDataSource.kt"
click node_android_api "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/remote/ApiService.kt"
click node_android_network "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/remote/NetworkClient.kt"
click node_android_tokens "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/remote/TokenStore.kt"
click node_android_location "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/services/LocationService.kt"
click node_server_entry "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/index.js"
click node_server_auth "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/routes/auth.js"
click node_server_incidents "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/routes/incidents.js"
click node_server_tracking "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/routes/track.js"
click node_server_ws "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/realtime/ws.js"
click node_server_db "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/db/connect.js"
click node_server_config "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/config/env.js"
click node_server_limiter "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/middleware/rateLimit.js"
click node_server_seed "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/seed/seed.js"
click node_incident_service "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/incidentService.js"
click node_escalation "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/escalationScheduler.js"
click node_matching "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/responderMatcher.js"
click node_triage "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/triageService.js"
click node_ledger "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/ledgerService.js"
click node_erss "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/erssHandoff.js"
click node_citizen_web "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/App.jsx"
click node_authority_login "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityLoginModal.jsx"
click node_dashboard "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityDashboard.jsx"
click node_authority_map "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityMap.jsx"
click node_incident_drawer "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/IncidentInspectDrawer.jsx"
click node_web_api "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/services/api.js"
click node_web_socket "https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/services/socket.js"

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_android_ui,node_android_incident,node_android_models,node_android_mock,node_android_api,node_android_network,node_android_tokens,node_android_location toneBlue
class node_server_entry,node_server_auth,node_server_incidents,node_server_tracking,node_server_ws,node_server_db,node_server_config,node_server_limiter,node_server_seed toneAmber
class node_citizen_web,node_authority_login,node_dashboard,node_authority_map,node_incident_drawer,node_web_api,node_web_socket toneMint
class node_incident_service,node_escalation,node_matching,node_triage,node_ledger,node_erss toneRose
class node_citizen_user,node_officer,node_erss_external toneIndigo
```

## Components

### Citizen Android App

- [Android Entry](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/MainActivity.kt): `app/app/src/main/java/com/jaagruth/MainActivity.kt`
- [Citizen Screens](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/ui/JagrathAppContainer.kt): `app/app/src/main/java/com/jaagruth/ui/JagrathAppContainer.kt`
- [Incident Repository](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt): `app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt`
- [Incident Models](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/models/Incident.kt): `app/app/src/main/java/com/jaagruth/data/models/Incident.kt`
- [Offline Data](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/local/MockDataSource.kt): `app/app/src/main/java/com/jaagruth/data/local/MockDataSource.kt`
- [API Client](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/remote/ApiService.kt): `app/app/src/main/java/com/jaagruth/data/remote/ApiService.kt`
- [Network Setup](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/remote/NetworkClient.kt): `app/app/src/main/java/com/jaagruth/data/remote/NetworkClient.kt`
- [Token Store](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/data/remote/TokenStore.kt): `app/app/src/main/java/com/jaagruth/data/remote/TokenStore.kt`
- [Location Tracking](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/app/app/src/main/java/com/jaagruth/services/LocationService.kt): `app/app/src/main/java/com/jaagruth/services/LocationService.kt`

### Response Backend

- [API Server](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/index.js): `server/src/index.js`
- [Authentication Routes](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/routes/auth.js): `server/src/routes/auth.js`
- [Incident Routes](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/routes/incidents.js): `server/src/routes/incidents.js`
- [Tracking Routes](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/routes/track.js): `server/src/routes/track.js`
- [Realtime WebSocket](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/realtime/ws.js): `server/src/realtime/ws.js`
- [MongoDB](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/db/connect.js): `server/src/db/connect.js`
- [Runtime Configuration](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/config/env.js): `server/src/config/env.js`
- [Rate Limiting](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/middleware/rateLimit.js): `server/src/middleware/rateLimit.js`
- [Demo Data Seed](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/seed/seed.js): `server/src/seed/seed.js`

### Authority Command Deck

- [Authority Website](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/App.jsx): `website/src/App.jsx`
- [Officer Access](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityLoginModal.jsx): `website/src/components/authority/AuthorityLoginModal.jsx`
- [Authority Dashboard](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityDashboard.jsx): `website/src/components/authority/AuthorityDashboard.jsx`
- [Incident Map](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/AuthorityMap.jsx): `website/src/components/authority/AuthorityMap.jsx`
- [Incident Inspector](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/components/authority/IncidentInspectDrawer.jsx): `website/src/components/authority/IncidentInspectDrawer.jsx`
- [Web API Service](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/services/api.js): `website/src/services/api.js`
- [WebSocket Service](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/website/src/services/socket.js): `website/src/services/socket.js`

### Response Domain Services

- [Incident Orchestration](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/incidentService.js): `server/src/services/incidentService.js`
- [Timed Escalation](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/escalationScheduler.js): `server/src/services/escalationScheduler.js`
- [Responder Matching](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/responderMatcher.js): `server/src/services/responderMatcher.js`
- [Severity Triage](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/triageService.js): `server/src/services/triageService.js`
- [Cryptographic Ledger](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/ledgerService.js): `server/src/services/ledgerService.js`
- [ERSS Handoff](https://github.com/hamsaraj875-del/personal_safety_and_emergency_response_platform/blob/main/server/src/services/erssHandoff.js): `server/src/services/erssHandoff.js`

### Other components

- **Citizen**
- **Authority Officer**
- **112 / ERSS**

## Connections

- Citizen → Android Entry: uses (evidence: `README.md`)
- Android Entry → Citizen Screens: launches (evidence: `app/app/src/main/java/com/jaagruth/MainActivity.kt`)
- Citizen Screens → Incident Repository: triggers SOS
- Incident Repository → API Client: calls API
- API Client → API Server: sends requests
- Incident Repository → Incident Models: uses (evidence: `app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt`)
- Incident Repository → Offline Data: falls back (evidence: `app/app/src/main/java/com/jaagruth/data/repository/IncidentRepository.kt`)
- Network Setup → Token Store: uses credentials
- Location Tracking → Offline Data: uses fallback data (evidence: `app/app/src/main/java/com/jaagruth/services/LocationService.kt`)
- API Server → Runtime Configuration: loads settings (evidence: `server/src/index.js`)
- API Server → Rate Limiting: applies limits (evidence: `server/src/index.js`)
- API Server → MongoDB: connects (evidence: `server/src/index.js`)
- API Server → Realtime WebSocket: initializes (evidence: `server/src/index.js`)
- API Server → Demo Data Seed: seeds optionally (evidence: `server/src/index.js`)
- API Server → Authentication Routes: mounts routes (evidence: `server/src/index.js`)
- API Server → Incident Routes: mounts routes (evidence: `server/src/index.js`)
- API Server → Tracking Routes: mounts routes (evidence: `server/src/index.js`)
- Incident Routes → Incident Orchestration: handles incidents
- Incident Orchestration → Cryptographic Ledger: appends blocks (evidence: `server/src/services/incidentService.js`)
- Incident Orchestration → Realtime WebSocket: broadcasts updates (evidence: `server/src/services/incidentService.js`)
- Incident Orchestration → Timed Escalation: schedules escalation
- Timed Escalation → Responder Matching: dispatches ranked responder
- Incident Orchestration → Severity Triage: requests severity triage
- Timed Escalation → ERSS Handoff: prepares handoff
- ERSS Handoff → 112 / ERSS: hands off (evidence: `README.md`)
- Authority Officer → Authority Website: opens (evidence: `README.md`)
- Authority Website → Officer Access: shows access (evidence: `website/src/App.jsx`)
- Authority Website → Authority Dashboard: shows after authorization (evidence: `website/src/App.jsx`)
- Authority Dashboard → Incident Map: renders (evidence: `website/src/components/authority/AuthorityDashboard.jsx`)
- Authority Dashboard → Incident Inspector: renders (evidence: `website/src/components/authority/AuthorityDashboard.jsx`)
- Authority Dashboard → Web API Service: fetches incident data (evidence: `website/src/components/authority/AuthorityDashboard.jsx`)
- Authority Dashboard → WebSocket Service: receives live updates (evidence: `website/src/components/authority/AuthorityDashboard.jsx`)
- Realtime WebSocket → WebSocket Service: streams events
- Incident Orchestration → Authority Dashboard: alerts authorities (evidence: `server/src/services/incidentService.js`)
- Authority Dashboard → Cryptographic Ledger: verifies incident integrity