# musthafaak56/nahdimandi architecture

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

- Interactive diagram: https://gitdiagram.com/musthafaak56/nahdimandi
- Repository: https://github.com/musthafaak56/nahdimandi

## Overview

1. This is a single-page React app built with Vite and deployed on Firebase Hosting. The runtime is browser-based, with Firebase services providing auth, database, messaging, and hosting integration.

2. The application has two major user paths: a public customer flow and a protected admin flow. Public pages include the landing/join experience and live status tracking; admin pages are behind authentication and expose operational controls, queue history, analytics, and support/contact tooling.

3. Routing is organized by page-level components under `src/pages`. The key routes are `/` and `/join` for check-in, `/status?id={queueId}` for customer tracking, `/admin/login` for authentication, and `/admin` for the dashboard. `ProtectedRoute` is the main boundary that keeps admin-only views gated.

4. Queue state is stored in Firestore using a date-scoped model. The primary customer record lives under `customers_per_day/{dateKey}/entries/{queueId}`, while `queue_counters/{dateKey}` ensures sequential numbering per day. This makes daily operational resets a first-class part of the data model.

5. There is a deliberate privacy boundary between internal queue data and customer-visible state. `queue_public/{queueId}` mirrors only non-sensitive queue/order fields so customers can see status and position without access to personal details like phone number or location.

6. Live queue behavior is driven by Firebase Auth and Firestore realtime reads/writes. Anonymous auth is used for customer sessions, while admin users use email/password. `AuthProvider` likely centralizes user/session state, and Firestore updates drive UI refreshes across both customer and admin screens.

7. Notifications and mobile-style “table ready” behavior are handled with Firebase Cloud Messaging. The repo includes a service worker at `public/firebase-messaging-sw.js`, and `src/lib/notifications.js` plus `src/lib/sound.js` indicate the app can combine push notifications with in-browser alerts for queue readiness.

8. Location-aware logic is a separate support subsystem. `src/lib/geofence.js`, `src/lib/phone.js`, `src/lib/time.js`, and `shared/storeLocations.js` suggest reusable domain logic for validating check-in location, formatting/normalizing local phone numbers, and handling date/time queue behavior consistently across views.

9. The admin dashboard is not just CRUD; it includes operational history and analytics. `AdminDashboardPage`, `AdminHistoryView`, `SummaryBar`, and `StatusBadge` imply a dashboard that summarizes active queues, paginates historical records, and computes business metrics like peak hours/days/dates from stored queue history.

10. Support and escalation are modeled explicitly. Firestore contains `support_tickets/{ticketId}`, and the dashboard has an Admin Contact tab with ticket creation plus shared contact information. The README notes a super-admin inbox restriction, so this is a privileged support workflow layered on top of the main queue system.

11. There is a separate demo/pitch/video subsystem under `src/remotion`. That code is for generating presentation videos or demo content, not core queue operations. It is architecturally distinct from the live app UI, even though it reuses project theme/UI concepts.

12. Testing and operational automation are split out cleanly. `tests/e2e` with Playwright covers queue flows end to end, while `scripts/seed-admins.mjs` seeds privileged admin records in Firestore. This indicates the app depends on both authenticated setup and realistic browser flow verification.

13. Firebase configuration is an important external boundary. The app depends on Auth providers, Firestore rules and indexes, and FCM/VAPID setup; `firebase.json`, `firestore.rules`, and `firestore.indexes.json` are core infrastructure artifacts, not incidental config.

14. Overall, the architecture centers on a realtime queueing domain: customer check-in creates a dated queue entry, queue counters assign the next number, a public mirror exposes safe status updates, and admin tooling updates queue state while tracking history, analytics, and support. The main diagram should emphasize the split between public customer surfaces, admin-only operations, and Firestore as the shared source of truth.

