# louaygharsaly2025/madari architecture

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

- Interactive diagram: https://gitdiagram.com/louaygharsaly2025/madari
- Repository: https://github.com/louaygharsaly2025/madari

## Overview

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: [`lib/features/dashboard`](https://github.com/louaygharsaly2025/madari/tree/main/lib/features/dashboard) (Dashboards), [`lib/core/services`](https://github.com/louaygharsaly2025/madari/tree/main/lib/core/services) (Core services), [`lib/core/services/background_service.dart`](https://github.com/louaygharsaly2025/madari/blob/main/lib/core/services/background_service.dart) (Device services), [`lib/core/services/storage_service.dart`](https://github.com/louaygharsaly2025/madari/blob/main/lib/core/services/storage_service.dart) (Local data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core"]
  node_main["App entry<br/>flutter entrypoint<br/>[main.dart]"]
  node_router["Router<br/>route config<br/>[router.dart]"]
  node_auto_router["Auto router<br/>routing generator<br/>[auto_router.dart]"]
  node_shell["Madari shell<br/>app shell<br/>[madari_shell.dart]"]
  node_core_services["Core services<br/>shared services"]
  node_core_widgets["Shared widgets<br/>ui primitives"]
  node_core_theme["Theme"]
end

subgraph group_group_features["Features"]
  node_home["Home<br/>dashboard<br/>[home_screen.dart]"]
  node_dashboard["Dashboards<br/>hub screens"]
  node_religion["Religion<br/>content hub"]
  node_quran["Quran<br/>reader subsystem"]
  node_vault["Vault<br/>secure storage<br/>[vault_screen.dart]"]
  node_health["Health<br/>wellness hub"]
  node_safety["Safety"]
  node_accessibility["Accessibility"]
  node_ai["AI<br/>assistant subsystem"]
  node_social["Social<br/>community hub"]
  node_tools["Tools<br/>utility hub"]
  node_settings["Settings<br/>control hub"]
end

subgraph group_group_platform["Platform"]
  node_native_android["Android native<br/>platform bridge"]
  node_native_ios["iOS embed<br/>platform shell<br/>[AppDelegate.swift]"]
end

subgraph group_group_edge["Edges"]
  node_backend_firebase["Firebase backend<br/>cloud boundary"]
  node_local_data[("Local data<br/>persistence boundary")]
  node_device_services["Device services<br/>device APIs"]
end

node_main -->|"starts"| node_router
node_router -->|"delegates"| node_auto_router
node_router -->|"wraps"| node_shell
node_shell -->|"uses"| node_core_widgets
node_shell -->|"applies"| node_core_theme
node_home -->|"links"| node_dashboard
node_dashboard -->|"routes to"| node_religion
node_dashboard -->|"routes to"| node_health
node_dashboard -->|"routes to"| node_social
node_dashboard -->|"routes to"| node_tools
node_dashboard -->|"routes to"| node_settings
node_religion -->|"contains"| node_quran
node_religion -->|"uses"| node_core_services
node_quran -->|"reads/writes"| node_local_data
node_vault -->|"stores"| node_local_data
node_vault -->|"uses"| node_core_services
node_health -->|"uses"| node_device_services
node_safety -->|"uses"| node_device_services
node_accessibility -->|"bridges"| node_native_android
node_accessibility -->|"uses"| node_core_services
node_ai -->|"uses"| node_core_services
node_social -->|"persists"| node_local_data
node_tools -->|"uses"| node_device_services
node_settings -->|"configures"| node_core_services
node_backend_firebase -.->|"backs"| node_core_services
node_local_data -.->|"served by"| node_core_services
node_device_services -.->|"extends"| node_native_android
node_device_services -.->|"packages"| node_native_ios

click node_main "https://github.com/louaygharsaly2025/madari/blob/main/lib/main.dart"
click node_router "https://github.com/louaygharsaly2025/madari/blob/main/lib/router.dart"
click node_auto_router "https://github.com/louaygharsaly2025/madari/blob/main/lib/core/routing/auto_router.dart"
click node_shell "https://github.com/louaygharsaly2025/madari/blob/main/lib/core/widgets/madari_shell.dart"
click node_core_services "https://github.com/louaygharsaly2025/madari/tree/main/lib/core/services"
click node_core_widgets "https://github.com/louaygharsaly2025/madari/tree/main/lib/core/widgets"
click node_core_theme "https://github.com/louaygharsaly2025/madari/tree/main/lib/core/theme"
click node_home "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/home/home_screen.dart"
click node_dashboard "https://github.com/louaygharsaly2025/madari/tree/main/lib/features/dashboard"
click node_religion "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/religion/religion_dashboard.dart"
click node_quran "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/religion/quran/quran_dashboard.dart"
click node_vault "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/vault/vault_screen.dart"
click node_health "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/health/health_dashboard.dart"
click node_safety "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/safety/safety_center_screen.dart"
click node_accessibility "https://github.com/louaygharsaly2025/madari/tree/main/lib/features/accessibility"
click node_ai "https://github.com/louaygharsaly2025/madari/tree/main/lib/features/ai"
click node_social "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/social/social_dashboard.dart"
click node_tools "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/tools/tools_dashboard.dart"
click node_settings "https://github.com/louaygharsaly2025/madari/blob/main/lib/features/settings/settings_screen.dart"
click node_native_android "https://github.com/louaygharsaly2025/madari/tree/main/android/app/src/main/kotlin/com/louay/madari"
click node_native_ios "https://github.com/louaygharsaly2025/madari/blob/main/ios/Runner/AppDelegate.swift"
click node_backend_firebase "https://github.com/louaygharsaly2025/madari/blob/main/lib/firebase_options.dart"
click node_local_data "https://github.com/louaygharsaly2025/madari/blob/main/lib/core/services/storage_service.dart"
click node_device_services "https://github.com/louaygharsaly2025/madari/blob/main/lib/core/services/background_service.dart"

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_router,node_auto_router,node_shell,node_core_services,node_core_widgets,node_core_theme toneBlue
class node_home,node_dashboard,node_religion,node_quran,node_vault,node_health,node_safety,node_accessibility,node_ai,node_social,node_tools,node_settings toneAmber
class node_native_android,node_native_ios toneMint
class node_backend_firebase,node_local_data,node_device_services toneRose
```

## Components

### Core

Shared app shell, services, theming, and reusable widgets.

- [App entry](https://github.com/louaygharsaly2025/madari/blob/main/lib/main.dart): flutter entrypoint · Bootstraps the app and initializes the shell. · `lib/main.dart`
- [Router](https://github.com/louaygharsaly2025/madari/blob/main/lib/router.dart): route config · Central route generation and app navigation. · `lib/router.dart`
- [Auto router](https://github.com/louaygharsaly2025/madari/blob/main/lib/core/routing/auto_router.dart): routing generator · Generated route wiring and screen mapping. · `lib/core/routing/auto_router.dart`
- [Madari shell](https://github.com/louaygharsaly2025/madari/blob/main/lib/core/widgets/madari_shell.dart): app shell · Global layout, overlays, and shared scaffolding. · `lib/core/widgets/madari_shell.dart`
- [Core services](https://github.com/louaygharsaly2025/madari/tree/main/lib/core/services): shared services · Cross-cutting services for storage, sync, AI, notifications, sensors, and security. · `lib/core/services`
- [Shared widgets](https://github.com/louaygharsaly2025/madari/tree/main/lib/core/widgets): ui primitives · Reusable wrappers and overlays used across features. · `lib/core/widgets`
- [Theme](https://github.com/louaygharsaly2025/madari/tree/main/lib/core/theme): theme system · App-wide theming and theme state management. · `lib/core/theme`

### Features

Domain modules organized by capability.

- [Home](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/home/home_screen.dart): dashboard · Personal start screen that aggregates cards and quick actions. · `lib/features/home/home_screen.dart`
- [Dashboards](https://github.com/louaygharsaly2025/madari/tree/main/lib/features/dashboard): hub screens · Unified and personal dashboards for cross-feature navigation. · `lib/features/dashboard`
- [Religion](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/religion/religion_dashboard.dart): content hub · Spiritual reading, prayer, dhikr, Quran, hadith, and related tools. · `lib/features/religion/religion_dashboard.dart`
- [Quran](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/religion/quran/quran_dashboard.dart): reader subsystem · Reading, search, tafsir, bookmarks, wird, and memorization flows. · `lib/features/religion/quran/quran_dashboard.dart`
- [Vault](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/vault/vault_screen.dart): secure storage · Protected notes, media, passwords, cards, and emergency data. · `lib/features/vault/vault_screen.dart`
- [Health](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/health/health_dashboard.dart): wellness hub · Trackers and assistants for hydration, sleep, heart rate, meds, and SOS. · `lib/features/health/health_dashboard.dart`
- [Safety](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/safety/safety_center_screen.dart): safety hub · Geofence, tracking, shadow guard, and companion safety flows. · `lib/features/safety/safety_center_screen.dart`
- [Accessibility](https://github.com/louaygharsaly2025/madari/tree/main/lib/features/accessibility): accessibility suite · AAC, eye Morse, head control, social tone, and custom voice commands. · `lib/features/accessibility`
- [AI](https://github.com/louaygharsaly2025/madari/tree/main/lib/features/ai): assistant subsystem · Chat, coaching, search, notes, and contextual AI experiences. · `lib/features/ai`
- [Social](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/social/social_dashboard.dart): community hub · Broadcasts, community, relations, mentors, events, and chats. · `lib/features/social/social_dashboard.dart`
- [Tools](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/tools/tools_dashboard.dart): utility hub · Everyday utilities like notes, expenses, transcription, reminders, and weather. · `lib/features/tools/tools_dashboard.dart`
- [Settings](https://github.com/louaygharsaly2025/madari/blob/main/lib/features/settings/settings_screen.dart): control hub · Configuration for privacy, sync, accessibility, security, and features. · `lib/features/settings/settings_screen.dart`

### Platform

Native and cross-platform embedding layers.

- [Android native](https://github.com/louaygharsaly2025/madari/tree/main/android/app/src/main/kotlin/com/louay/madari): platform bridge · Accessibility service, floating window, tile, and widget integrations. · `android/app/src/main/kotlin/com/louay/madari`
- [iOS embed](https://github.com/louaygharsaly2025/madari/blob/main/ios/Runner/AppDelegate.swift): platform shell · iOS application embedding and lifecycle integration. · `ios/Runner/AppDelegate.swift`

### Edges

Cloud, local storage, and device integration boundaries.

- [Firebase backend](https://github.com/louaygharsaly2025/madari/blob/main/lib/firebase_options.dart): cloud boundary · Auth, Firestore, functions, and rules for cloud sync and server logic. · `lib/firebase_options.dart`
- [Local data](https://github.com/louaygharsaly2025/madari/blob/main/lib/core/services/storage_service.dart): persistence boundary · Local storage, databases, generated models, and offline sync. · `lib/core/services/storage_service.dart`
- [Device services](https://github.com/louaygharsaly2025/madari/blob/main/lib/core/services/background_service.dart): device APIs · Background tasks, sensors, location, alarms, notifications, and voice control. · `lib/core/services/background_service.dart`

## Connections

- 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.
