# louaygharsaly2025/madari_connect architecture

> Architecture diagram of the GitHub repository louaygharsaly2025/madari_connect, 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_connect
- Repository: https://github.com/louaygharsaly2025/madari_connect

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** frontend for “Madari Connect,” organized as a **public auth surface** plus a **protected dashboard shell**.
   - There is no obvious custom backend in the repo; the app delegates identity, realtime messaging, and push notifications to **Firebase**, and AI features to **Gemini** as described in the README.

2. **Route architecture**
   - Public entry points live under `src/app/login` and `src/app/register`.
   - The main experience is under `src/app/(dashboard)`, which uses a shared `layout.tsx` and many feature pages: academy, AI assistant, analytics, communities, family, help, jobs, map, market, messages, profile, settings, success-rooms, tools, web, privacy.
   - This route group strongly suggests a single dashboard shell with feature pages swapped in rather than separate apps.

3. **App shell and global UI**
   - `src/app/layout.tsx` and `src/app/(dashboard)/layout.tsx` define the top-level application chrome.
   - Shared shell components in `src/components/layout` provide persistent UI such as the sidebar, language switcher, notifications, AI chat widget, radio mini-player, weather/date-time, and profile editing.
   - The dashboard therefore behaves like a multi-tool workspace with global utilities always available around the routed content.

4. **State and cross-cutting context**
   - Global behavior is centralized in React contexts under `src/context`: `auth`, `language`, `accessibility`, `ai`, `gamification`, and `radio`.
   - These contexts are the main boundary for app-wide state such as logged-in user state, selected locale, accessibility profile, assistant behavior, gamification progress, and radio playback.
   - This is important for the architecture diagram because many pages likely read from the same shared providers instead of owning isolated state.

5. **Authentication and guarded access**
   - `src/components/auth-guard.tsx` indicates protected dashboard routes are gated on authentication.
   - `src/context/auth-context.tsx` is the central auth boundary, likely wrapping Firebase Auth.
   - The README emphasizes strict registration and inclusive safety rules; in architecture terms, auth is not just login, but also the gatekeeper for access to the protected social/service surface.

6. **Social and community subsystem**
   - The social layer is split across `src/components/feed`, `src/components/messages`, `src/components/profile`, `src/components/layout/notification-dropdown.tsx`, and dashboard pages like communities, messages, profile, and analytics.
   - Feed components such as `post-card` and `stories` handle content presentation, while messages use a conventional chat stack: conversation list, chat window, bubbles, and message input.
   - Profile UI is decomposed into header, main content, sidebar, activity, and suggestions, implying a feed/profile-centric social model rather than a simple settings page.

7. **Accessibility-first subsystem**
   - Accessibility is a first-class architectural layer, not a theme toggle. It has dedicated components in `src/components/accessibility`, `src/components/layout/accessibility-tools.tsx`, and `src/context/accessibility-context.tsx`.
   - Key pieces include the AAC board, floating palette, and accessibility rating modal for the map.
   - The README’s “shape-shifting UI” and onboarding wizard are reflected by `src/components/onboarding/onboarding-wizard.tsx`, implying the UI can reconfigure itself based on a user’s accessibility profile.

8. **Service and utility domains**
   - The dashboard contains separate verticals for **map**, **jobs**, **market**, **family**, **help**, **privacy**, **settings**, and **web browsing**.
   - These appear as page-level domains rather than deep sub-apps, each likely composed from shared shell components plus domain-specific widgets.
   - `src/components/widgets` supports the dashboard with medication tracking, network diagnostics, online contacts, and prayer times, which are utility surfaces rather than primary content feeds.

9. **AI, voice, and radio**
   - `src/app/(dashboard)/ai-assistant` and `src/components/layout/ai-chat-widget.tsx` are the main AI entry points, backed by `src/context/ai-context.tsx`.
   - The architecture suggests AI is embedded into the shell as a persistent assistant, not isolated to one page.
   - `src/context/radio-context.tsx` plus `radio-mini-player.tsx` show media playback is also global, supporting the app’s “always-available companion” design.

10. **Notifications, messaging, and realtime boundary**
   - `src/hooks/use-notifications.ts`, `src/lib/fcm.ts`, `src/lib/firebase.ts`, and `public/firebase-messaging-sw.js` form the notification pipeline.
   - The service worker boundary is important: push delivery and foreground handling are handled outside the React tree, while the app consumes the results through hooks and dropdown UI.
   - This is the main realtime/external-event path in the repo alongside chat.

11. **Localization and user-specific data**
   - The app is localized through `public/locales/*.json` and `src/context/language-context.tsx`, with Arabic, English, French, German, Italian, and Tunisian Arabic available.
   - `src/lib/profile-data.ts` likely provides seeded or derived profile content used by profile and suggestion components.
   - `src/lib/utils.ts` is the shared utility layer for small cross-cutting helpers.