Main entry points: [`src/App.jsx`](https://github.com/musthafaak56/nahdimandi/blob/main/src/App.jsx) (App router), [`src/pages/AdminDashboardPage.jsx`](https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/AdminDashboardPage.jsx) (Dashboard), [`src/lib/queue.js`](https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/queue.js) (Queue logic), [`src/pages/JoinPage.jsx`](https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/JoinPage.jsx) (Join page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_main(("Main entry<br/>React bootstrap<br/>[main.jsx]"))
  node_app_shell["App router<br/>Route shell<br/>[App.jsx]"]
  node_auth_provider["Auth provider<br/>Session state<br/>[AuthProvider.jsx]"]
  node_protected_route{{"Protected route<br/>Auth gate<br/>[ProtectedRoute.jsx]"}}
end

subgraph group_public["Customer flow"]
  node_join_page["Join page<br/>Customer intake<br/>[JoinPage.jsx]"]
  node_status_page["Status page<br/>Customer tracking<br/>[StatusPage.jsx]"]
  node_queue_card["Queue card<br/>Customer UI<br/>[QueueCard.jsx]"]
end

subgraph group_admin["Admin ops"]
  node_admin_login["Admin login<br/>Auth page<br/>[AdminLoginPage.jsx]"]
  node_admin_dashboard["Dashboard<br/>Admin console"]
  node_admin_history["History view<br/>Ops history"]
  node_admin_contact["Contact view<br/>Support workflow"]
  node_summary_bar["Summary bar<br/>Metrics panel<br/>[SummaryBar.jsx]"]
  node_status_badge["Status badge<br/>State indicator<br/>[StatusBadge.jsx]"]
end

subgraph group_domain["Domain logic"]
  node_queue_lib["Queue logic<br/>Firestore model<br/>[queue.js]"]
  node_support_lib["Support logic<br/>Ticket model<br/>[support.js]"]
  node_geo_phone_time["Location utils<br/>Domain helpers<br/>[geofence.js]"]
  node_store_locations["Store locations<br/>Shared data<br/>[storeLocations.js]"]
end

subgraph group_infra["Firebase + automation"]
  node_notifications["Notifications<br/>FCM + alerts<br/>[notifications.js]"]
  node_firebase_client["Firebase client<br/>SDK setup<br/>[firebase.js]"]
  node_messaging_sw{{"Messaging SW<br/>Service worker"}}
end

subgraph group_demo["Demo media"]
  node_remotion_pitch["Pitch video<br/>Presentation render<br/>[PitchVideo.jsx]"]
end

node_main -->|"boots"| node_app_shell
node_app_shell -->|"wraps"| node_auth_provider
node_app_shell -->|"routes"| node_join_page
node_app_shell -->|"routes"| node_status_page
node_app_shell -->|"routes"| node_admin_login
node_app_shell -->|"guards"| node_protected_route
node_protected_route -->|"unlocks"| node_admin_dashboard
node_join_page -->|"creates"| node_queue_lib
node_status_page -->|"renders"| node_queue_card
node_status_page -->|"reads"| node_queue_lib
node_admin_dashboard -->|"shows"| node_summary_bar
node_admin_dashboard -->|"reviews"| node_admin_history
node_admin_dashboard -->|"supports"| node_admin_contact
node_admin_dashboard -->|"uses"| node_status_badge
node_admin_history -->|"queries"| node_queue_lib
node_admin_contact -->|"opens"| node_support_lib
node_queue_lib -->|"persists"| node_firebase_client
node_support_lib -->|"persists"| node_firebase_client
node_geo_phone_time -->|"uses"| node_store_locations
node_join_page -->|"validates"| node_geo_phone_time
node_queue_lib -->|"triggers"| node_notifications
node_notifications -->|"delivers"| node_messaging_sw
node_notifications -->|"configures"| node_firebase_client
node_remotion_pitch -.->|"shares theme"| node_app_shell

click node_main "https://github.com/musthafaak56/nahdimandi/blob/main/src/main.jsx"
click node_app_shell "https://github.com/musthafaak56/nahdimandi/blob/main/src/App.jsx"
click node_auth_provider "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/AuthProvider.jsx"
click node_protected_route "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/ProtectedRoute.jsx"
click node_join_page "https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/JoinPage.jsx"
click node_status_page "https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/StatusPage.jsx"
click node_queue_card "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/QueueCard.jsx"
click node_admin_login "https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/AdminLoginPage.jsx"
click node_admin_dashboard "https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/AdminDashboardPage.jsx"
click node_admin_history "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/AdminHistoryView.jsx"
click node_admin_contact "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/AdminContactView.jsx"
click node_summary_bar "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/SummaryBar.jsx"
click node_status_badge "https://github.com/musthafaak56/nahdimandi/blob/main/src/components/StatusBadge.jsx"
click node_queue_lib "https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/queue.js"
click node_support_lib "https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/support.js"
click node_geo_phone_time "https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/geofence.js"
click node_notifications "https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/notifications.js"
click node_firebase_client "https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/firebase.js"
click node_messaging_sw "https://github.com/musthafaak56/nahdimandi/blob/main/public/firebase-messaging-sw.js"
click node_store_locations "https://github.com/musthafaak56/nahdimandi/blob/main/shared/storeLocations.js"
click node_remotion_pitch "https://github.com/musthafaak56/nahdimandi/blob/main/src/remotion/PitchVideo.jsx"

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_app_shell,node_auth_provider,node_protected_route toneBlue
class node_join_page,node_status_page,node_queue_card toneAmber
class node_admin_login,node_admin_dashboard,node_admin_history,node_admin_contact,node_summary_bar,node_status_badge toneMint
class node_queue_lib,node_support_lib,node_geo_phone_time,node_store_locations toneRose
class node_notifications,node_firebase_client,node_messaging_sw toneIndigo
class node_remotion_pitch toneTeal
```

## Components

### App shell

Browser entry, routing, and cross-cutting providers

- [Main entry](https://github.com/musthafaak56/nahdimandi/blob/main/src/main.jsx): React bootstrap · Starts the browser app and mounts the UI · `src/main.jsx`
- [App router](https://github.com/musthafaak56/nahdimandi/blob/main/src/App.jsx): Route shell · Top-level routing and application composition · `src/App.jsx`
- [Auth provider](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/AuthProvider.jsx): Session state · Centralizes Firebase auth/session state for the app · `src/components/AuthProvider.jsx`
- [Protected route](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/ProtectedRoute.jsx): Auth gate · Guards admin-only views behind authentication · `src/components/ProtectedRoute.jsx`

### Customer flow

Public check-in and live status experience

- [Join page](https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/JoinPage.jsx): Customer intake · Public check-in and queue creation flow · `src/pages/JoinPage.jsx`
- [Status page](https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/StatusPage.jsx): Customer tracking · Public live queue status and position view · `src/pages/StatusPage.jsx`
- [Queue card](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/QueueCard.jsx): Customer UI · Displays customer queue details and status · `src/components/QueueCard.jsx`

### Admin ops

Authenticated dashboard, history, and support tooling

- [Admin login](https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/AdminLoginPage.jsx): Auth page · Email/password login for admin users · `src/pages/AdminLoginPage.jsx`
- [Dashboard](https://github.com/musthafaak56/nahdimandi/blob/main/src/pages/AdminDashboardPage.jsx): Admin console · Primary operational dashboard for live queue control · `src/pages/AdminDashboardPage.jsx`
- [History view](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/AdminHistoryView.jsx): Ops history · Paginated queue history and business metrics · `src/components/AdminHistoryView.jsx`
- [Contact view](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/AdminContactView.jsx): Support workflow · Admin support tickets and shared contact actions · `src/components/AdminContactView.jsx`
- [Summary bar](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/SummaryBar.jsx): Metrics panel · Shows active queue summaries and operational metrics · `src/components/SummaryBar.jsx`
- [Status badge](https://github.com/musthafaak56/nahdimandi/blob/main/src/components/StatusBadge.jsx): State indicator · Small status/priority indicator used across queue views · `src/components/StatusBadge.jsx`

### Domain logic

Shared queue, time, location, and support helpers

- [Queue logic](https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/queue.js): Firestore model · Queue reads, writes, counters, and public/private state mapping · `src/lib/queue.js`
- [Support logic](https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/support.js): Ticket model · Support ticket and escalation helpers · `src/lib/support.js`
- [Location utils](https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/geofence.js): Domain helpers · Geofence, phone normalization, and time/date helpers · `src/lib/geofence.js`
- [Store locations](https://github.com/musthafaak56/nahdimandi/blob/main/shared/storeLocations.js): Shared data · Reusable store/location data for geofence and check-in rules · `shared/storeLocations.js`

### Firebase + automation

Hosting, data model, messaging, and setup scripts

- [Notifications](https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/notifications.js): FCM + alerts · Push notifications and in-browser readiness alerts · `src/lib/notifications.js`
- [Firebase client](https://github.com/musthafaak56/nahdimandi/blob/main/src/lib/firebase.js): SDK setup · Firebase Auth, Firestore, and messaging integration · `src/lib/firebase.js`
- [Messaging SW](https://github.com/musthafaak56/nahdimandi/blob/main/public/firebase-messaging-sw.js): Service worker · Firebase Cloud Messaging service worker for background delivery · `public/firebase-messaging-sw.js`

### Demo media

Remotion-based pitch/demo video subsystem

- [Pitch video](https://github.com/musthafaak56/nahdimandi/blob/main/src/remotion/PitchVideo.jsx): Presentation render · Remotion scene graph for pitch/demo video generation · `src/remotion/PitchVideo.jsx`

## Connections

- Main entry → App router: boots · Browser entry mounts the routed app
- App router → Auth provider: wraps · App composition provides session state
- App router → Join page: routes · Public check-in route
- App router → Status page: routes · Public status route
- App router → Admin login: routes · Admin authentication route
- App router → Protected route: guards · Admin area is behind auth gate
- Protected route → Dashboard: unlocks · Authenticated access to dashboard
- Join page → Queue logic: creates · Check-in creates dated queue entries
- Status page → Queue card: renders · Status page displays queue state
- Status page → Queue logic: reads · Customer view subscribes to queue state
- Dashboard → Summary bar: shows · Dashboard includes live operational metrics
- Dashboard → History view: reviews · Dashboard exposes historical queue records
- Dashboard → Contact view: supports · Dashboard exposes support/contact tooling
- Dashboard → Status badge: uses · Shared status visualization across ops screens
- History view → Queue logic: queries · History view reads queue history and analytics inputs
- Contact view → Support logic: opens · Support workflow creates and manages tickets
- Queue logic → Firebase client: persists · Queue state is stored and observed in Firestore
- Support logic → Firebase client: persists · Support tickets use Firebase data services
- Location utils → Store locations: uses · Location validation depends on shared store data
- Join page → Location utils: validates · Customer intake checks location, phone, and time rules
- Queue logic → Notifications: triggers · Queue readiness can send push or local alerts
- Notifications → Messaging SW: delivers · Background FCM delivery via service worker
- Notifications → Firebase client: configures · Messaging uses Firebase SDK setup
- Pitch video → App router: shares theme · Demo media reuses project UI/theme concepts
