# asse-byte/halaqatna_app architecture

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

- Interactive diagram: https://gitdiagram.com/asse-byte/halaqatna_app
- Repository: https://github.com/asse-byte/halaqatna_app

## Overview

Halaqtna manages Quran memorization circles: teachers record attendance and recitation sessions, after which the API derives learner analytics, gamification progress, reports, and optional forecasts. Students and circle staff use the web client; teachers can also record sessions in the mobile client, including offline queueing. The API is the central runtime boundary for authorization and domain operations. The README documents the API-to-ML prediction service and database, but the supplied excerpts do not show the full route/controller or persistence wiring; those links are included only where documented, and unsampled details are not inferred.

Main entry points: [`api/app/Http/Controllers/SessionController.php`](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/SessionController.php) (Session operations), [`api/routes/api.php`](https://github.com/asse-byte/halaqatna_app/blob/main/api/routes/api.php) (API routes), [`api/app/Http/Controllers/StudentController.php`](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/StudentController.php) (Student operations), [`mobile/src/screens/LogSessionScreen.jsx`](https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/screens/LogSessionScreen.jsx) (Mobile session entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web application<br/>[App.jsx]"]
  node_web_session["Session entry<br/>[LogSession.jsx]"]
  node_web_api["Web API client<br/>[api.js]"]
  node_mobile["Teacher mobile app<br/>[App.js]"]
  node_mobile_session["Mobile session entry"]
  node_offline_queue["Offline queue<br/>[offline.js]"]
  node_mobile_api["Mobile API client<br/>[api.js]"]
end

subgraph group_api_core["API and access"]
  node_api_routes["API routes<br/>[api.php]"]
  node_auth["Authentication and RBAC"]
  node_sessions["Session operations"]
  node_students["Student operations"]
  node_circles["Circle operations"]
end

subgraph group_learning["Learning services"]
  node_learner_data[("Learner records<br/>[Student.php]")]
  node_session_data[("Recitation records")]
  node_analytics["Learning analytics"]
  node_gamification["XP and achievements"]
  node_reports["Reports and summaries<br/>[ReportService.php]"]
end

subgraph group_integrations["External services"]
  node_ml_client["Forecast client<br/>[MlClient.php]"]
  node_ml_service["Prediction service<br/>[main.py]"]
  node_db[("MySQL database")]
end

node_staff(("Circle staff"))
node_student_user(("Student"))

node_staff -->|"uses"| node_web
node_student_user -->|"uses"| node_web
node_staff -->|"uses"| node_mobile
node_web -->|"routes to"| node_web_session
node_web_session -->|"requests data"| node_web_api
node_web_api -.->|"calls API"| node_api_routes
node_mobile -->|"routes to"| node_mobile_session
node_mobile_session -->|"queues offline"| node_offline_queue
node_mobile_session -->|"calls"| node_mobile_api
node_offline_queue -->|"replays requests"| node_mobile_api
node_mobile_api -.->|"calls API"| node_api_routes
node_api_routes -->|"routes to"| node_sessions
node_api_routes -->|"routes to"| node_students
node_api_routes -->|"routes to"| node_circles
node_sessions -->|"checks access"| node_auth
node_students -->|"checks access"| node_auth
node_sessions -->|"writes sessions"| node_session_data
node_students -->|"reads learners"| node_learner_data
node_sessions -->|"updates metrics"| node_analytics
node_sessions -->|"awards progress"| node_gamification
node_students -->|"computes metrics"| node_analytics
node_circles -->|"builds reports"| node_reports
node_sessions -->|"requests forecast"| node_ml_client
node_students -->|"requests forecast"| node_ml_client
node_ml_client -->|"posts forecasts"| node_ml_service
node_api_routes -.->|"persists domain data"| node_db
node_ml_service -.->|"reads training data"| node_db

click node_web "https://github.com/asse-byte/halaqatna_app/blob/main/frontend/src/App.jsx"
click node_web_session "https://github.com/asse-byte/halaqatna_app/blob/main/frontend/src/pages/teacher/LogSession.jsx"
click node_web_api "https://github.com/asse-byte/halaqatna_app/blob/main/frontend/src/lib/api.js"
click node_mobile "https://github.com/asse-byte/halaqatna_app/blob/main/mobile/App.js"
click node_mobile_session "https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/screens/LogSessionScreen.jsx"
click node_offline_queue "https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/offline.js"
click node_mobile_api "https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/api.js"
click node_api_routes "https://github.com/asse-byte/halaqatna_app/blob/main/api/routes/api.php"
click node_auth "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/AuthRbacService.php"
click node_sessions "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/SessionController.php"
click node_students "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/StudentController.php"
click node_circles "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/CircleController.php"
click node_learner_data "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Models/Student.php"
click node_session_data "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Models/RecitationSession.php"
click node_analytics "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/AnalyticsEngine.php"
click node_gamification "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/GamificationEngine.php"
click node_reports "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/ReportService.php"
click node_ml_client "https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/MlClient.php"
click node_ml_service "https://github.com/asse-byte/halaqatna_app/blob/main/ml/main.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_web,node_web_session,node_web_api,node_mobile,node_mobile_session,node_offline_queue,node_mobile_api toneBlue
class node_api_routes,node_auth,node_sessions,node_students,node_circles toneAmber
class node_learner_data,node_session_data,node_analytics,node_gamification,node_reports toneMint
class node_ml_client,node_ml_service,node_db toneRose
class node_staff,node_student_user toneIndigo
```

## Components

### User clients

- [Web application](https://github.com/asse-byte/halaqatna_app/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session entry](https://github.com/asse-byte/halaqatna_app/blob/main/frontend/src/pages/teacher/LogSession.jsx): `frontend/src/pages/teacher/LogSession.jsx`
- [Web API client](https://github.com/asse-byte/halaqatna_app/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`
- [Teacher mobile app](https://github.com/asse-byte/halaqatna_app/blob/main/mobile/App.js): `mobile/App.js`
- [Mobile session entry](https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/screens/LogSessionScreen.jsx): `mobile/src/screens/LogSessionScreen.jsx`
- [Offline queue](https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/offline.js): `mobile/src/offline.js`
- [Mobile API client](https://github.com/asse-byte/halaqatna_app/blob/main/mobile/src/api.js): `mobile/src/api.js`

### API and access

- [API routes](https://github.com/asse-byte/halaqatna_app/blob/main/api/routes/api.php): `api/routes/api.php`
- [Authentication and RBAC](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/AuthRbacService.php): `api/app/Services/AuthRbacService.php`
- [Session operations](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/SessionController.php): `api/app/Http/Controllers/SessionController.php`
- [Student operations](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/StudentController.php): `api/app/Http/Controllers/StudentController.php`
- [Circle operations](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Http/Controllers/CircleController.php): `api/app/Http/Controllers/CircleController.php`

### Learning services

- [Learner records](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Models/Student.php): `api/app/Models/Student.php`
- [Recitation records](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Models/RecitationSession.php): `api/app/Models/RecitationSession.php`
- [Learning analytics](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/AnalyticsEngine.php): `api/app/Services/AnalyticsEngine.php`
- [XP and achievements](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/GamificationEngine.php): `api/app/Services/GamificationEngine.php`
- [Reports and summaries](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/ReportService.php): `api/app/Services/ReportService.php`

### External services

- [Forecast client](https://github.com/asse-byte/halaqatna_app/blob/main/api/app/Services/MlClient.php): `api/app/Services/MlClient.php`
- [Prediction service](https://github.com/asse-byte/halaqatna_app/blob/main/ml/main.py): `ml/main.py`
- **MySQL database**

### Other components

- **Circle staff**
- **Student**

## Connections

- Circle staff → Web application: uses (evidence: `README.md`)
- Student → Web application: uses (evidence: `README.md`)
- Circle staff → Teacher mobile app: uses (evidence: `README.md`)
- Web application → Session entry: routes to (evidence: `frontend/src/App.jsx`)
- Session entry → Web API client: requests data (evidence: `frontend/src/pages/teacher/LogSession.jsx`)
- Web API client → API routes: calls API (evidence: `README.md`)
- Teacher mobile app → Mobile session entry: routes to (evidence: `mobile/App.js`)
- Mobile session entry → Offline queue: queues offline (evidence: `mobile/src/screens/LogSessionScreen.jsx`)
- Mobile session entry → Mobile API client: calls (evidence: `mobile/src/screens/LogSessionScreen.jsx`)
- Offline queue → Mobile API client: replays requests (evidence: `mobile/src/offline.js`)
- Mobile API client → API routes: calls API (evidence: `README.md`)
- API routes → Session operations: routes to (evidence: `api/routes/api.php`)
- API routes → Student operations: routes to (evidence: `api/routes/api.php`)
- API routes → Circle operations: routes to (evidence: `api/routes/api.php`)
- Session operations → Authentication and RBAC: checks access (evidence: `api/app/Http/Controllers/SessionController.php`)
- Student operations → Authentication and RBAC: checks access (evidence: `api/app/Http/Controllers/StudentController.php`)
- Session operations → Recitation records: writes sessions (evidence: `api/app/Http/Controllers/SessionController.php`)
- Student operations → Learner records: reads learners (evidence: `api/app/Http/Controllers/StudentController.php`)
- Session operations → Learning analytics: updates metrics (evidence: `api/app/Http/Controllers/SessionController.php`)
- Session operations → XP and achievements: awards progress (evidence: `api/app/Http/Controllers/SessionController.php`)
- Student operations → Learning analytics: computes metrics (evidence: `api/app/Http/Controllers/StudentController.php`)
- Circle operations → Reports and summaries: builds reports (evidence: `api/app/Http/Controllers/CircleController.php`)
- Session operations → Forecast client: requests forecast (evidence: `api/app/Http/Controllers/SessionController.php`)
- Student operations → Forecast client: requests forecast (evidence: `api/app/Http/Controllers/StudentController.php`)
- Forecast client → Prediction service: posts forecasts (evidence: `api/app/Services/MlClient.php`)
- API routes → MySQL database: persists domain data (evidence: `README.md`)
- Prediction service → MySQL database: reads training data (evidence: `README.md`)
