# ashfak99/hackinverse-women-safety architecture

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

- Interactive diagram: https://gitdiagram.com/ashfak99/hackinverse-women-safety
- Repository: https://github.com/ashfak99/hackinverse-women-safety

## Overview

Nari-Suraksha is an offline-first Android safety app: a user triggers SOS, a cancel countdown precedes local audio/location capture, and BLE broadcasts the alert to nearby phones; responders can acknowledge it. The app also provides decoy-calculator access, background scanning, incident history, and safe-zone information. A React web portal presents product information and an interactive simulator. Android startup and SOS orchestration are supported by excerpts; several feature branches are documented in the README but their implementation files were not sampled, so those links cite the README.

Main entry points: [`app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt`](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt) (Main view model), [`frontend/src/App.jsx`](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/App.jsx) (Web portal shell), [`app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt`](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt) (App entry), [`app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt`](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt) (SOS broadcast service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android_ui["Android experience"]
  node_activity["App entry<br/>[MainActivity.kt]"]
  node_main_vm["Main view model<br/>[MainViewModel.kt]"]
  node_home_ui["Home and alert UI<br/>[HomeScreen.kt]"]
  node_decoy["Calculator decoy"]
  node_safe_zones["Safe zones<br/>[SafeZoneScreen.kt]"]
end

subgraph group_sos_flow["SOS workflow"]
  node_sos_manager["SOS countdown manager<br/>[SosManager.kt]"]
  node_shake["Shake trigger<br/>[ShakeDetector.kt]"]
  node_audio["Audio evidence<br/>[AudioRecorder.kt]"]
  node_location["GPS capture"]
  node_sos_service["SOS broadcast service"]
end

subgraph group_ble_mesh["BLE mesh"]
  node_packet["SOS packet<br/>[SosPacket.kt]"]
  node_transport["BLE transport"]
  node_advertiser["BLE advertiser<br/>[BleAdvertiser.kt]"]
  node_scanner["BLE scanner<br/>[BleScanner.kt]"]
  node_scan_service["Background guardian"]
end

subgraph group_state_services["State and services"]
  node_preferences["User preferences"]
  node_database[("Incident database<br/>[AppDatabase.kt]")]
  node_history["Incident history"]
end

subgraph group_web_portal["Web portal"]
  node_web_app["Web portal shell<br/>[App.jsx]"]
  node_simulator["BLE and decoy simulator"]
  node_web_features["Feature overview<br/>[FeatureGrid.jsx]"]
  node_web_zones["Safe-zone explorer"]
  node_web_architecture["Offline architecture display"]
  node_download["Android download"]
end

node_user(("Phone user"))
node_nearby_phone(("Nearby responder phone"))

node_user -->|"opens app"| node_activity
node_activity -->|"creates"| node_main_vm
node_activity -->|"navigates to"| node_home_ui
node_home_ui -->|"observes state"| node_main_vm
node_user -->|"triggers SOS"| node_home_ui
node_user -->|"enters secret PIN"| node_decoy
node_decoy -->|"covert trigger"| node_sos_manager
node_user -->|"shakes phone"| node_shake
node_main_vm -->|"starts or stops"| node_shake
node_main_vm -->|"handles SOS events"| node_sos_manager
node_sos_manager -->|"starts recording"| node_audio
node_sos_manager -->|"fetches coordinates"| node_location
node_main_vm -->|"starts service"| node_sos_service
node_sos_service -->|"creates packet"| node_packet
node_sos_service -->|"starts advertising"| node_transport
node_transport -.->|"dispatches broadcast"| node_advertiser
node_advertiser -->|"broadcasts SOS"| node_nearby_phone
node_nearby_phone -->|"sends ACK beacon"| node_scanner
node_scanner -.->|"returns received alerts"| node_transport
node_scan_service -->|"starts scanning"| node_transport
node_scan_service -.->|"records received SOS"| node_database
node_sos_service -->|"persists sent event"| node_database
node_main_vm -->|"reads settings"| node_preferences
node_activity -->|"creates view model"| node_history
node_history -.->|"loads incidents"| node_database
node_user -->|"views help locations"| node_safe_zones
node_web_app -->|"renders"| node_simulator
node_web_app -->|"renders"| node_web_features
node_web_app -->|"renders"| node_web_zones
node_web_app -->|"renders"| node_web_architecture
node_web_app -->|"renders"| node_download

click node_activity "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt"
click node_main_vm "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt"
click node_home_ui "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/screens/HomeScreen.kt"
click node_decoy "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/decoy/CalculatorEngine.kt"
click node_safe_zones "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/screens/SafeZoneScreen.kt"
click node_sos_manager "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/trigger/SosManager.kt"
click node_shake "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/trigger/ShakeDetector.kt"
click node_audio "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/capture/AudioRecorder.kt"
click node_location "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/capture/LocationProvider.kt"
click node_sos_service "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt"
click node_packet "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/core/SosPacket.kt"
click node_transport "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ble/BleTransportImpl.kt"
click node_advertiser "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ble/BleAdvertiser.kt"
click node_scanner "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ble/BleScanner.kt"
click node_scan_service "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/service/ScanForegroundService.kt"
click node_preferences "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/data/UserPreferencesRepository.kt"
click node_database "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/data/AppDatabase.kt"
click node_history "https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/HistoryViewModel.kt"
click node_web_app "https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/App.jsx"
click node_simulator "https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/InteractiveSimulator.jsx"
click node_web_features "https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/FeatureGrid.jsx"
click node_web_zones "https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/SafeZonesExplorer.jsx"
click node_web_architecture "https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/OfflineArchitecture.jsx"
click node_download "https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/DownloadSection.jsx"

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_activity,node_main_vm,node_home_ui,node_decoy,node_safe_zones,node_user toneBlue
class node_sos_manager,node_shake,node_audio,node_location,node_sos_service toneAmber
class node_packet,node_transport,node_advertiser,node_scanner,node_scan_service toneMint
class node_preferences,node_database,node_history toneRose
class node_web_app,node_simulator,node_web_features,node_web_zones,node_web_architecture,node_download,node_nearby_phone toneIndigo
```

## Components

### Android experience

- [App entry](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt): `app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt`
- [Main view model](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt): `app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt`
- [Home and alert UI](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/screens/HomeScreen.kt): `app/src/main/java/com/brokencoders/narisuraksha/ui/screens/HomeScreen.kt`
- [Calculator decoy](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/decoy/CalculatorEngine.kt): `app/src/main/java/com/brokencoders/narisuraksha/decoy/CalculatorEngine.kt`
- [Safe zones](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/screens/SafeZoneScreen.kt): `app/src/main/java/com/brokencoders/narisuraksha/ui/screens/SafeZoneScreen.kt`

### SOS workflow

- [SOS countdown manager](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/trigger/SosManager.kt): `app/src/main/java/com/brokencoders/narisuraksha/trigger/SosManager.kt`
- [Shake trigger](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/trigger/ShakeDetector.kt): `app/src/main/java/com/brokencoders/narisuraksha/trigger/ShakeDetector.kt`
- [Audio evidence](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/capture/AudioRecorder.kt): `app/src/main/java/com/brokencoders/narisuraksha/capture/AudioRecorder.kt`
- [GPS capture](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/capture/LocationProvider.kt): `app/src/main/java/com/brokencoders/narisuraksha/capture/LocationProvider.kt`
- [SOS broadcast service](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt): `app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt`

### BLE mesh

- [SOS packet](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/core/SosPacket.kt): `app/src/main/java/com/brokencoders/narisuraksha/core/SosPacket.kt`
- [BLE transport](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ble/BleTransportImpl.kt): `app/src/main/java/com/brokencoders/narisuraksha/ble/BleTransportImpl.kt`
- [BLE advertiser](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ble/BleAdvertiser.kt): `app/src/main/java/com/brokencoders/narisuraksha/ble/BleAdvertiser.kt`
- [BLE scanner](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ble/BleScanner.kt): `app/src/main/java/com/brokencoders/narisuraksha/ble/BleScanner.kt`
- [Background guardian](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/service/ScanForegroundService.kt): `app/src/main/java/com/brokencoders/narisuraksha/service/ScanForegroundService.kt`

### State and services

- [User preferences](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/data/UserPreferencesRepository.kt): `app/src/main/java/com/brokencoders/narisuraksha/data/UserPreferencesRepository.kt`
- [Incident database](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/data/AppDatabase.kt): `app/src/main/java/com/brokencoders/narisuraksha/data/AppDatabase.kt`
- [Incident history](https://github.com/ashfak99/hackinverse-women-safety/blob/main/app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/HistoryViewModel.kt): `app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/HistoryViewModel.kt`

### Web portal

- [Web portal shell](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [BLE and decoy simulator](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/InteractiveSimulator.jsx): `frontend/src/components/InteractiveSimulator.jsx`
- [Feature overview](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/FeatureGrid.jsx): `frontend/src/components/FeatureGrid.jsx`
- [Safe-zone explorer](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/SafeZonesExplorer.jsx): `frontend/src/components/SafeZonesExplorer.jsx`
- [Offline architecture display](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/OfflineArchitecture.jsx): `frontend/src/components/OfflineArchitecture.jsx`
- [Android download](https://github.com/ashfak99/hackinverse-women-safety/blob/main/frontend/src/components/DownloadSection.jsx): `frontend/src/components/DownloadSection.jsx`

### Other components

- **Phone user**
- **Nearby responder phone**

## Connections

- Phone user → App entry: opens app (evidence: `README.md`)
- App entry → Main view model: creates (evidence: `app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt`)
- App entry → Home and alert UI: navigates to (evidence: `app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt`)
- Home and alert UI → Main view model: observes state (evidence: `app/src/main/java/com/brokencoders/narisuraksha/ui/screens/HomeScreen.kt`)
- Phone user → Home and alert UI: triggers SOS (evidence: `README.md`)
- Phone user → Calculator decoy: enters secret PIN (evidence: `README.md`)
- Calculator decoy → SOS countdown manager: covert trigger (evidence: `README.md`)
- Phone user → Shake trigger: shakes phone (evidence: `README.md`)
- Main view model → Shake trigger: starts or stops (evidence: `app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt`)
- Main view model → SOS countdown manager: handles SOS events (evidence: `app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt`)
- SOS countdown manager → Audio evidence: starts recording (evidence: `app/src/main/java/com/brokencoders/narisuraksha/trigger/SosManager.kt`)
- SOS countdown manager → GPS capture: fetches coordinates (evidence: `app/src/main/java/com/brokencoders/narisuraksha/trigger/SosManager.kt`)
- Main view model → SOS broadcast service: starts service (evidence: `app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt`)
- SOS broadcast service → SOS packet: creates packet (evidence: `app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt`)
- SOS broadcast service → BLE transport: starts advertising (evidence: `README.md`)
- BLE transport → BLE advertiser: dispatches broadcast
- BLE advertiser → Nearby responder phone: broadcasts SOS (evidence: `README.md`)
- Nearby responder phone → BLE scanner: sends ACK beacon (evidence: `README.md`)
- BLE scanner → BLE transport: returns received alerts
- Background guardian → BLE transport: starts scanning (evidence: `app/src/main/java/com/brokencoders/narisuraksha/service/ScanForegroundService.kt`)
- Background guardian → Incident database: records received SOS
- SOS broadcast service → Incident database: persists sent event (evidence: `app/src/main/java/com/brokencoders/narisuraksha/service/SosForegroundService.kt`)
- Main view model → User preferences: reads settings (evidence: `app/src/main/java/com/brokencoders/narisuraksha/ui/viewmodels/MainViewModel.kt`)
- App entry → Incident history: creates view model (evidence: `app/src/main/java/com/brokencoders/narisuraksha/MainActivity.kt`)
- Incident history → Incident database: loads incidents
- Phone user → Safe zones: views help locations (evidence: `README.md`)
- Web portal shell → BLE and decoy simulator: renders (evidence: `frontend/src/App.jsx`)
- Web portal shell → Feature overview: renders (evidence: `frontend/src/App.jsx`)
- Web portal shell → Safe-zone explorer: renders (evidence: `frontend/src/App.jsx`)
- Web portal shell → Offline architecture display: renders (evidence: `frontend/src/App.jsx`)
- Web portal shell → Android download: renders (evidence: `frontend/src/App.jsx`)
