# basharalshameri/rafiq-al-quran-v2 architecture

> Architecture diagram of the GitHub repository basharalshameri/rafiq-al-quran-v2, 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/basharalshameri/rafiq-al-quran-v2
- Repository: https://github.com/basharalshameri/rafiq-al-quran-v2

## Overview

Rafiq is an education and Quran-program administration platform, with a web frontend and a TypeScript/Express backend. The principal user workflow is to enter through the web app, navigate role-appropriate administration screens, and use feature APIs to manage organizational and educational records. Backend controllers pass scoped requests to domain services; sampled code confirms this for authentication, exams, finance, golden records, users, and staff operations. The README is empty, and source excerpts are selective, so the graph preserves visible product areas but omits uncertain frontend-to-backend wiring and unsampled persistence links.

Main entry points: [`frontend/src/features/search/useGlobalSearch.ts`](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/search/useGlobalSearch.ts) (Global search), [`backend/src/modules/exams/exams.controller.ts`](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.controller.ts) (Exam controller), [`frontend/src/App.tsx`](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/App.tsx) (Web app), [`frontend/src/features/users/users.api.ts`](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/users/users.api.ts) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_router["Page router<br/>[router.tsx]"]
  node_authui["Sign-in UI<br/>[auth.api.ts]"]
  node_search["Global search<br/>[useGlobalSearch.ts]"]
end

subgraph group_identity["Identity and organization"]
  node_usersapi["User API<br/>[users.api.ts]"]
  node_orgapi["Organization API<br/>[org.api.ts]"]
  node_usersctrl["User controller"]
  node_userssvc["User service<br/>[users.service.ts]"]
  node_authsvc["Authentication service<br/>[auth.service.ts]"]
end

subgraph group_education["Education workflows"]
  node_examsctrl["Exam controller"]
  node_examssvc["Exam service<br/>[exams.service.ts]"]
  node_workflow["Exam workflow"]
  node_goldctrl["Golden records"]
end

subgraph group_operations["Finance and operations"]
  node_financectrl["Finance controller"]
  node_financesvcs["Finance services"]
  node_staffctrl["Staff operations"]
  node_attendance["Attendance services"]
end

subgraph group_runtime["Backend runtime"]
  node_appserver["HTTP server<br/>[server.ts]"]
  node_approuter["API router<br/>[router.ts]"]
end

node_user(("Staff user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"renders routes"| node_router
node_user -->|"signs in"| node_authui
node_search -->|"queries people"| node_usersapi
node_search -->|"queries centers"| node_orgapi
node_usersctrl -->|"calls"| node_userssvc
node_authsvc --> node_usersapi
node_examsctrl -->|"calls"| node_examssvc
node_examsctrl -->|"calls"| node_workflow
node_goldctrl --> node_workflow
node_financectrl -->|"calls"| node_financesvcs
node_staffctrl -->|"calls"| node_attendance
node_appserver -->|"dispatches"| node_approuter

click node_webapp "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/App.tsx"
click node_router "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/app/router.tsx"
click node_authui "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/auth/auth.api.ts"
click node_search "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/search/useGlobalSearch.ts"
click node_usersapi "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/users/users.api.ts"
click node_orgapi "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/org/org.api.ts"
click node_usersctrl "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/users/users.controller.ts"
click node_userssvc "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/users/users.service.ts"
click node_authsvc "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/auth/auth.service.ts"
click node_examsctrl "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.controller.ts"
click node_examssvc "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.service.ts"
click node_workflow "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.workflow.service.ts"
click node_goldctrl "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/golden-records/golden-records.controller.ts"
click node_financectrl "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/finance-v2/finance-v2.controller.ts"
click node_financesvcs "https://github.com/basharalshameri/rafiq-al-quran-v2/tree/main/backend/src/modules/finance-v2/services"
click node_staffctrl "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/staff-operations/staff-operations.controller.ts"
click node_attendance "https://github.com/basharalshameri/rafiq-al-quran-v2/tree/main/backend/src/modules/attendance"
click node_appserver "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/app/server.ts"
click node_approuter "https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/app/router.ts"

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_webapp,node_router,node_authui,node_search,node_user toneBlue
class node_usersapi,node_orgapi,node_usersctrl,node_userssvc,node_authsvc toneAmber
class node_examsctrl,node_examssvc,node_workflow,node_goldctrl toneMint
class node_financectrl,node_financesvcs,node_staffctrl,node_attendance toneRose
class node_appserver,node_approuter toneIndigo
```

## Components

### Web application

- [Web app](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Page router](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/app/router.tsx): `frontend/src/app/router.tsx`
- [Sign-in UI](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/auth/auth.api.ts): `frontend/src/features/auth/auth.api.ts`
- [Global search](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/search/useGlobalSearch.ts): `frontend/src/features/search/useGlobalSearch.ts`

### Identity and organization

- [User API](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/users/users.api.ts): `frontend/src/features/users/users.api.ts`
- [Organization API](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/frontend/src/features/org/org.api.ts): `frontend/src/features/org/org.api.ts`
- [User controller](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/users/users.controller.ts): `backend/src/modules/users/users.controller.ts`
- [User service](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/users/users.service.ts): `backend/src/modules/users/users.service.ts`
- [Authentication service](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/auth/auth.service.ts): `backend/src/modules/auth/auth.service.ts`

### Education workflows

- [Exam controller](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.controller.ts): `backend/src/modules/exams/exams.controller.ts`
- [Exam service](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.service.ts): `backend/src/modules/exams/exams.service.ts`
- [Exam workflow](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/exams/exams.workflow.service.ts): `backend/src/modules/exams/exams.workflow.service.ts`
- [Golden records](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/golden-records/golden-records.controller.ts): `backend/src/modules/golden-records/golden-records.controller.ts`

### Finance and operations

- [Finance controller](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/finance-v2/finance-v2.controller.ts): `backend/src/modules/finance-v2/finance-v2.controller.ts`
- [Finance services](https://github.com/basharalshameri/rafiq-al-quran-v2/tree/main/backend/src/modules/finance-v2/services): `backend/src/modules/finance-v2/services`
- [Staff operations](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/modules/staff-operations/staff-operations.controller.ts): `backend/src/modules/staff-operations/staff-operations.controller.ts`
- [Attendance services](https://github.com/basharalshameri/rafiq-al-quran-v2/tree/main/backend/src/modules/attendance): `backend/src/modules/attendance`

### Backend runtime

- [HTTP server](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/app/server.ts): `backend/src/app/server.ts`
- [API router](https://github.com/basharalshameri/rafiq-al-quran-v2/blob/main/backend/src/app/router.ts): `backend/src/app/router.ts`

### Other components

- **Staff user**

## Connections

- Staff user → Web app: uses
- Web app → Page router: renders routes
- Staff user → Sign-in UI: signs in
- Global search → User API: queries people
- Global search → Organization API: queries centers
- User controller → User service: calls
- Authentication service → User API
- Exam controller → Exam service: calls
- Exam controller → Exam workflow: calls
- Golden records → Exam workflow
- Finance controller → Finance services: calls
- Staff operations → Attendance services: calls
- HTTP server → API router: dispatches