the-bhuvi/codehathon-4.0-sos-app

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.