How louaygharsaly2025/madari_connect works
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: layout.tsx Dashboard shell · layout Shell widgets · auth-context.tsx Auth context · accessibility A11y UI
Components 29
Public surface
Unauthenticated entry points for onboarding and access.
Dashboard shell
Shared app chrome and protected routed experience.
- App layout · Top-level application wrapper and global styles.
src/app/layout.tsx - Dashboard shell · Shared authenticated shell for dashboard pages.
src/app/(dashboard)/layout.tsx - Sidebar · Persistent navigation and shell scaffolding.
src/components/layout/sidebar.tsx - Shell widgets · 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 · Main post-login landing page.
src/app/(dashboard)/page.tsx - Messages · Conversation and messaging entry point.
src/app/(dashboard)/messages/page.tsx - Profile · User profile and identity surface.
src/app/(dashboard)/profile/page.tsx - Map · Map and accessibility rating experience.
src/app/(dashboard)/map/page.tsx - Tools hub · Gateway to prayer, Quran, Ramadan, and sharia tools.
src/app/(dashboard)/tools - Feed UI · Post and story components for the social feed.
src/components/feed - Chat UI · Conversation list, window, bubbles, and input for chat.
src/components/messages - Profile UI · Header, main content, sidebar, activity, and suggestions sections.
src/components/profile - A11y UI · AAC board, floating palette, and accessibility tools.
src/components/accessibility - Dashboard widgets · Medication, network, contacts, and prayer-time widgets.
src/components/widgets
Platform services
Cross-cutting contexts, data access, and external integrations.
- Auth guard · Protects dashboard access for signed-in users.
src/components/auth-guard.tsx - Auth context · Central auth state and Firebase-backed user session boundary.
src/context/auth-context.tsx - Language context · App-wide localization and language selection state.
src/context/language-context.tsx - Accessibility context · Accessibility profile and shape-shifting UI state.
src/context/accessibility-context.tsx - AI context · Shared assistant state for embedded AI features.
src/context/ai-context.tsx - Radio context · Global radio/player state for the companion audio experience.
src/context/radio-context.tsx - Firebase · Auth, realtime data, and messaging backend dependencies.
src/lib/firebase.ts - Push pipeline · Firebase Cloud Messaging setup and service worker delivery path.
src/lib/fcm.ts - Notifications hook · Foreground notification consumption inside React.
src/hooks/use-notifications.ts - Gemini AI · Remote model used by the assistant experience.
- Locale files · JSON translation bundles for supported languages.
public/locales - Messaging SW · Push and background messaging boundary.
public/firebase-messaging-sw.js - Madari Lens · Auxiliary browser-extension-style asset bundle.
madari-lens
Connections 28
- 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.