How louaygharsaly2025/madari_guardian works
1. System shape
Madari Guardian is a Flutter client application with a feature-rich mobile-first architecture. The core app logic lives in lib/, while Android/iOS/macOS/web/Windows/Linux folders are mostly platform shells and build scaffolding. The product is centered on real-time tracking, geofencing, emergency workflows, and device monitoring.
2. App bootstrap and shared foundation
lib/main.dart is the entry point and likely wires together Firebase initialization, routing, theming, and Riverpod-based state management. Shared configuration is split into lib/firebase_options.dart, assets/firebase_options.json, and the firebase.json deployment config, which indicates the app is tightly coupled to a Firebase project from startup onward.
3. Presentation layer
The lib/screens/ folder is organized by user workflow rather than technical layer: login, guardian dashboard, emergency dashboard, geofence management, history, trusted users, profile, settings, notifications, weekly reports, offline maps, chatbot, fake call, and user guide. This suggests a dashboard-style UX where most app behavior is exposed through dedicated feature screens instead of a single generic shell.
4. Domain models
lib/models/ contains the app’s main data contracts: alerts, device status, geofences, tracking logs, and users. These models define the shape of data moving between Firebase, background services, and UI screens, and they are the key boundary for drawing the domain layer in an architecture diagram.
5. Service layer as the main orchestration boundary
lib/services/ is the architectural center of the app. It includes authentication, Firebase access, location tracking, geofencing, background execution, sensor monitoring, connectivity, offline synchronization, remote commands, safety check-ins, fake calls, WhatsApp integration, localization, and theming. Most feature screens appear to depend on these services rather than talking to Firebase or device APIs directly.
6. Real-time tracking flow
The main runtime flow is: device sensors and location updates are captured by location_service, sensor_monitor_service, and background_service, then persisted or broadcast through firebase_service. On the UI side, tracking-related screens consume the resulting models to display live maps, device vitals, and activity history, with Google Maps providing the map visualization layer.
7. Geofencing and alerting
geofence_service and geofence_model form a dedicated boundary-monitoring subsystem. When a device enters or exits a zone, the app likely creates alert_model events that surface in the dashboard, notification settings, history, and emergency views. This subsystem is one of the primary event generators in the app.
8. Offline-first synchronization
The presence of connectivity_service and offline_sync_service shows that the app is designed to keep operating when network state changes. Local actions and captured telemetry can be buffered during disconnection and synchronized when connectivity returns, making offline handling a first-class architectural concern rather than an edge case.
9. Security and access control
auth_service handles Firebase authentication, while the README also calls out biometric access via local_auth and secure storage. On the backend side, firestore.rules indicates that Firestore security rules are part of the enforcement boundary, so access control exists in both the client and Firebase configuration.
10. Emergency and safety features
Several services are explicitly emergency-oriented: remote_command_service, fake_call_service, safety_checkin_service, and whatsapp_service. These support actions like ringing/locking a monitored device, triggering a fake call, check-ins, and sending alerts through external messaging channels, which makes the app more than a passive tracker.
11. UI polish, personalization, and multilingual support
theme_service, theme_colors, localization_service, and app_translations show that the app separates visual and language concerns from core tracking logic. The README’s mention of glassmorphic design and multiple fonts suggests a premium UI layer that is intentionally isolated from the domain services.
12. Firebase and cloud boundary
The repo includes firebase_functions.js, firestore.rules, and deployment docs, which means some backend logic and security live outside the Flutter app. Firebase Auth, Firestore, and Cloud Messaging are the main cloud services, with Cloud Functions likely handling server-side events, notifications, or command orchestration.
13. Platform integration
Android and iOS contain the expected native bootstrap files, Firebase Android config, and platform manifests, while desktop/web folders are generated Flutter targets. Native code appears minimal, so the architecture is dominated by shared Dart code with platform plugins used for maps, biometrics, notifications, and background behavior.
14. Practical diagram view
If you draw the architecture, the clearest layout is: user-facing screens on one side, a central service layer in the middle, and Firebase/device APIs on the other side. The most important data flows are location/sensor events into services, services into Firestore/Firebase Messaging, and cloud/device updates back into dashboards, alerts, and history views.
Main entry points: firebase_service.dart Firebase · main.dart Main · alert_model.dart Alert · tracking_log_model.dart Tracking log
Components 34
App shell
Bootstrap and shared Flutter entrypoints.
- Main · App bootstrap; likely wires Firebase, routing, and app-wide state.
lib/main.dart - Firebase opts · Generated Firebase configuration used by the Flutter client.
lib/firebase_options.dart
Presentation
User-facing screens organized by workflow.
- Login · User sign-in and access entry point.
lib/screens/login_screen.dart - Dashboard · Primary guardian overview for live status and activity.
lib/screens/guardian_dashboard.dart - Emergency · Emergency workflow and high-priority alerts view.
lib/screens/emergency_dashboard_screen.dart - Geofences · Create and manage monitored zones.
lib/screens/geofence_screen.dart - History · Past tracking logs and event timeline.
lib/screens/history_screen.dart - Settings · App preferences including notifications and behavior.
lib/screens/settings_screen.dart - Offline maps · Offline map and field-use experience.
lib/screens/offline_maps_screen.dart - Chatbot · Conversational helper and support workflow.
lib/screens/chatbot_screen.dart
Domain models
Core data contracts shared across the app.
- Alert · Alert and incident payload shared across features.
lib/models/alert_model.dart - Device status · Current monitored device state and health.
lib/models/device_status_model.dart - Geofence · Boundary and zone definition contract.
lib/models/geofence_model.dart - Tracking log · Captured location and activity history records.
lib/models/tracking_log_model.dart - User · Guardian and tracked-user profile data.
lib/models/user_model.dart
Services
Client-side orchestration and device/Firebase integrations.
- Firebase · Primary Firestore/Auth/Messaging integration boundary.
lib/services/firebase_service.dart - Auth · Authentication and sign-in coordination.
lib/services/auth_service.dart - Location · Live location capture and movement updates.
lib/services/location_service.dart - Sensors · Sensor-based monitoring and device signals.
lib/services/sensor_monitor_service.dart - Geofencing · Zone evaluation and enter/exit detection.
lib/services/geofence_service.dart - Background · Persistent background execution and task handling.
lib/services/background_service.dart - Offline sync · Buffers and reconciles data when connectivity changes.
lib/services/offline_sync_service.dart - Connectivity · Network-state awareness for offline-first behavior.
lib/services/connectivity_service.dart - Remote commands · Remote actions such as ring, lock, or command dispatch.
lib/services/remote_command_service.dart - Safety check-in · Check-in and safety workflow support.
lib/services/safety_checkin_service.dart - Fall detection · Fall/event detection from sensors.
lib/services/fall_detection_service.dart - WhatsApp · External messaging and alert delivery integration.
lib/services/whatsapp_service.dart - Theme · App theme selection and visual state.
lib/services/theme_service.dart - Localization · Language selection and translation lookup.
lib/services/localization_service.dart
Cloud boundary
Firebase configuration, deployment, and server-side rules/functions.
- Firestore rules · Server-side access control for Firestore data.
firestore.rules - Functions · Firebase Cloud Functions for backend events or notifications.
firebase_functions.js - Firebase JSON · Firebase project deployment configuration.
firebase.json
Connections 35
- Main → Firebase opts: loads config · Bootstrap uses generated Firebase options.
- Main → Auth: starts auth · App startup delegates login/session setup.
- Main → Theme: applies theme · Initializes shared visual state.
- Main → Localization: loads locale · Initializes language resources.
- Auth → User: builds user · Authentication resolves user identity data.
- Firebase → User: reads/writes · Persists and retrieves user profiles.
- Firebase → Alert: persists alerts · Stores alert and incident events.
- Firebase → Tracking log: stores logs · Uploads tracking history and telemetry.
- Firebase → Device status: syncs status · Synchronizes device health/state.
- Location → Tracking log: emits logs · Turns live position updates into history records.
- Sensors → Fall detection: feeds signals · Sensor stream can trigger fall detection.
- Location → Geofencing: evaluates zones · Location updates are checked against boundaries.
- Geofencing → Geofence: uses zones · Boundary evaluation depends on geofence definitions.
- Geofencing → Alert: raises alert · Zone violations become alert events.
- Background → Location: runs tracking · Background execution keeps location capture alive.
- Background → Sensors: runs sensing · Background execution supports device monitoring.
- Offline sync → Connectivity: observes network · Sync behavior depends on connectivity state.
- Offline sync → Firebase: reconciles data · Buffered events are pushed to cloud services.
- Remote commands → Firebase: dispatches control · Remote commands are mediated through backend services.
- WhatsApp → Alert: shares alert · Alerts can be forwarded through messaging channels.
- Safety check-in → Alert: creates alert · Check-in failures or safety events become alerts.
- Dashboard → Device status: shows status · Dashboard presents current monitored device state.
- Dashboard → Tracking log: shows history · Dashboard summarizes recent tracking activity.
- Emergency → Alert: shows alerts · Emergency UI centers on incident events.
- Geofences → Geofence: edits zones · Geofence UI manages boundary definitions.
- History → Tracking log: renders logs · History view displays tracking records.
- Login → Auth: auth flows · Login screen uses authentication service.
- Settings → Theme: tunes theme · Settings can adjust appearance.
- Settings → Localization: tunes language · Settings can adjust app locale.
- Offline maps → Offline sync: sync view · Offline maps are tied to offline sync behavior.
- Chatbot → Firebase: assistant data · Chat/assistant features likely use shared backend data.
- Functions → Firestore rules: complements · Server-side processing sits alongside security rules.
- Firebase JSON → Functions: deploys · Firebase deployment config includes serverless services.
- Android → Main: launches app · Android host boots the shared Flutter entrypoint.
- iOS → Main: launches app · iOS host boots the shared Flutter entrypoint.