# the-bhuvi/codehathon-4.0-sos-app architecture

> Architecture diagram of the GitHub repository the-bhuvi/codehathon-4.0-sos-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-bhuvi/codehathon-4.0-sos-app
- Repository: https://github.com/the-bhuvi/codehathon-4.0-sos-app

## Overview

#### Purpose and Top-Level Shape
SafeAlert is a distributed SOS-response system: a Flutter victim app creates emergency alerts, Python AI enriches/prioritizes them, Supabase persists and publishes live state, and a React dashboard supports agency response. The repository has independently runnable mobile, AI, dashboard, and Node API units.

#### Client Entry Points
- Flutter app startup and composition: `mobile/lib/main.dart`; primary SOS/home flow: `mobile/lib/screens/home/home_screen.dart`.
- React/Vite dashboard startup: `dashboard/src/main.jsx`, with root UI assembly in `dashboard/src/App.jsx`.
- AI service executable: `backend/ai/main.py`.
- Node API service entry point: `backend/api/index.js`.

#### SOS Capture and Device Resilience
The mobile app is the incident producer. Its SOS UI and confirmation sequence collect a user-triggered emergency; service boundaries separate API submission, location acquisition, local persistence, SMS fallback, and offline retry.
- SOS presentation: `mobile/lib/widgets/sos_button.dart`, `mobile/lib/screens/confirmation/confirmation_screen.dart`.
- Delivery/resilience services: `mobile/lib/services/api_service.dart`, `mobile/lib/services/offline_queue_service.dart`, `mobile/lib/services/location_service.dart`.
- Android-specific background shake detection and reboot restoration are native platform responsibilities: `mobile/android/app/src/main/kotlin/com/safealert/safe_alert/ShakeDetectionService.kt`, `mobile/android/app/src/main/kotlin/com/safealert/safe_alert/BootReceiver.kt`.

#### AI Enrichment and Backend Boundary
The FastAPI process is the AI-facing HTTP boundary. Per the project design, it classifies severity, supports language handling/transcription, stores/analyzes alert information, and forwards alerts to relevant agencies. Python dependencies and runtime configuration are isolated from the Node service.
- Implementation/runtime: `backend/ai/main.py`, `backend/ai/requirements.txt`.
- Separate JavaScript API/proxy runtime: `backend/api/index.js`, `backend/api/package.json`.
- The mobile-to-backend contract is consumed through `mobile/lib/services/api_service.dart`.

#### Supabase as System of Record and Realtime Bus
Supabase/PostgreSQL is the shared persistence and live-update boundary between alert creation, backend enrichment, and responders. Schema/bootstrap artifacts define database setup and feature migration; each frontend has a Supabase integration layer.
- Database definitions: `docs/database_setup.sql`, `backend/migrations/001_add_all_features.sql`.
- Mobile integration: `mobile/lib/services/supabase_service.dart`.
- Dashboard integration: `dashboard/src/lib/supabase.js`.

#### Agency Operations Dashboard
The dashboard consumes realtime incident state for visual triage and resolution workflows rather than owning emergency data. The dashboard shell coordinates map, incident list, detail/right panel, and response controls.
- Composition: `dashboard/src/components/Dashboard.jsx`.
- Operational views: `dashboard/src/components/Map.jsx`, `dashboard/src/components/IncidentList.jsx`, `dashboard/src/components/RightPanel.jsx`.
- Shared top/bottom navigation controls: `dashboard/src/components/TopBar.jsx`, `dashboard/src/components/BottomBar.jsx`.

#### Primary End-to-End Flow
1. A user triggers SOS manually or through Android shake detection.
2. Mobile collects location/context, persists or queues locally when offline, then submits through its API/Supabase services.
3. The AI backend processes emergency context for severity and routing; Supabase retains the incident and emits realtime changes.
4. The React dashboard receives incident updates, maps and prioritizes them, and responders update lifecycle state.
5. Supabase updates propagate to connected clients; mobile history and agency-facing views consume the shared incident record.

#### Material Runtimes and External Services
Flutter/Dart targets Android and iOS; Android includes Kotlin services for background triggering. The dashboard is React/Vite on Node.js. AI runs Python/FastAPI with Hugging Face DistilBERT and speech-recognition capabilities. Supabase supplies PostgreSQL, realtime subscriptions, storage, and likely authentication. Environment templates are provided at `backend/ai/.env.example` and `dashboard/.env.example`.

