How imadbnr1/depannage-dz works
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: auth_service.dart Core services · app_store.dart App store · auto_rescue.dart Root app · customer_shell_page.dart Customer flow
Components 21
Flutter App
Client runtime, UI, state, domain, and shared widgets.
- App entry · Application startup and top-level wiring.
lib/main.dart - Root app · Top-level app composition and navigation setup.
lib/app/auto_rescue.dart - App store · Central ChangeNotifier coordinating auth-aware realtime app state.
lib/state/app_store.dart - Auth flow · Login, signup, and auth gating.
lib/features/auth/pages/auth_gate.dart - Customer flow · Order creation, request tracking, history, profile, support, and rating.
lib/features/customer/pages/customer_shell_page.dart - Provider flow · Availability, mission offers, tracking, earnings, history, and provider profile.
lib/features/provider/pages/provider_shell_page.dart - Admin flow · Dashboard, analytics, pricing, notifications, support config, and logs.
lib/features/admin/pages/admin_dashboard_page.dart - Shared screens · Onboarding, splash, permissions, legal, chat, and receipt screens.
lib/features/shared/pages/splash_page.dart - UI widgets · Shared map markers, chips, navigation, panels, overlays, and loading states.
lib/widgets/modern_bottom_nav_bar.dart - Domain models · Core app request, role, provider, message, notification, route, and config models.
lib/models/app_request.dart - Core models · App-wide user and search result models.
lib/core/models/app_user.dart - Data repos · Repository boundary for request and tracking persistence.
lib/repositories/firestore_request_repository.dart - Core services · Auth, location, routing, notifications, presence, audit, export, and launch services.
lib/core/services/auth_service.dart - Localization · 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 · Map search, geocoding, nearby places, and routing proxy endpoints.
functions/index.js - Firestore rules · Role-scoped access control for users, requests, chats, logs, config, and notifications.
firestore.rules - Storage rules · Upload constraints for stored files.
storage.rules - Firebase config · Firebase hosting and app configuration.
firebase.json
Platform & Assets
Android, web, and bundled deployment assets.
- Android app · Android build and platform integration.
android/app/src/main/AndroidManifest.xml - Web client · Web entrypoint, manifest, and service worker for push messaging.
web/index.html - Assets · Logos and sounds used by the client.
assets/logo/applogo.rar
Connections 27
- 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.