# imadbnr1/depannage-dz architecture

> Architecture diagram of the GitHub repository imadbnr1/depannage-dz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imadbnr1/depannage-dz
- Repository: https://github.com/imadbnr1/depannage-dz

## Overview

1. **System boundary**
   - Auto Rescue is a **Flutter client** that runs on **Android and web**, backed by **Firebase** services. The app is not a traditional client/server split with a custom API layer; most business state lives in **Firestore**, with a small **Cloud Functions** layer for map/routing/search proxying.

2. **Primary product flows**
   - The app is organized around three operational roles: **customer**, **provider**, and **admin**. Each role has its own page set and action model, but they share the same auth, localization, notification, and storage infrastructure.

3. **UI architecture**
   - `lib/features/` is the main presentation boundary:
     - `auth/` handles login, signup, and auth gating.
     - `customer/` covers order creation, request tracking, history, profile, support.
     - `provider/` covers availability, mission offers, tracking, earnings, history.
     - `admin/` covers dashboard, analytics, pricing, notifications, support config, logs.
     - `shared/` contains cross-role screens like chat, onboarding, splash, permissions, legal.
   - `lib/widgets/` holds reusable UI building blocks such as map markers, status chips, bottom nav, panels, and alert overlays.

4. **State management and orchestration**
   - The central runtime coordinator is `lib/state/app_store.dart`, built on **Provider / ChangeNotifier**.
   - `AppStore` manages the app’s cross-screen state: authentication-aware subscriptions, request streams, provider availability, dispatch chain state, live tracking, notifications, tab state, and mission lifecycle transitions.
   - This is the main place where the UI is coupled to backend-driven realtime state.

5. **Domain and data access layers**
   - Shared domain entities live in `lib/models/` and `lib/core/models/`.
   - `lib/repositories/` isolates Firestore access for requests and tracking, so feature pages do not talk directly to Firebase for core mission data.
   - This gives the architecture a clear boundary between **UI state**, **domain objects**, and **persistent storage**.

6. **Backend services layer**
   - `lib/core/services/` contains the main integration services:
     - **Auth** and user profile lookup
     - **Location / geocoding / place search**
     - **Routing** and navigation launch
     - **Notifications** via FCM and local alerts
     - **Provider presence** and realtime availability
     - **Audit / admin logging**
     - **CSV export** for admin reporting
   - These services are the integration layer between Flutter and Firebase/external map providers.

7. **Dispatch and mission lifecycle**
   - The most important business flow is the **request dispatch chain**:
     1. Customer creates a request in Firestore with status `searching`.
     2. Eligible providers are filtered by online/busy/approved state and sorted by distance.
     3. Offers are sent one provider at a time with a timeout.
     4. Rejection/timeout advances the chain.
     5. If nobody accepts, the customer gets a no-provider-accepted state and can retry or cancel.
   - This flow is stateful and is coordinated across `AppStore`, Firestore request documents, and provider mission pages.

8. **Realtime tracking and maps**
   - Tracking screens use **flutter_map**, **OpenStreetMap tiles**, **Geolocator**, and route polylines to show customer/provider/destination movement.
   - `RouteService` abstracts route calculation and supports multiple providers with fallback behavior.
   - A notable boundary is that route/search/geocode work may be proxied through **Cloud Functions** so the frontend does not hold private routing keys.

9. **Notifications and presence**
   - Messaging and alerts are split across several channels:
     - **Firebase Cloud Messaging** for push delivery
     - **Local notifications** for in-app/device presentation
     - **In-app notification service** for foreground UX
     - **Chat messages** stored in Firestore
   - Provider availability is mirrored through **Firebase Realtime Database** at `presence/providers/{providerUid}`, then reflected into Firestore fields such as online/busy/seen state for dispatch decisions.

10. **Security and administration**
    - Firebase security rules are a major architectural boundary:
      - `firestore.rules` controls role-scoped access to users, providers, requests, chats, logs, config, and notifications.
      - `storage.rules` constrains uploads.
    - Admin-only capabilities include provider approval/blocking, pricing, notifications, analytics, support configuration, and audit inspection.
    - Provider accounts are intentionally gated by approval before they can receive missions.

11. **Localization and app-wide UX**
    - The app supports **French, English, and Arabic** via `lib/core/i18n/`.
    - Language selection is persisted, and Arabic requires RTL-aware UI behavior.
    - This is a cross-cutting concern shared by auth, customer, provider, admin, and shared screens.

