# mahmoudalmodalal/noor_alhoda architecture

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

- Interactive diagram: https://gitdiagram.com/mahmoudalmodalal/noor_alhoda
- Repository: https://github.com/mahmoudalmodalal/noor_alhoda

## Overview

Noor Al-Huda is an offline-first PWA for Quran-memorization center operations. Directors, teachers, and students/parents use role-specific screens to manage enrollment, attendance, memorization plans and reviews, evaluations, and progress; directors also oversee courses and reports. The frontend reads and mutates encrypted local data, then synchronizes through a Django API with PostgreSQL. README documentation establishes the main layers and sync workflow; sampled source confirms selected auth, student, review, evaluation, notification, reporting, and push-service behavior, but not every subsystem’s wiring.

Main entry points: [`backend/noor_alhuda/urls.py`](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/noor_alhuda/urls.py) (Django API routes), [`frontend/src/lib/sync/runner.ts`](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/sync/runner.ts) (Sync runner), [`frontend/src/app/(dashboard)/page.tsx`](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/app/(dashboard)/page.tsx) (Role screens), [`backend/sync/services/push_services.py`](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/sync/services/push_services.py) (Push service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA Client"]
  node_screens["Role screens<br/>[page.tsx]"]
  node_query["Query dispatcher<br/>[queries.ts]"]
  node_mutation["Mutation dispatcher<br/>[mutations.ts]"]
  node_localdb[("Encrypted local DB<br/>[schema.ts]")]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
end

subgraph group_identity["Identity &amp; Enrollment"]
  node_authsvc["Auth services<br/>[auth_services.py]"]
  node_accounts[("Account records<br/>[models.py]")]
  node_student["Student services"]
  node_teacher["Teacher operations"]
  node_enrollment[("Enrollment data<br/>[models.py]")]
end

subgraph group_learning["Learning Operations"]
  node_learningops["Plans &amp; attendance<br/>[record_services.py]"]
  node_review["Review scheduling<br/>[review_services.py]"]
  node_progress["Memorization progress"]
  node_evaluation["Evaluations"]
  node_courses["Course catalog<br/>[course_services.py]"]
  node_notifications["Messages &amp; alerts"]
end

subgraph group_oversight["Center Oversight"]
  node_oversightsvc["Reports &amp; exports<br/>[report_services.py]"]
  node_imports["Bulk data import<br/>[orchestrator.py]"]
end

subgraph group_sync["Offline Sync"]
  node_api["Django API routes<br/>[urls.py]"]
  node_syncclient["Sync runner<br/>[runner.ts]"]
  node_outbox["Pending outbox<br/>[outbox.ts]"]
  node_push["Push service<br/>[push_services.py]"]
  node_pull["Pull service<br/>[pull_services.py]"]
  node_serverdb[("PostgreSQL")]
end

node_people(("Center users"))

node_people -->|"use"| node_screens
node_screens -->|"read via"| node_query
node_query -->|"reads"| node_localdb
node_screens -->|"change via"| node_mutation
node_mutation -->|"writes"| node_localdb
node_people -->|"sign in"| node_authui
node_authui -->|"authenticates"| node_api
node_api -->|"dispatches"| node_authsvc
node_authsvc -->|"reads/writes"| node_accounts
node_api -->|"dispatches"| node_student
node_api -->|"dispatches"| node_teacher
node_student -->|"writes"| node_enrollment
node_teacher -->|"assigns"| node_enrollment
node_api -->|"dispatches"| node_learningops
node_api -->|"dispatches"| node_review
node_api -->|"dispatches"| node_progress
node_api -->|"dispatches"| node_evaluation
node_api -->|"dispatches"| node_courses
node_api -->|"dispatches"| node_notifications
node_api -->|"dispatches"| node_oversightsvc
node_api -->|"dispatches"| node_imports
node_syncclient -->|"reads pending"| node_outbox
node_syncclient -->|"requests sync"| node_api
node_api -->|"dispatches"| node_push
node_api -->|"dispatches"| node_pull
node_push -->|"applies writes"| node_serverdb
node_pull -->|"reads changes"| node_serverdb
node_push -->|"calls services"| node_student
node_syncclient -->|"applies updates"| node_localdb
node_api -->|"persists domain data"| node_serverdb

click node_screens "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/app/(dashboard)/page.tsx"
click node_query "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/hooks/queries.ts"
click node_mutation "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/hooks/mutations.ts"
click node_localdb "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/db/schema.ts"
click node_authui "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_authsvc "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/accounts/services/auth_services.py"
click node_accounts "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/accounts/models.py"
click node_student "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/students/services/student_services.py"
click node_teacher "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/teacher/services/teacher_services.py"
click node_enrollment "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/students/models.py"
click node_learningops "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/records/services/record_services.py"
click node_review "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/records/services/review_services.py"
click node_progress "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/progress/services/progress_services.py"
click node_evaluation "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/evaluations/services/evaluation_services.py"
click node_courses "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/courses/services/course_services.py"
click node_notifications "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/notifications/services/notification_services.py"
click node_oversightsvc "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/reports/services/report_services.py"
click node_imports "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/students/services/excel_import/orchestrator.py"
click node_api "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/noor_alhuda/urls.py"
click node_syncclient "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/sync/runner.ts"
click node_outbox "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/sync/outbox.ts"
click node_push "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/sync/services/push_services.py"
click node_pull "https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/sync/services/pull_services.py"

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_screens,node_query,node_mutation,node_localdb,node_authui,node_people toneBlue
class node_authsvc,node_accounts,node_student,node_teacher,node_enrollment toneAmber
class node_learningops,node_review,node_progress,node_evaluation,node_courses,node_notifications toneMint
class node_oversightsvc,node_imports toneRose
class node_api,node_syncclient,node_outbox,node_push,node_pull,node_serverdb toneIndigo
```

## Components

### PWA Client

- [Role screens](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/app/(dashboard)/page.tsx): `frontend/src/app/(dashboard)/page.tsx`
- [Query dispatcher](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/hooks/queries.ts): `frontend/src/hooks/queries.ts`
- [Mutation dispatcher](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/hooks/mutations.ts): `frontend/src/hooks/mutations.ts`
- [Encrypted local DB](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/db/schema.ts): `frontend/src/lib/db/schema.ts`
- [Auth context](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`

### Identity & Enrollment

- [Auth services](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/accounts/services/auth_services.py): `backend/accounts/services/auth_services.py`
- [Account records](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/accounts/models.py): `backend/accounts/models.py`
- [Student services](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/students/services/student_services.py): `backend/students/services/student_services.py`
- [Teacher operations](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/teacher/services/teacher_services.py): `backend/teacher/services/teacher_services.py`
- [Enrollment data](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/students/models.py): `backend/students/models.py`

### Learning Operations

- [Plans & attendance](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/records/services/record_services.py): `backend/records/services/record_services.py`
- [Review scheduling](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/records/services/review_services.py): `backend/records/services/review_services.py`
- [Memorization progress](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/progress/services/progress_services.py): `backend/progress/services/progress_services.py`
- [Evaluations](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/evaluations/services/evaluation_services.py): `backend/evaluations/services/evaluation_services.py`
- [Course catalog](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/courses/services/course_services.py): `backend/courses/services/course_services.py`
- [Messages & alerts](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/notifications/services/notification_services.py): `backend/notifications/services/notification_services.py`

### Center Oversight

- [Reports & exports](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/reports/services/report_services.py): `backend/reports/services/report_services.py`
- [Bulk data import](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/students/services/excel_import/orchestrator.py): `backend/students/services/excel_import/orchestrator.py`

### Offline Sync

- [Django API routes](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/noor_alhuda/urls.py): `backend/noor_alhuda/urls.py`
- [Sync runner](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/sync/runner.ts): `frontend/src/lib/sync/runner.ts`
- [Pending outbox](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/frontend/src/lib/sync/outbox.ts): `frontend/src/lib/sync/outbox.ts`
- [Push service](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/sync/services/push_services.py): `backend/sync/services/push_services.py`
- [Pull service](https://github.com/mahmoudalmodalal/noor_alhoda/blob/main/backend/sync/services/pull_services.py): `backend/sync/services/pull_services.py`
- **PostgreSQL**

### Other components

- **Center users**

## Connections

- Center users → Role screens: use
- Role screens → Query dispatcher: read via
- Query dispatcher → Encrypted local DB: reads
- Role screens → Mutation dispatcher: change via
- Mutation dispatcher → Encrypted local DB: writes
- Center users → Auth context: sign in
- Auth context → Django API routes: authenticates
- Django API routes → Auth services: dispatches
- Auth services → Account records: reads/writes
- Django API routes → Student services: dispatches
- Django API routes → Teacher operations: dispatches
- Student services → Enrollment data: writes
- Teacher operations → Enrollment data: assigns
- Django API routes → Plans & attendance: dispatches
- Django API routes → Review scheduling: dispatches
- Django API routes → Memorization progress: dispatches
- Django API routes → Evaluations: dispatches
- Django API routes → Course catalog: dispatches
- Django API routes → Messages & alerts: dispatches
- Django API routes → Reports & exports: dispatches
- Django API routes → Bulk data import: dispatches
- Sync runner → Pending outbox: reads pending
- Sync runner → Django API routes: requests sync
- Django API routes → Push service: dispatches
- Django API routes → Pull service: dispatches
- Push service → PostgreSQL: applies writes
- Pull service → PostgreSQL: reads changes
- Push service → Student services: calls services
- Sync runner → Encrypted local DB: applies updates
- Django API routes → PostgreSQL: persists domain data