Main entry points: [`dashboard/src/components/Dashboard.jsx`](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/Dashboard.jsx) (Operations workspace), [`mobile/lib/widgets/sos_button.dart`](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/widgets/sos_button.dart) (SOS capture flow), [`mobile/lib/services/api_service.dart`](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/api_service.dart) (Alert API client), [`backend/ai/main.py`](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/ai/main.py) (AI enrichment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Flutter mobile app"]
  node_mobile_app["Mobile app shell<br/>Flutter/Dart<br/>[main.dart]"]
  node_sos_flow["SOS capture flow<br/>Flutter UI<br/>[sos_button.dart]"]
  node_location["Location service<br/>mobile service"]
  node_offline_queue["Offline queue<br/>mobile persistence"]
  node_mobile_api["Alert API client<br/>mobile service<br/>[api_service.dart]"]
  node_mobile_supabase["Mobile Supabase client<br/>mobile integration"]
  node_shake_service["Shake detection<br/>Android/Kotlin"]
end

subgraph group_backend["Backend services"]
  node_node_api{{"Node API proxy<br/>Node.js service<br/>[index.js]"}}
  node_ai_service{{"AI enrichment API<br/>Python/FastAPI<br/>[main.py]"}}
  node_ai_runtime["AI dependencies<br/>Python runtime<br/>[requirements.txt]"]
end

subgraph group_data["Shared data platform"]
  node_supabase[("Supabase<br/>PostgreSQL + Realtime")]
  node_schema["Database schema<br/>SQL bootstrap<br/>[database_setup.sql]"]
end

subgraph group_dashboard["Agency dashboard"]
  node_dashboard_app["Dashboard shell<br/>React/Vite<br/>[App.jsx]"]
  node_operations["Operations workspace<br/>React components<br/>[Dashboard.jsx]"]
  node_map_view["Incident map<br/>React view<br/>[Map.jsx]"]
  node_incident_list["Incident triage list<br/>React view<br/>[IncidentList.jsx]"]
  node_response_panel["Response detail panel<br/>React view<br/>[RightPanel.jsx]"]
  node_dashboard_supabase["Dashboard Supabase client<br/>React integration<br/>[supabase.js]"]
end

node_mobile_app -->|"hosts"| node_sos_flow
node_shake_service -->|"triggers"| node_sos_flow
node_sos_flow -->|"collects context"| node_location
node_sos_flow -->|"queues offline"| node_offline_queue
node_location -->|"adds location"| node_mobile_api
node_offline_queue -.->|"retries alerts"| node_mobile_api
node_mobile_api -->|"submits SOS"| node_node_api
node_node_api -->|"proxies alert"| node_ai_service
node_ai_runtime -->|"runs models"| node_ai_service
node_ai_service -->|"stores enriched incident"| node_supabase
node_schema -->|"defines schema"| node_supabase
node_mobile_supabase -->|"reads history and updates"| node_supabase
node_supabase -.->|"publishes changes"| node_mobile_supabase
node_dashboard_app -->|"renders"| node_operations
node_operations -->|"coordinates"| node_map_view
node_operations -->|"coordinates"| node_incident_list
node_operations -->|"coordinates"| node_response_panel
node_operations -->|"uses"| node_dashboard_supabase
node_dashboard_supabase -->|"subscribes and updates"| node_supabase
node_supabase -.->|"publishes realtime incidents"| node_dashboard_supabase

click node_mobile_app "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/main.dart"
click node_sos_flow "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/widgets/sos_button.dart"
click node_location "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/location_service.dart"
click node_offline_queue "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/offline_queue_service.dart"
click node_mobile_api "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/api_service.dart"
click node_mobile_supabase "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/supabase_service.dart"
click node_shake_service "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/android/app/src/main/kotlin/com/safealert/safe_alert/ShakeDetectionService.kt"
click node_node_api "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/api/index.js"
click node_ai_service "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/ai/main.py"
click node_ai_runtime "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/ai/requirements.txt"
click node_schema "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/docs/database_setup.sql"
click node_dashboard_app "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/App.jsx"
click node_operations "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/Dashboard.jsx"
click node_map_view "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/Map.jsx"
click node_incident_list "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/IncidentList.jsx"
click node_response_panel "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/RightPanel.jsx"
click node_dashboard_supabase "https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/lib/supabase.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_mobile_app,node_sos_flow,node_location,node_offline_queue,node_mobile_api,node_mobile_supabase,node_shake_service toneBlue
class node_node_api,node_ai_service,node_ai_runtime toneAmber
class node_supabase,node_schema toneMint
class node_dashboard_app,node_operations,node_map_view,node_incident_list,node_response_panel,node_dashboard_supabase toneRose
```

## Components

### Flutter mobile app

- [Mobile app shell](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/main.dart): Flutter/Dart · Starts the victim app and home flow. · `mobile/lib/main.dart`
- [SOS capture flow](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/widgets/sos_button.dart): Flutter UI · Captures manual SOS and confirmation. · `mobile/lib/widgets/sos_button.dart`
- [Location service](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/location_service.dart): mobile service · `mobile/lib/services/location_service.dart`
- [Offline queue](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/offline_queue_service.dart): mobile persistence · Retains alerts for retry when disconnected. · `mobile/lib/services/offline_queue_service.dart`
- [Alert API client](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/api_service.dart): mobile service · `mobile/lib/services/api_service.dart`
- [Mobile Supabase client](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/lib/services/supabase_service.dart): mobile integration · `mobile/lib/services/supabase_service.dart`
- [Shake detection](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/mobile/android/app/src/main/kotlin/com/safealert/safe_alert/ShakeDetectionService.kt): Android/Kotlin · Background SOS trigger with reboot restoration. · `mobile/android/app/src/main/kotlin/com/safealert/safe_alert/ShakeDetectionService.kt`

### Backend services

- [Node API proxy](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/api/index.js): Node.js service · Separate JavaScript API runtime. · `backend/api/index.js`
- [AI enrichment API](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/ai/main.py): Python/FastAPI · Classifies severity, handles language/transcription, and routes alerts. · `backend/ai/main.py`
- [AI dependencies](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/backend/ai/requirements.txt): Python runtime · Provides model and speech-recognition capabilities. · `backend/ai/requirements.txt`

### Shared data platform

- **Supabase**: PostgreSQL + Realtime · System of record and live-update bus.
- [Database schema](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/docs/database_setup.sql): SQL bootstrap · Defines incident data and feature migrations. · `docs/database_setup.sql`

### Agency dashboard

- [Dashboard shell](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/App.jsx): React/Vite · Assembles agency operations UI. · `dashboard/src/App.jsx`
- [Operations workspace](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/Dashboard.jsx): React components · Coordinates map, incident list, detail panel, and response controls. · `dashboard/src/components/Dashboard.jsx`
- [Incident map](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/Map.jsx): React view · `dashboard/src/components/Map.jsx`
- [Incident triage list](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/IncidentList.jsx): React view · `dashboard/src/components/IncidentList.jsx`
- [Response detail panel](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/components/RightPanel.jsx): React view · Lets responders update incident lifecycle state. · `dashboard/src/components/RightPanel.jsx`
- [Dashboard Supabase client](https://github.com/the-bhuvi/codehathon-4.0-sos-app/blob/main/dashboard/src/lib/supabase.js): React integration · Subscribes to and updates shared incidents. · `dashboard/src/lib/supabase.js`

## Connections

- Mobile app shell → SOS capture flow: hosts
- Shake detection → SOS capture flow: triggers
- SOS capture flow → Location service: collects context
- SOS capture flow → Offline queue: queues offline
- Location service → Alert API client: adds location
- Offline queue → Alert API client: retries alerts
- Alert API client → Node API proxy: submits SOS
- Node API proxy → AI enrichment API: proxies alert
- AI dependencies → AI enrichment API: runs models
- AI enrichment API → Supabase: stores enriched incident
- Database schema → Supabase: defines schema
- Mobile Supabase client → Supabase: reads history and updates
- Supabase → Mobile Supabase client: publishes changes
- Dashboard shell → Operations workspace: renders
- Operations workspace → Incident map: coordinates
- Operations workspace → Incident triage list: coordinates
- Operations workspace → Response detail panel: coordinates
- Operations workspace → Dashboard Supabase client: uses
- Dashboard Supabase client → Supabase: subscribes and updates
- Supabase → Dashboard Supabase client: publishes realtime incidents