How louaygharsaly2025/madari works
1. Product shape
Madari is a large Flutter multi-platform app that behaves like a personal operating system rather than a single-purpose app. The feature tree is organized by domain modules under lib/features, with shared cross-cutting infrastructure in lib/core. The app spans spiritual tools, productivity, safety/security, health, AI assistance, accessibility, and social/family utilities.
2. Bootstrapping and navigation
The main entrypoints are lib/main.dart and lib/router.dart, with route generation handled by lib/core/routing/auto_router.dart. This indicates a centralized app shell that decides the initial experience and routes users into feature-specific screens. The core/widgets/madari_shell.dart and related wrapper widgets suggest a consistent global layout/overlay system around feature pages.
3. Core architectural layer
lib/core holds shared configuration, constants, models, theming, utilities, and generic services used across features. This is the app’s integration boundary: feature modules should depend on core abstractions for storage, notifications, auth, sync, sensors, and accessibility instead of directly wiring platform details in every screen.
4. Feature-first modularization
Most business logic lives inside self-contained feature folders such as religion, vault, health, safety, social, tools, ai, home, settings, and accessibility. Each feature typically has its own screens, models, services, and sometimes state management classes. This makes the architecture highly domain-oriented, with the UI and the domain logic colocated per capability.
5. Data and persistence
The codebase uses local-first storage heavily. The presence of many *.g.dart generated model files points to code-generated persistence/serialization models, likely with Isar/Hive-style object storage and JSON-backed assets. There is also explicit support for sqflite, plus helper services such as database_helper.dart, storage_service.dart, backup_service.dart, and offline_sync_service.dart, which suggests multiple persistence layers: structured local storage, lightweight cache, and backup/sync pipelines.
6. Cloud and sync boundary
Firebase is a real architectural dependency, not just incidental tooling: firebase_options.dart, firebase_service.dart, firestore_service.dart, auth_service.dart, firebase.json, firestore.rules, and firebase_functions.js show cloud-backed identity, data sync, and server-side functions. The repo also includes p2p_sync_service.dart, sync_service.dart, and quran_sync_service.dart, so synchronization is split between cloud sync and offline/peer-oriented flows depending on the domain.
7. AI and semantic assistance subsystem
AI is a first-class subsystem under both core/services and features/ai / features/ideas. Services like ai_analysis_service.dart, ai_briefing_service.dart, ai_coach_service.dart, contextual_ai_service.dart, daily_digest_service.dart, and query_my_life_service.dart indicate multiple AI entry points: coaching, summaries, semantic search, and proactive recommendations. The README confirms Gemini integration, so AI likely sits behind service abstractions consumed by dashboards and assistant UIs rather than directly embedded in screens.
8. Spiritual content engine
The religion and quran trees are one of the biggest subsystems. They combine static content in assets/quran and assets/data, screen flows for reading/searching/tafsir/bookmarks/wird/khatma, and dedicated services like quran_service.dart, tafsir_service.dart, khatma_service.dart, and wird_service.dart. This area also includes hadith collections, dhikr/athkar, prayer times, qibla, Ramadan/fasting tools, quotes, and radio, making it a content-heavy domain with many specialized reader screens.
9. Privacy, vault, and security
Security is a major architectural pillar. The vault feature manages sensitive user assets such as notes, media, cards, passwords, numbers, authenticator data, and emergency contacts, while services like vault_service.dart, security_service.dart, privacy_shield_service.dart, shoulder_surfing_service.dart, and intruder_selfie_service.dart support protection features. The “fake calculator,” lock screen, intruder record models, and decoy/privacy screens show that security is not just storage encryption but also anti-observation and deception UX.
10. Health, wellness, and emergency flows
Health features are split into trackers and specialized assistants: hydration, step tracking, heart rate, sleep, BMI, medication, coffee, fasting hydration, symptom tracking, and SOS/emergency profile screens. These features rely on dedicated services like health_data_service.dart, heart_rate_service.dart, step_service.dart, and voice_coach_service.dart, so the architecture supports continuous monitoring and reminder-style workflows in addition to manual data entry.
11. Accessibility and device interaction
Accessibility is not an add-on; it has its own feature set and platform bridge. The app includes accessibility services and UI for AAC voice, custom voice commands, eye Morse chat, head control, spatial radar, social tone, and stimming support. On Android, native components like MadariAccessibilityService, FloatingWindowService, MadariTileService, and MadariWidgetProvider indicate deep OS integration for overlays, quick actions, accessibility callbacks, and widgets. android_accessibility_channel.dart bridges Flutter to those native services.
12. Background, sensing, and real-world automation
Several services appear designed for always-on or background execution: background_service.dart, workmanager_service.dart, alarm_service.dart, notification_service.dart, geofence_service.dart, location_service.dart, sensor_monitor_service.dart, shake_service.dart, voice_command_service.dart, and voice_guidance_service.dart. This means the app’s architecture is event-driven and device-sensor-driven, with scheduled/background processing feeding alerts, reminders, and safety features.
13. Navigation and UX composition
The app is structured around dashboards and hubs rather than a flat menu. Many domains have a dashboard screen (home, religion, health, social, tools, settings, vault, etc.), and the home screen aggregates cards from multiple subsystems such as AI summaries, athkar, weather, tasks, quotes, and spiritual insights. Shared widgets like overlays, floating bubbles, predictive hit areas, and accessibility wrappers suggest a layered UI model with global affordances above feature content.
14. Platform-specific footprint
The repository includes native Android, iOS, macOS, Windows, Linux, and web scaffolding, so Flutter is the primary cross-platform layer while certain capabilities are platform-sensitive. Android contains the deepest customization for accessibility services, widgets, tile services, and background behavior; iOS/macOS/desktop shells exist mainly for packaging and platform embedding. This implies the architecture is portable at the UI level but selectively native where OS APIs are required.
15. Localization, content assets, and code generation
The app is multilingual and content-rich. lib/l10n contains generated localization classes and multiple ARB files, while the root includes Arabic/English/French documentation and translation tooling. Large asset sets for Quran texts, hadith collections, audio, fonts, and city data indicate the app ships significant offline content. Generated model files and localization outputs show a build pipeline that depends on code generation for both data models and language support.
16. How the main data flow works
Typical flows start in the Flutter shell, route into a feature dashboard, then call one or more services. Those services read from local storage or assets, optionally sync with Firebase or background processes, and return domain data to screens/widgets. Device APIs, native Android services, and cloud services sit at the edges of the system, while core and feature services are the main mediation layer between UI and infrastructure.
Main entry points: dashboard Dashboards · services Core services · background_service.dart Device services · storage_service.dart Local data
Components 24
Core
Shared app shell, services, theming, and reusable widgets.
- App entry · Bootstraps the app and initializes the shell.
lib/main.dart - Router · Central route generation and app navigation.
lib/router.dart - Auto router · Generated route wiring and screen mapping.
lib/core/routing/auto_router.dart - Madari shell · Global layout, overlays, and shared scaffolding.
lib/core/widgets/madari_shell.dart - Core services · Cross-cutting services for storage, sync, AI, notifications, sensors, and security.
lib/core/services - Shared widgets · Reusable wrappers and overlays used across features.
lib/core/widgets - Theme · App-wide theming and theme state management.
lib/core/theme
Features
Domain modules organized by capability.
- Home · Personal start screen that aggregates cards and quick actions.
lib/features/home/home_screen.dart - Dashboards · Unified and personal dashboards for cross-feature navigation.
lib/features/dashboard - Religion · Spiritual reading, prayer, dhikr, Quran, hadith, and related tools.
lib/features/religion/religion_dashboard.dart - Quran · Reading, search, tafsir, bookmarks, wird, and memorization flows.
lib/features/religion/quran/quran_dashboard.dart - Vault · Protected notes, media, passwords, cards, and emergency data.
lib/features/vault/vault_screen.dart - Health · Trackers and assistants for hydration, sleep, heart rate, meds, and SOS.
lib/features/health/health_dashboard.dart - Safety · Geofence, tracking, shadow guard, and companion safety flows.
lib/features/safety/safety_center_screen.dart - Accessibility · AAC, eye Morse, head control, social tone, and custom voice commands.
lib/features/accessibility - AI · Chat, coaching, search, notes, and contextual AI experiences.
lib/features/ai - Social · Broadcasts, community, relations, mentors, events, and chats.
lib/features/social/social_dashboard.dart - Tools · Everyday utilities like notes, expenses, transcription, reminders, and weather.
lib/features/tools/tools_dashboard.dart - Settings · Configuration for privacy, sync, accessibility, security, and features.
lib/features/settings/settings_screen.dart
Platform
Native and cross-platform embedding layers.
- Android native · Accessibility service, floating window, tile, and widget integrations.
android/app/src/main/kotlin/com/louay/madari - iOS embed · iOS application embedding and lifecycle integration.
ios/Runner/AppDelegate.swift
Edges
Cloud, local storage, and device integration boundaries.
- Firebase backend · Auth, Firestore, functions, and rules for cloud sync and server logic.
lib/firebase_options.dart - Local data · Local storage, databases, generated models, and offline sync.
lib/core/services/storage_service.dart - Device services · Background tasks, sensors, location, alarms, notifications, and voice control.
lib/core/services/background_service.dart
Connections 28
- App entry → Router: starts · App entry initializes navigation.
- Router → Auto router: delegates · Route generation is centralized in the generated router.
- Router → Madari shell: wraps · Navigation flows land inside the global app shell.
- Madari shell → Shared widgets: uses · Shell composes shared overlays and wrappers.
- Madari shell → Theme: applies · Shell and pages share global theme state.
- Home → Dashboards: links · Home acts as an aggregation point for dashboard-style navigation.
- Dashboards → Religion: routes to · Unified dashboards fan out into major domains.
- Dashboards → Health: routes to · Unified dashboards fan out into major domains.
- Dashboards → Social: routes to · Unified dashboards fan out into major domains.
- Dashboards → Tools: routes to · Unified dashboards fan out into major domains.
- Dashboards → Settings: routes to · Unified dashboards fan out into major domains.
- Religion → Quran: contains · Quran is the largest spiritual reader subsystem.
- Religion → Core services: uses · Spiritual screens depend on shared content and sync services.
- Quran → Local data: reads/writes · Quran flows use local content, bookmarks, plans, and sync state.
- Vault → Local data: stores · Sensitive data is stored locally with protection flows.
- Vault → Core services: uses · Vault relies on security, storage, scanner, and auth services.
- Health → Device services: uses · Health trackers depend on sensors, reminders, and background jobs.
- Safety → Device services: uses · Safety features depend on location, geofence, alerts, and monitoring.
- Accessibility → Android native: bridges · Accessibility suite connects to Android services and overlays.
- Accessibility → Core services: uses · Flutter accessibility features share core observers and channels.
- AI → Core services: uses · AI features are surfaced through shared AI service abstractions.
- Social → Local data: persists · Community, chat, and relationship data use local models and storage.
- Tools → Device services: uses · Tooling features rely on reminders, transcription, location, and sensors.
- Settings → Core services: configures · Settings control sync, privacy, accessibility, and security services.
- Firebase backend → Core services: backs · Cloud sync and auth are mediated by shared services.
- Local data → Core services: served by · Storage helpers and database services provide the persistence layer.
- Device services → Android native: extends · Background, accessibility, and widget behavior can use native Android hooks.
- Device services → iOS embed: packages · Flutter also ships with iOS embedding for platform-specific capabilities.