12. **PWA and mobile-friendly delivery**
   - `src/app/manifest.ts` and `public/firebase-messaging-sw.js` indicate the app is built as a **PWA-capable** experience with installability and push support.
   - The README also mentions Flutter integration and QR synchronization, so the web app is one client in a broader cross-platform ecosystem.

13. **Adjacent browser-extension-style asset bundle**
   - The `madari-lens/` directory contains `manifest.json` and `content.css`, which looks like a separate browser-extension or overlay asset package.
   - Architecturally, this is likely an auxiliary boundary rather than part of the main Next.js runtime, used to inject or style accessibility-related UI outside the app.

14. **What to draw in the diagram**
   - At the center: the **Next.js dashboard shell** with context providers around it.
   - On the left: **public auth routes** feeding into **auth guard/Firebase auth**.
   - Around the shell: **feature domains** for social, accessibility, AI, services, and utilities.
   - On the right: **Firebase services**, **Gemini AI**, **push notifications/service worker**, and **localization assets** as the main external dependencies.

Main entry points: [`src/app/(dashboard)/layout.tsx`](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/layout.tsx) (Dashboard shell), [`src/components/layout`](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/layout) (Shell widgets), [`src/context/auth-context.tsx`](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/auth-context.tsx) (Auth context), [`src/components/accessibility`](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/accessibility) (A11y UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public surface"]
  node_login_page["Login<br/>Public route<br/>[page.tsx]"]
  node_register_page["Register<br/>Public route<br/>[page.tsx]"]
end

subgraph group_dashboard["Dashboard shell"]
  node_app_layout["App layout<br/>Next.js root<br/>[layout.tsx]"]
  node_dashboard_layout["Dashboard shell<br/>Route layout<br/>[layout.tsx]"]
  node_sidebar["Sidebar<br/>Nav chrome<br/>[sidebar.tsx]"]
  node_shell_widgets["Shell widgets<br/>Global utilities"]
end

subgraph group_features["Feature domains"]
  node_home_page["Dashboard home<br/>Landing route<br/>[page.tsx]"]
  node_messages_page["Messages<br/>Chat surface<br/>[page.tsx]"]
  node_profile_page["Profile<br/>[page.tsx]"]
  node_map_page["Map<br/>Location surface<br/>[page.tsx]"]
  node_tools_page["Tools hub<br/>Utility hub"]
  node_feed_components["Feed UI<br/>Social UI"]
  node_message_components["Chat UI<br/>Conversation UI"]
  node_profile_components["Profile UI"]
  node_accessibility_components["A11y UI<br/>Accessibility UI"]
  node_widgets["Dashboard widgets<br/>Utility widgets"]
end

subgraph group_platform["Platform services"]
  node_auth_guard["Auth guard<br/>Route gate<br/>[auth-guard.tsx]"]
  node_auth_ctx["Auth context<br/>Session state<br/>[auth-context.tsx]"]
  node_language_ctx["Language context<br/>Locale state"]
  node_accessibility_ctx["Accessibility context<br/>A11y state"]
  node_ai_ctx["AI context<br/>Assistant state<br/>[ai-context.tsx]"]
  node_radio_ctx["Radio context<br/>Playback state<br/>[radio-context.tsx]"]
  node_firebase[("Firebase<br/>Backend services<br/>[firebase.ts]")]
  node_fcm["Push pipeline<br/>Notifications<br/>[fcm.ts]"]
  node_notifications_hook["Notifications hook<br/>Realtime hook"]
  node_gemini{{"Gemini AI<br/>External AI"}}
  node_locales["Locale files<br/>Translations"]
  node_pwa_sw["Messaging SW<br/>Service worker"]
  node_madari_lens["Madari Lens<br/>Extension assets"]
end

node_login_page -->|"sign in"| node_auth_ctx
node_register_page -->|"create account"| node_auth_ctx
node_auth_ctx -->|"auth backend"| node_firebase
node_auth_guard -->|"verify session"| node_auth_ctx
node_app_layout -->|"wraps"| node_dashboard_layout
node_dashboard_layout -->|"renders"| node_sidebar
node_dashboard_layout -->|"renders"| node_shell_widgets
node_dashboard_layout -->|"protects"| node_auth_guard
node_dashboard_layout -->|"hosts"| node_home_page
node_dashboard_layout -->|"hosts"| node_messages_page
node_dashboard_layout -->|"hosts"| node_profile_page
node_dashboard_layout -->|"hosts"| node_map_page
node_dashboard_layout -->|"hosts"| node_tools_page
node_home_page -->|"uses"| node_feed_components
node_messages_page -->|"uses"| node_message_components
node_profile_page -->|"uses"| node_profile_components
node_map_page -->|"uses"| node_accessibility_components
node_shell_widgets -->|"uses"| node_language_ctx
node_shell_widgets -->|"uses"| node_ai_ctx
node_shell_widgets -->|"uses"| node_radio_ctx
node_shell_widgets -->|"uses"| node_notifications_hook
node_accessibility_components -->|"uses"| node_accessibility_ctx
node_ai_ctx -->|"calls"| node_gemini
node_notifications_hook -->|"consumes"| node_fcm
node_fcm -->|"delivers via"| node_pwa_sw
node_language_ctx -->|"loads"| node_locales
node_widgets -->|"data source"| node_firebase
node_madari_lens -.->|"supports"| node_accessibility_components

click node_app_layout "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/layout.tsx"
click node_dashboard_layout "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/layout.tsx"
click node_sidebar "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/components/layout/sidebar.tsx"
click node_shell_widgets "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/layout"
click node_auth_guard "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/components/auth-guard.tsx"
click node_auth_ctx "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/auth-context.tsx"
click node_language_ctx "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/language-context.tsx"
click node_accessibility_ctx "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/accessibility-context.tsx"
click node_ai_ctx "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/ai-context.tsx"
click node_radio_ctx "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/radio-context.tsx"
click node_login_page "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/login/page.tsx"
click node_register_page "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/register/page.tsx"
click node_home_page "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/page.tsx"
click node_messages_page "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/messages/page.tsx"
click node_profile_page "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/profile/page.tsx"
click node_map_page "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/map/page.tsx"
click node_tools_page "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/app/(dashboard)/tools"
click node_feed_components "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/feed"
click node_message_components "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/messages"
click node_profile_components "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/profile"
click node_accessibility_components "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/accessibility"
click node_widgets "https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/widgets"
click node_firebase "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/lib/firebase.ts"
click node_fcm "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/lib/fcm.ts"
click node_notifications_hook "https://github.com/louaygharsaly2025/madari_connect/blob/main/src/hooks/use-notifications.ts"
click node_locales "https://github.com/louaygharsaly2025/madari_connect/tree/main/public/locales"
click node_pwa_sw "https://github.com/louaygharsaly2025/madari_connect/blob/main/public/firebase-messaging-sw.js"
click node_madari_lens "https://github.com/louaygharsaly2025/madari_connect/tree/main/madari-lens"

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_login_page,node_register_page toneBlue
class node_app_layout,node_dashboard_layout,node_sidebar,node_shell_widgets toneAmber
class node_home_page,node_messages_page,node_profile_page,node_map_page,node_tools_page,node_feed_components,node_message_components,node_profile_components,node_accessibility_components,node_widgets toneMint
class node_auth_guard,node_auth_ctx,node_language_ctx,node_accessibility_ctx,node_ai_ctx,node_radio_ctx,node_firebase,node_fcm,node_notifications_hook,node_gemini,node_locales,node_pwa_sw,node_madari_lens toneRose
```

## Components

### Public surface

Unauthenticated entry points for onboarding and access.

- [Login](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/login/page.tsx): Public route · Public sign-in entry point. · `src/app/login/page.tsx`
- [Register](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/register/page.tsx): Public route · Public account creation entry point. · `src/app/register/page.tsx`

### Dashboard shell

Shared app chrome and protected routed experience.

- [App layout](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/layout.tsx): Next.js root · Top-level application wrapper and global styles. · `src/app/layout.tsx`
- [Dashboard shell](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/layout.tsx): Route layout · Shared authenticated shell for dashboard pages. · `src/app/(dashboard)/layout.tsx`
- [Sidebar](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/components/layout/sidebar.tsx): Nav chrome · Persistent navigation and shell scaffolding. · `src/components/layout/sidebar.tsx`
- [Shell widgets](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/layout): Global utilities · Persistent helpers such as language, notifications, AI chat, radio, weather, time, and profile editing. · `src/components/layout`

### Feature domains

Main product areas rendered inside the dashboard.

- [Dashboard home](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/page.tsx): Landing route · Main post-login landing page. · `src/app/(dashboard)/page.tsx`
- [Messages](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/messages/page.tsx): Chat surface · Conversation and messaging entry point. · `src/app/(dashboard)/messages/page.tsx`
- [Profile](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/profile/page.tsx): Social profile · User profile and identity surface. · `src/app/(dashboard)/profile/page.tsx`
- [Map](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/app/(dashboard)/map/page.tsx): Location surface · Map and accessibility rating experience. · `src/app/(dashboard)/map/page.tsx`
- [Tools hub](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/app/(dashboard)/tools): Utility hub · Gateway to prayer, Quran, Ramadan, and sharia tools. · `src/app/(dashboard)/tools`
- [Feed UI](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/feed): Social UI · Post and story components for the social feed. · `src/components/feed`
- [Chat UI](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/messages): Conversation UI · Conversation list, window, bubbles, and input for chat. · `src/components/messages`
- [Profile UI](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/profile): Profile UI · Header, main content, sidebar, activity, and suggestions sections. · `src/components/profile`
- [A11y UI](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/accessibility): Accessibility UI · AAC board, floating palette, and accessibility tools. · `src/components/accessibility`
- [Dashboard widgets](https://github.com/louaygharsaly2025/madari_connect/tree/main/src/components/widgets): Utility widgets · Medication, network, contacts, and prayer-time widgets. · `src/components/widgets`

### Platform services

Cross-cutting contexts, data access, and external integrations.

- [Auth guard](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/components/auth-guard.tsx): Route gate · Protects dashboard access for signed-in users. · `src/components/auth-guard.tsx`
- [Auth context](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/auth-context.tsx): Session state · Central auth state and Firebase-backed user session boundary. · `src/context/auth-context.tsx`
- [Language context](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/language-context.tsx): Locale state · App-wide localization and language selection state. · `src/context/language-context.tsx`
- [Accessibility context](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/accessibility-context.tsx): A11y state · Accessibility profile and shape-shifting UI state. · `src/context/accessibility-context.tsx`
- [AI context](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/ai-context.tsx): Assistant state · Shared assistant state for embedded AI features. · `src/context/ai-context.tsx`
- [Radio context](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/context/radio-context.tsx): Playback state · Global radio/player state for the companion audio experience. · `src/context/radio-context.tsx`
- [Firebase](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/lib/firebase.ts): Backend services · Auth, realtime data, and messaging backend dependencies. · `src/lib/firebase.ts`
- [Push pipeline](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/lib/fcm.ts): Notifications · Firebase Cloud Messaging setup and service worker delivery path. · `src/lib/fcm.ts`
- [Notifications hook](https://github.com/louaygharsaly2025/madari_connect/blob/main/src/hooks/use-notifications.ts): Realtime hook · Foreground notification consumption inside React. · `src/hooks/use-notifications.ts`
- **Gemini AI**: External AI · Remote model used by the assistant experience.
- [Locale files](https://github.com/louaygharsaly2025/madari_connect/tree/main/public/locales): Translations · JSON translation bundles for supported languages. · `public/locales`
- [Messaging SW](https://github.com/louaygharsaly2025/madari_connect/blob/main/public/firebase-messaging-sw.js): Service worker · Push and background messaging boundary. · `public/firebase-messaging-sw.js`
- [Madari Lens](https://github.com/louaygharsaly2025/madari_connect/tree/main/madari-lens): Extension assets · Auxiliary browser-extension-style asset bundle. · `madari-lens`

## Connections

- Login → Auth context: sign in · Public login updates session state.
- Register → Auth context: create account · Registration feeds the shared auth boundary.
- Auth context → Firebase: auth backend · Firebase provides identity/session services.
- Auth guard → Auth context: verify session · Protected routes consult auth state.
- App layout → Dashboard shell: wraps · Root app composition flows into the dashboard shell.
- Dashboard shell → Sidebar: renders · Shell includes persistent navigation.
- Dashboard shell → Shell widgets: renders · Shell exposes global utilities around routed content.
- Dashboard shell → Auth guard: protects · Dashboard routes are gated by authentication.
- Dashboard shell → Dashboard home: hosts · The shell routes into the main landing page.
- Dashboard shell → Messages: hosts · The shell swaps in feature pages.
- Dashboard shell → Profile: hosts · The shell swaps in feature pages.
- Dashboard shell → Map: hosts · The shell swaps in feature pages.
- Dashboard shell → Tools hub: hosts · The shell swaps in feature pages.
- Dashboard home → Feed UI: uses · Social landing content is built from feed UI pieces.
- Messages → Chat UI: uses · Chat page is composed from messaging widgets.
- Profile → Profile UI: uses · Profile page is assembled from profile sections.
- Map → A11y UI: uses · Map experience includes accessibility-specific UI.
- Shell widgets → Language context: uses · Language switcher and localized chrome use language state.
- Shell widgets → AI context: uses · AI chat widget uses shared assistant state.
- Shell widgets → Radio context: uses · Mini-player uses global playback state.
- Shell widgets → Notifications hook: uses · Notification dropdown consumes foreground events.
- A11y UI → Accessibility context: uses · Accessibility UI is driven by shared a11y state.
- AI context → Gemini AI: calls · Assistant features are backed by Gemini.
- Notifications hook → Push pipeline: consumes · Hook reads the push notification pipeline.
- Push pipeline → Messaging SW: delivers via · Background notification delivery occurs through the service worker.
- Language context → Locale files: loads · Locale choices map to translation bundles.
- Dashboard widgets → Firebase: data source · Utility widgets rely on shared backend services where needed.
- Madari Lens → A11y UI: supports · Auxiliary assets appear to extend the accessibility surface.
