# hariom317/vsafe-women-safety-app architecture

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

- Interactive diagram: https://gitdiagram.com/hariom317/vsafe-women-safety-app
- Repository: https://github.com/hariom317/vsafe-women-safety-app

## Overview

1. **Repository shape**
   - This is a **Flutter cross-platform mobile app** with generated platform shells for Android, iOS, web, Windows, macOS, and Linux.
   - The actual product logic lives almost entirely under `lib/`; the native folders are thin launch/bridge layers.

2. **App entry and shell**
   - `lib/main.dart` is the Dart entry point and likely decides the initial route and global app setup.
   - Platform-specific runners (`android/.../MainActivity.kt`, `ios/Runner/AppDelegate.swift`, etc.) only host the Flutter runtime; they are not where the app’s domain logic lives.

3. **Primary product boundary: safety app UI**
   - The UI is organized by feature area:
     - `intro_pages` for splash/onboarding
     - `user` for sign-up/login/profile recovery
     - `navbar_pages` for the main post-login tabs
     - `required_pages` for core safety flows
     - `widgets` and `components` for reusable UI parts
   - This gives the architecture a clear split between **authentication/onboarding** and the **main safety dashboard**.

4. **Authentication and user lifecycle**
   - `lib/src/user/` contains the account flow: welcome screen, login, registration, password reset, email/OTP verification, and profile update.
   - This is the app’s front door and likely gates access to all safety and communication features.
   - User identity is represented in `lib/src/model/user_model.dart`, suggesting the app stores a structured profile separate from UI.

5. **Main navigation and feature hub**
   - `lib/src/widgets/bottom_nav_bar.dart` and `lib/src/widgets/drawer_widgets/screen_drawer.dart` indicate two major navigation surfaces:
     - a bottom tab bar for primary workflows
     - a drawer for secondary settings/help/legal screens
   - `navbar_pages/home_screen.dart`, `chat_screen.dart`, `fake_call_screen.dart`, and `profile_screen.dart` suggest the core app is centered around these four main sections.

6. **Safety operations subsystem**
   - The home experience is decomposed into focused widgets:
     - `emergency.dart` for SOS actions
     - `nearby_map_service.dart` for map/location-based assistance
     - `safety_tips.dart` and `situation.dart` for guidance and contextual content
     - `custom_carousel.dart` for surfaced content on the home page
   - The feature set from the README—SOS, shake-trigger alerts, emergency contacts, and real-time location sharing—appears to live here.

7. **Emergency and fake-call flows**
   - `required_pages/fake_call.dart`, `incoming_fake_call.dart`, and `navbar_pages/fake_call_screen.dart` model a dedicated **de-escalation/escape** flow.
   - `flutter_background_services.dart` implies background execution is used for time-sensitive behaviors like shake detection or alerting while the app is not foregrounded.
   - `assets/audio/caller_tune.mp3` supports the fake-call experience with realistic ringing audio.

8. **Chat and contact subsystem**
   - `lib/src/chat/` contains the full one-to-one messaging stack: user cards, message cards, profile dialog, user chat screen, and profile viewing.
   - `lib/src/model/contact_model.dart` and `user_message.dart` define the data boundary for contacts and chat messages.
   - `chat/apis.dart` and `db/db_services.dart` suggest backend/persistence access is abstracted away from the UI, likely to Firebase or another cloud datastore as described in the README.

9. **Persistence and lightweight local state**
   - `db_services.dart` and `share_pref.dart` indicate two storage layers:
     - app/database services for structured records
     - shared preferences for local flags or session-like state
   - This likely supports remembered login state, onboarding completion, profile cache, and possibly selected settings.

10. **Support content and informational surfaces**
   - The app includes non-transactional content flows for safety education and support:
     - `drawer_widgets/help_page.dart`, `privacy_policy_page.dart`, `terms_and_conditions.dart`, `feedback_page.dart`, `notification_page.dart`, `setting_page.dart`
     - `required_pages/chatbot.dart` for guided assistance
   - These are important because the app is not only operational SOS tooling; it also provides guidance, policy, and support content.