12. **Deployment and infrastructure**
    - Firebase project config is committed for client use: `firebase_options.dart`, `google-services.json`, `firebase.json`, plus hosting and messaging assets.
    - Web push support is backed by `web/firebase-messaging-sw.js`.
    - Cloud Functions expose map/search endpoints such as `mapSearch`, `reverseGeocode`, `nearbyPlaces`, and `routeDirections`.
    - The repo also includes assets for logos and sounds, plus Flutter/Android scaffolding for mobile deployment.

Main entry points: [`lib/core/services/auth_service.dart`](https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/services/auth_service.dart) (Core services), [`lib/state/app_store.dart`](https://github.com/imadbnr1/depannage-dz/blob/main/lib/state/app_store.dart) (App store), [`lib/app/auto_rescue.dart`](https://github.com/imadbnr1/depannage-dz/blob/main/lib/app/auto_rescue.dart) (Root app), [`lib/features/customer/pages/customer_shell_page.dart`](https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/customer/pages/customer_shell_page.dart) (Customer flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Flutter App"]
  node_node_main["App entry<br/>Flutter bootstrap<br/>[main.dart]"]
  node_node_app["Root app<br/>App shell<br/>[auto_rescue.dart]"]
  node_node_store["App store<br/>State coordinator<br/>[app_store.dart]"]
  node_node_auth["Auth flow<br/>Feature screens<br/>[auth_gate.dart]"]
  node_node_customer["Customer flow<br/>Customer UI"]
  node_node_provider["Provider flow<br/>Provider UI"]
  node_node_admin["Admin flow<br/>Admin UI"]
  node_node_shared["Shared screens<br/>Cross-role UI<br/>[splash_page.dart]"]
  node_node_widgets["UI widgets<br/>Reusable components"]
  node_node_models["Domain models<br/>Entities<br/>[app_request.dart]"]
  node_node_core_models["Core models<br/>Shared entities<br/>[app_user.dart]"]
  node_node_repos["Data repos<br/>Firestore access"]
  node_node_services["Core services<br/>Integration layer<br/>[auth_service.dart]"]
  node_node_i18n["Localization<br/>i18n"]
end

subgraph group_group_backend["Firebase Backend"]
  node_node_functions["Cloud functions<br/>Backend functions<br/>[index.js]"]
  node_node_rules_fs["Firestore rules<br/>Security rules<br/>[firestore.rules]"]
  node_node_rules_storage["Storage rules<br/>Security rules<br/>[storage.rules]"]
  node_node_firebase_json["Firebase config<br/>Project config<br/>[firebase.json]"]
end

subgraph group_group_platform["Platform & Assets"]
  node_node_android["Android app<br/>Native shell"]
  node_node_web["Web client<br/>Web shell<br/>[index.html]"]
  node_node_assets["Assets<br/>Media bundle<br/>[applogo.rar]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"provides state"| node_node_store
node_node_store -->|"gates"| node_node_auth
node_node_store -->|"drives"| node_node_customer
node_node_store -->|"drives"| node_node_provider
node_node_store -->|"drives"| node_node_admin
node_node_store -->|"shares"| node_node_shared
node_node_customer -->|"reads/writes"| node_node_repos
node_node_provider -->|"reads/writes"| node_node_repos
node_node_admin -->|"uses"| node_node_services
node_node_customer -->|"uses"| node_node_services
node_node_provider -->|"uses"| node_node_services
node_node_services -->|"proxies"| node_node_functions
node_node_services -.->|"constrained by"| node_node_rules_fs
node_node_repos -.->|"constrained by"| node_node_rules_fs
node_node_services -.->|"uploads bounded by"| node_node_rules_storage
node_node_services -.->|"configured by"| node_node_firebase_json
node_node_store -->|"uses"| node_node_models
node_node_repos -->|"persists"| node_node_models
node_node_services -->|"uses"| node_node_core_models
node_node_app -->|"localizes"| node_node_i18n
node_node_customer -->|"composes"| node_node_widgets
node_node_provider -->|"composes"| node_node_widgets
node_node_admin -->|"composes"| node_node_widgets
node_node_web -->|"integrates"| node_node_services
node_node_android -->|"packages"| node_node_app
node_node_assets -->|"supplies"| node_node_app

click node_node_main "https://github.com/imadbnr1/depannage-dz/blob/main/lib/main.dart"
click node_node_app "https://github.com/imadbnr1/depannage-dz/blob/main/lib/app/auto_rescue.dart"
click node_node_store "https://github.com/imadbnr1/depannage-dz/blob/main/lib/state/app_store.dart"
click node_node_auth "https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/auth/pages/auth_gate.dart"
click node_node_customer "https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/customer/pages/customer_shell_page.dart"
click node_node_provider "https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/provider/pages/provider_shell_page.dart"
click node_node_admin "https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/admin/pages/admin_dashboard_page.dart"
click node_node_shared "https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/shared/pages/splash_page.dart"
click node_node_widgets "https://github.com/imadbnr1/depannage-dz/blob/main/lib/widgets/modern_bottom_nav_bar.dart"
click node_node_models "https://github.com/imadbnr1/depannage-dz/blob/main/lib/models/app_request.dart"
click node_node_core_models "https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/models/app_user.dart"
click node_node_repos "https://github.com/imadbnr1/depannage-dz/blob/main/lib/repositories/firestore_request_repository.dart"
click node_node_services "https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/services/auth_service.dart"
click node_node_i18n "https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/i18n/app_localizations.dart"
click node_node_functions "https://github.com/imadbnr1/depannage-dz/blob/main/functions/index.js"
click node_node_rules_fs "https://github.com/imadbnr1/depannage-dz/blob/main/firestore.rules"
click node_node_rules_storage "https://github.com/imadbnr1/depannage-dz/blob/main/storage.rules"
click node_node_firebase_json "https://github.com/imadbnr1/depannage-dz/blob/main/firebase.json"
click node_node_android "https://github.com/imadbnr1/depannage-dz/blob/main/android/app/src/main/AndroidManifest.xml"
click node_node_web "https://github.com/imadbnr1/depannage-dz/blob/main/web/index.html"
click node_node_assets "https://github.com/imadbnr1/depannage-dz/blob/main/assets/logo/applogo.rar"

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_node_main,node_node_app,node_node_store,node_node_auth,node_node_customer,node_node_provider,node_node_admin,node_node_shared,node_node_widgets,node_node_models,node_node_core_models,node_node_repos,node_node_services,node_node_i18n toneBlue
class node_node_functions,node_node_rules_fs,node_node_rules_storage,node_node_firebase_json toneAmber
class node_node_android,node_node_web,node_node_assets toneMint
```

## Components

### Flutter App

Client runtime, UI, state, domain, and shared widgets.

- [App entry](https://github.com/imadbnr1/depannage-dz/blob/main/lib/main.dart): Flutter bootstrap · Application startup and top-level wiring. · `lib/main.dart`
- [Root app](https://github.com/imadbnr1/depannage-dz/blob/main/lib/app/auto_rescue.dart): App shell · Top-level app composition and navigation setup. · `lib/app/auto_rescue.dart`
- [App store](https://github.com/imadbnr1/depannage-dz/blob/main/lib/state/app_store.dart): State coordinator · Central ChangeNotifier coordinating auth-aware realtime app state. · `lib/state/app_store.dart`
- [Auth flow](https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/auth/pages/auth_gate.dart): Feature screens · Login, signup, and auth gating. · `lib/features/auth/pages/auth_gate.dart`
- [Customer flow](https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/customer/pages/customer_shell_page.dart): Customer UI · Order creation, request tracking, history, profile, support, and rating. · `lib/features/customer/pages/customer_shell_page.dart`
- [Provider flow](https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/provider/pages/provider_shell_page.dart): Provider UI · Availability, mission offers, tracking, earnings, history, and provider profile. · `lib/features/provider/pages/provider_shell_page.dart`
- [Admin flow](https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/admin/pages/admin_dashboard_page.dart): Admin UI · Dashboard, analytics, pricing, notifications, support config, and logs. · `lib/features/admin/pages/admin_dashboard_page.dart`
- [Shared screens](https://github.com/imadbnr1/depannage-dz/blob/main/lib/features/shared/pages/splash_page.dart): Cross-role UI · Onboarding, splash, permissions, legal, chat, and receipt screens. · `lib/features/shared/pages/splash_page.dart`
- [UI widgets](https://github.com/imadbnr1/depannage-dz/blob/main/lib/widgets/modern_bottom_nav_bar.dart): Reusable components · Shared map markers, chips, navigation, panels, overlays, and loading states. · `lib/widgets/modern_bottom_nav_bar.dart`
- [Domain models](https://github.com/imadbnr1/depannage-dz/blob/main/lib/models/app_request.dart): Entities · Core app request, role, provider, message, notification, route, and config models. · `lib/models/app_request.dart`
- [Core models](https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/models/app_user.dart): Shared entities · App-wide user and search result models. · `lib/core/models/app_user.dart`
- [Data repos](https://github.com/imadbnr1/depannage-dz/blob/main/lib/repositories/firestore_request_repository.dart): Firestore access · Repository boundary for request and tracking persistence. · `lib/repositories/firestore_request_repository.dart`
- [Core services](https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/services/auth_service.dart): Integration layer · Auth, location, routing, notifications, presence, audit, export, and launch services. · `lib/core/services/auth_service.dart`
- [Localization](https://github.com/imadbnr1/depannage-dz/blob/main/lib/core/i18n/app_localizations.dart): i18n · Language controller, translations, and RTL-aware UX support. · `lib/core/i18n/app_localizations.dart`

### Firebase Backend

Firestore, Cloud Functions, messaging, and rules boundaries.

- [Cloud functions](https://github.com/imadbnr1/depannage-dz/blob/main/functions/index.js): Backend functions · Map search, geocoding, nearby places, and routing proxy endpoints. · `functions/index.js`
- [Firestore rules](https://github.com/imadbnr1/depannage-dz/blob/main/firestore.rules): Security rules · Role-scoped access control for users, requests, chats, logs, config, and notifications. · `firestore.rules`
- [Storage rules](https://github.com/imadbnr1/depannage-dz/blob/main/storage.rules): Security rules · Upload constraints for stored files. · `storage.rules`
- [Firebase config](https://github.com/imadbnr1/depannage-dz/blob/main/firebase.json): Project config · Firebase hosting and app configuration. · `firebase.json`

### Platform & Assets

Android, web, and bundled deployment assets.

- [Android app](https://github.com/imadbnr1/depannage-dz/blob/main/android/app/src/main/AndroidManifest.xml): Native shell · Android build and platform integration. · `android/app/src/main/AndroidManifest.xml`
- [Web client](https://github.com/imadbnr1/depannage-dz/blob/main/web/index.html): Web shell · Web entrypoint, manifest, and service worker for push messaging. · `web/index.html`
- [Assets](https://github.com/imadbnr1/depannage-dz/blob/main/assets/logo/applogo.rar): Media bundle · Logos and sounds used by the client. · `assets/logo/applogo.rar`

## Connections

- App entry → Root app: boots · Main launches the app shell.
- Root app → App store: provides state · Root app wires global state into the UI tree.
- App store → Auth flow: gates · Auth state controls access to role flows.
- App store → Customer flow: drives · Customer screens reflect store-managed mission state.
- App store → Provider flow: drives · Provider screens reflect availability and dispatch state.
- App store → Admin flow: drives · Admin screens consume shared realtime state and logs.
- App store → Shared screens: shares · Common screens use the same global app state.
- Customer flow → Data repos: reads/writes · Customer mission pages use the repository boundary for requests.
- Provider flow → Data repos: reads/writes · Provider mission pages use the repository boundary for tracking and requests.
- Admin flow → Core services: uses · Admin actions rely on service integrations such as audit and export.
- Customer flow → Core services: uses · Customer flow uses maps, notifications, and location services.
- Provider flow → Core services: uses · Provider flow uses presence, tracking, routing, and alerts.
- Core services → Cloud functions: proxies · Map and routing requests may be proxied through Cloud Functions.
- Core services → Firestore rules: constrained by · Service writes and reads are bounded by Firestore rules.
- Data repos → Firestore rules: constrained by · Repository access is governed by Firestore security rules.
- Core services → Storage rules: uploads bounded by · File uploads are constrained by storage rules.
- Core services → Firebase config: configured by · Firebase project settings and hosting configuration apply to services.
- App store → Domain models: uses · Global state is built on shared domain models.
- Data repos → Domain models: persists · Repositories store and hydrate domain objects.
- Core services → Core models: uses · Integration services use shared core models.
- Root app → Localization: localizes · App shell applies localization across the UI.
- Customer flow → UI widgets: composes · Customer pages are built from reusable widgets.
- Provider flow → UI widgets: composes · Provider pages are built from reusable widgets.
- Admin flow → UI widgets: composes · Admin pages reuse shared UI widgets.
- Web client → Core services: integrates · Web client uses messaging and Firebase integrations.
- Android app → Root app: packages · Android shell packages the Flutter app.
- Assets → Root app: supplies · App uses bundled logos and sounds.