11. **Content-heavy asset pipeline**
   - The `assets/` tree is a major part of the product: Lottie animations, intro imagery, safety-tip images, and safety-training videos.
   - This indicates the app leans heavily on **rich educational and onboarding media** rather than plain text-only screens.
   - The architecture therefore includes a presentation/content layer as a first-class subsystem.

12. **Backend and platform integration boundaries**
   - The README states Firebase is used for backend services, and `ios/Runner/GoogleService-Info.plist` confirms Firebase configuration on iOS.
   - The code layout suggests cloud-backed features for authentication, messaging, and possibly notifications/location services, while native code remains minimal.
   - In a diagram, the key boundaries are: **Flutter UI layer → app services/data layer → Firebase/backend services**, with native runners acting only as platform hosts.

Main entry points: [`lib/main.dart`](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/main.dart) (Main), [`lib/src/widgets/bottom_nav_bar.dart`](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/bottom_nav_bar.dart) (Nav shell), [`lib/src/pages/navbar_pages/home_screen.dart`](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/home_screen.dart) (Home hub), [`lib/src/user/login_screen.dart`](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/user/login_screen.dart) (Auth flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter_app["Flutter app"]
  node_main["Main<br/>entrypoint<br/>[main.dart]"]
  node_intro_flow["Intro flow<br/>onboarding"]
  node_auth_flow["Auth flow<br/>account<br/>[login_screen.dart]"]
  node_user_profile_model[("User model<br/>[user_model.dart]")]
  node_home_hub["Home hub<br/>dashboard<br/>[home_screen.dart]"]
  node_nav_shell["Nav shell<br/>navigation"]
  node_profile_screen["Profile<br/>account-ui"]
  node_chat_screen["Chat<br/>messaging<br/>[chat_screen.dart]"]
  node_chat_stack["Chat stack<br/>messaging-components"]
  node_contact_model[("Contact data<br/>model<br/>[contact_model.dart]")]
  node_db_services["DB services<br/>persistence<br/>[db_services.dart]"]
  node_share_pref["Prefs<br/>local-state<br/>[share_pref.dart]"]
  node_safety_widgets["Safety widgets<br/>safety-ui<br/>[emergency.dart]"]
  node_fake_call_flow["Fake call<br/>de-escalation<br/>[fake_call.dart]"]
  node_background_services["Background svc<br/>runtime"]
  node_support_pages["Support pages<br/>info<br/>[screen_drawer.dart]"]
  node_chatbot_page["Chatbot<br/>assistant<br/>[chatbot.dart]"]
  node_shared_ui["Shared UI<br/>components"]
end

subgraph group_platform_hosts["Platform hosts"]
  node_android_runner["Android<br/>native-host<br/>[MainActivity.kt]"]
  node_ios_runner["iOS<br/>native-host<br/>[AppDelegate.swift]"]
  node_desktop_web_hosts["Desktop/Web<br/>native-host<br/>[index.html]"]
end

subgraph group_assets["Assets"]
  node_media_assets["Media assets<br/>content-pack<br/>[sos.json]"]
end

node_main -->|"starts"| node_intro_flow
node_main -->|"routes"| node_auth_flow
node_main -->|"opens"| node_home_hub
node_intro_flow -->|"uses"| node_media_assets
node_auth_flow -->|"writes"| node_user_profile_model
node_auth_flow -->|"uses"| node_shared_ui
node_home_hub -->|"contained in"| node_nav_shell
node_nav_shell -->|"switches to"| node_profile_screen
node_nav_shell -->|"switches to"| node_chat_screen
node_nav_shell -->|"hosts"| node_safety_widgets
node_nav_shell -->|"opens"| node_support_pages
node_home_hub -->|"triggers"| node_fake_call_flow
node_home_hub -->|"offers"| node_chatbot_page
node_safety_widgets -->|"depends on"| node_background_services
node_fake_call_flow -->|"plays"| node_media_assets
node_chat_screen -->|"navigates to"| node_chat_stack
node_chat_stack -->|"reads"| node_contact_model
node_chat_stack -->|"syncs"| node_db_services
node_db_services -->|"uses"| node_share_pref
node_db_services -->|"persists"| node_user_profile_model
node_support_pages -->|"uses"| node_media_assets
node_android_runner -->|"hosts"| node_main
node_ios_runner -->|"hosts"| node_main
node_desktop_web_hosts -->|"hosts"| node_main

click node_main "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/main.dart"
click node_intro_flow "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/intro_pages/onboarding_screen.dart"
click node_auth_flow "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/user/login_screen.dart"
click node_user_profile_model "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/model/user_model.dart"
click node_home_hub "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/home_screen.dart"
click node_nav_shell "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/bottom_nav_bar.dart"
click node_profile_screen "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/profile_screen.dart"
click node_chat_screen "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/chat_screen.dart"
click node_chat_stack "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/chat/user_chat_screen.dart"
click node_contact_model "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/model/contact_model.dart"
click node_db_services "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/db/db_services.dart"
click node_share_pref "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/db/share_pref.dart"
click node_safety_widgets "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/home_widgets/emergency.dart"
click node_fake_call_flow "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/required_pages/fake_call.dart"
click node_background_services "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/utils/flutter_background_services.dart"
click node_support_pages "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/drawer_widgets/screen_drawer.dart"
click node_chatbot_page "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/required_pages/chatbot.dart"
click node_shared_ui "https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/components/custom_textfield.dart"
click node_android_runner "https://github.com/hariom317/vsafe-women-safety-app/blob/master/android/app/src/main/kotlin/com/safety/vsafe/MainActivity.kt"
click node_ios_runner "https://github.com/hariom317/vsafe-women-safety-app/blob/master/ios/Runner/AppDelegate.swift"
click node_desktop_web_hosts "https://github.com/hariom317/vsafe-women-safety-app/blob/master/web/index.html"
click node_media_assets "https://github.com/hariom317/vsafe-women-safety-app/blob/master/assets/animations/intro_app_animations/sos.json"

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_main,node_intro_flow,node_auth_flow,node_user_profile_model,node_home_hub,node_nav_shell,node_profile_screen,node_chat_screen,node_chat_stack,node_contact_model,node_db_services,node_share_pref,node_safety_widgets,node_fake_call_flow,node_background_services,node_support_pages,node_chatbot_page,node_shared_ui toneBlue
class node_android_runner,node_ios_runner,node_desktop_web_hosts toneAmber
class node_media_assets toneMint
```

## Components

### Flutter app

Dart application logic and UI

- [Main](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/main.dart): entrypoint · Dart app entry and bootstrap · `lib/main.dart`
- [Intro flow](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/intro_pages/onboarding_screen.dart): onboarding · Splash and onboarding screens · `lib/src/pages/intro_pages/onboarding_screen.dart`
- [Auth flow](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/user/login_screen.dart): account · Login, registration, reset and verification · `lib/src/user/login_screen.dart`
- [User model](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/model/user_model.dart): model · Structured user profile data · `lib/src/model/user_model.dart`
- [Home hub](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/home_screen.dart): dashboard · Post-login safety dashboard · `lib/src/pages/navbar_pages/home_screen.dart`
- [Nav shell](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/bottom_nav_bar.dart): navigation · Bottom tabs and drawer navigation · `lib/src/widgets/bottom_nav_bar.dart`
- [Profile](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/profile_screen.dart): account-ui · User profile and account view · `lib/src/pages/navbar_pages/profile_screen.dart`
- [Chat](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/navbar_pages/chat_screen.dart): messaging · Main messaging entry screen · `lib/src/pages/navbar_pages/chat_screen.dart`
- [Chat stack](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/chat/user_chat_screen.dart): messaging-components · User cards, messages and profile dialogs · `lib/src/chat/user_chat_screen.dart`
- [Contact data](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/model/contact_model.dart): model · Contacts and message records · `lib/src/model/contact_model.dart`
- [DB services](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/db/db_services.dart): persistence · Backend and record access layer · `lib/src/db/db_services.dart`
- [Prefs](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/db/share_pref.dart): local-state · Local flags and session state · `lib/src/db/share_pref.dart`
- [Safety widgets](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/home_widgets/emergency.dart): safety-ui · SOS, nearby map, tips and situation content · `lib/src/widgets/home_widgets/emergency.dart`
- [Fake call](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/required_pages/fake_call.dart): de-escalation · Fake-call and incoming-call flow · `lib/src/pages/required_pages/fake_call.dart`
- [Background svc](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/utils/flutter_background_services.dart): runtime · Background execution for time-sensitive actions · `lib/src/utils/flutter_background_services.dart`
- [Support pages](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/widgets/drawer_widgets/screen_drawer.dart): info · Help, privacy, terms, settings and feedback · `lib/src/widgets/drawer_widgets/screen_drawer.dart`
- [Chatbot](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/pages/required_pages/chatbot.dart): assistant · Guided help and support assistant · `lib/src/pages/required_pages/chatbot.dart`
- [Shared UI](https://github.com/hariom317/vsafe-women-safety-app/blob/master/lib/src/components/custom_textfield.dart): components · Reusable buttons, text fields and routes · `lib/src/components/custom_textfield.dart`

### Platform hosts

Native launch shells and platform integration

- [Android](https://github.com/hariom317/vsafe-women-safety-app/blob/master/android/app/src/main/kotlin/com/safety/vsafe/MainActivity.kt): native-host · Flutter host shell for Android · `android/app/src/main/kotlin/com/safety/vsafe/MainActivity.kt`
- [iOS](https://github.com/hariom317/vsafe-women-safety-app/blob/master/ios/Runner/AppDelegate.swift): native-host · Flutter host shell for iOS · `ios/Runner/AppDelegate.swift`
- [Desktop/Web](https://github.com/hariom317/vsafe-women-safety-app/blob/master/web/index.html): native-host · Flutter host shells for web, Windows, macOS and Linux · `web/index.html`

### Assets

Media and content used by the app

- [Media assets](https://github.com/hariom317/vsafe-women-safety-app/blob/master/assets/animations/intro_app_animations/sos.json): content-pack · Animations, audio, images and videos · `assets/animations/intro_app_animations/sos.json`

## Connections

- Main → Intro flow: starts · Launches onboarding and splash experience
- Main → Auth flow: routes · Enters account setup and sign-in flows
- Main → Home hub: opens · Loads the main app shell after entry
- Intro flow → Media assets: uses · Displays onboarding animations and imagery
- Auth flow → User model: writes · Creates and updates structured user data
- Auth flow → Shared UI: uses · Builds forms and action controls
- Home hub → Nav shell: contained in · Runs inside the main tab and drawer shell
- Nav shell → Profile: switches to · One of the primary bottom-tab destinations
- Nav shell → Chat: switches to · One of the primary bottom-tab destinations
- Nav shell → Safety widgets: hosts · Primary dashboard content is composed from safety widgets
- Nav shell → Support pages: opens · Drawer exposes secondary support and settings pages
- Home hub → Fake call: triggers · Launches the de-escalation escape path
- Home hub → Chatbot: offers · Surfaces guided assistance from the dashboard
- Safety widgets → Background svc: depends on · Supports shake detection and alert timing in background
- Fake call → Media assets: plays · Uses ringing audio and fake-call visuals
- Chat → Chat stack: navigates to · Opens the one-to-one chat detail stack
- Chat stack → Contact data: reads · Renders contact and message records
- Chat stack → DB services: syncs · Fetches and stores chat data through backend services
- DB services → Prefs: uses · Combines cloud-backed data with local session state
- DB services → User model: persists · Stores user profile records
- Support pages → Media assets: uses · Displays help and informational content assets
- Android → Main: hosts · Android shell launches the Flutter entrypoint
- iOS → Main: hosts · iOS shell launches the Flutter entrypoint
- Desktop/Web → Main: hosts · Web and desktop shells launch the Flutter entrypoint