# tauhid219/pwapractice architecture

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

- Interactive diagram: https://gitdiagram.com/tauhid219/pwapractice
- Repository: https://github.com/tauhid219/pwapractice

## Overview

1. **Overall shape**
   - This is a Laravel 12 monolith for a quiz-learning PWA, split into three main surfaces: **guest/auth**, **student/frontend**, and **admin**.
   - The core domain is educational content and assessment: categories, levels, questions, quiz attempts, live exams, user progress, and RBAC-managed administration.

2. **HTTP entry and routing**
   - Requests enter through Laravel’s normal `public/index.php` front controller and are routed mainly by `routes/web.php` and `routes/auth.php`.
   - Controllers are organized by boundary: `app/Http/Controllers/Auth`, `Frontend`, and `Admin`, which makes the UI/application split explicit at the routing layer.

3. **Presentation layer split**
   - The app uses Blade views heavily, with distinct layout families:
     - `resources/views/layouts/*` for shared app/admin shells
     - `resources/views/frontend/*` for student-facing quiz/live-exam screens
     - `resources/views/admin/*` for management screens
   - View components and dedicated layout classes in `app/View/Components` keep the UI shell separate from feature pages.

4. **Student-facing learning flow**
   - The frontend controllers (`FrontendController`, `Frontend/QuizController`, `Frontend/LiveExamController`) drive the learner experience.
   - Students browse levels/questions, take quizzes, and take live exams; results are rendered in separate result pages.
   - `app/Services/QuizScoringService.php` is the main scoring boundary for quiz evaluation, keeping grading logic out of controllers.

5. **Live exam subsystem**
   - Live exams are modeled separately from regular quizzes using `LiveExam`, `LiveExamQuestion`, and `LiveExamAttempt`.
   - The live exam flow includes dedicated create/manage/result screens in the admin panel and taking/results screens in the frontend.
   - Anti-cheat and exam telemetry are part of the domain: `tab_switches` is tracked on live exam attempts, and there is a queued job `ProcessLiveExamScore` for post-submission processing.

6. **Content management and admin operations**
   - Admin controllers manage the content catalog: categories, levels, questions, users, roles, permissions, and live exams.
   - Admin views include CRUD pages plus specialized pages like live exam question management and results reporting.
   - This side is the operational control plane for maintaining the learning content and exam setup.

7. **Data import/export boundary**
   - Question data can be bulk imported and exported via `app/Imports/*` and `app/Exports/*`.
   - Separate import/export types exist for standard questions and live exam question templates, which suggests a deliberate distinction between reusable question banks and exam-specific assemblies.

8. **Domain model and persistence**
   - The primary tables/entities are `users`, `categories`, `levels`, `questions`, `quiz_attempts`, `user_progress`, `live_exams`, `live_exam_questions`, `live_exam_attempts`, and `read_questions`.
   - Migrations show the schema evolved around quiz scoring, exam analytics, streaks, and localized/content metadata such as options and acceptable answers.
   - Factories and seeders provide a reproducible baseline dataset for categories, levels, chapters, questions, and roles/permissions.

9. **RBAC and access boundaries**
   - Authorization is a first-class subsystem, backed by `config/permission.php` and the `permission_tables` migration, indicating Spatie Laravel-Permission usage.
   - Middleware like `IsAdmin` and `CheckLevelAccess` enforce role- and content-based access at the HTTP boundary.
   - The admin area is therefore not just a UI split; it is protected by explicit authorization rules.

10. **Request validation and form contracts**
   - Feature actions are guarded by dedicated Form Request classes such as `StoreQuestionRequest`, `SubmitQuizRequest`, `SubmitLiveExamRequest`, and profile/auth requests.
   - This keeps validation and authorization close to the input boundary, separate from controller orchestration and domain logic.

11. **PWA and client-side runtime**
   - The project includes a real offline-capable PWA layer: `public/manifest.json`, `public/sw.js`, icons, and offline fallback views.
   - `public/frontend/js/timer-worker.js` and bundled frontend assets indicate client-side support for exam timing independent of the main page lifecycle.
   - Sounds and worker-based timing are part of the learner experience, especially for quiz/live-exam interactions.

12. **Cross-cutting concerns**
   - `SetLocale` supports bilingual content (`lang/en.json`, `lang/bn.json`), so localization is built into the request pipeline.
   - `SecurityHeaders` is a dedicated middleware for response hardening.
   - `ProfileController` and profile views show that user account management is a shared concern across student/admin experiences.

13. **Background processing and platform services**
   - Laravel’s queue system is enabled (`database/jobs` migration and `config/queue.php`), with scoring work offloaded to a job for live exams.
   - Cache and session infrastructure are standard Laravel services, with MySQL/SQLite as supported persistence targets.
   - The architecture is largely server-rendered, with the PWA and worker layer augmenting, not replacing, the backend.

14. **Verification and quality**
   - The test suite is broad and architecture-aware: feature tests cover auth, RBAC, quiz flows, live exams, profile/progress, and admin question management, while unit tests cover scoring and streak logic.
   - This suggests the repo’s critical boundaries are meant to be preserved through tests: authentication, authorization, exam correctness, and scoring behavior.

Main entry points: [`routes/web.php`](https://github.com/tauhid219/pwapractice/blob/main/routes/web.php) (Web routes), [`app/Http/Controllers/Admin`](https://github.com/tauhid219/pwapractice/tree/main/app/Http/Controllers/Admin) (Admin controllers), [`app/Models`](https://github.com/tauhid219/pwapractice/tree/main/app/Models) (Domain models), [`resources/views/frontend`](https://github.com/tauhid219/pwapractice/tree/main/resources/views/frontend) (Student views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & routing"]
  node_public_index["Front controller<br/>HTTP entry<br/>[index.php]"]
  node_web_routes["Web routes<br/>route map<br/>[web.php]"]
  node_auth_routes["Auth routes<br/>route map<br/>[auth.php]"]
end

subgraph group_presentation["Presentation layer"]
  node_app_layouts["Layout shells<br/>view components"]
  node_frontend_views["Student views<br/>Blade screens"]
  node_admin_views["Admin views<br/>Blade screens"]
end

subgraph group_learner["Learner flow"]
  node_auth_controllers["Auth controllers"]
  node_frontend_controller["Frontend shell<br/>controller"]
  node_quiz_controller["Quiz flow<br/>controller<br/>[QuizController.php]"]
  node_live_exam_controller["Live exam flow<br/>controller"]
  node_profile_controller["Profile<br/>controller"]
end

subgraph group_admin["Admin control plane"]
  node_admin_controllers["Admin controllers"]
end

subgraph group_domain["Domain & persistence"]
  node_quiz_scoring["Scoring service"]
  node_live_exam_job["Score job<br/>queue job"]
  node_domain_models[("Domain models<br/>Eloquent models")]
  node_imports_exports["Import/export<br/>data pipeline"]
  node_db_schema[("Schema & seed<br/>migrations and seeders")]
end

subgraph group_platform["Platform services"]
  node_set_locale(("Locale<br/>middleware<br/>[SetLocale.php]"))
  node_security_headers(("Security headers<br/>middleware"))
  node_is_admin(("Admin gate<br/>middleware<br/>[IsAdmin.php]"))
  node_check_level_access(("Level gate<br/>middleware"))
  node_rbac_config["RBAC config<br/>permission config<br/>[permission.php]"]
  node_locale_files["Translations<br/>i18n assets"]
  node_pwa_assets["PWA assets<br/>offline runtime<br/>[manifest.json]"]
end

node_public_index -->|"dispatches to"| node_web_routes
node_web_routes -->|"includes"| node_auth_routes
node_web_routes -->|"applies"| node_set_locale
node_web_routes -->|"applies"| node_security_headers
node_web_routes -->|"guards admin"| node_is_admin
node_web_routes -->|"guards content"| node_check_level_access
node_web_routes -->|"routes to"| node_auth_controllers
node_web_routes -->|"routes to"| node_frontend_controller
node_web_routes -->|"routes to"| node_quiz_controller
node_web_routes -->|"routes to"| node_live_exam_controller
node_web_routes -->|"routes to"| node_profile_controller
node_web_routes -->|"routes to"| node_admin_controllers
node_frontend_controller -->|"renders"| node_frontend_views
node_quiz_controller -->|"renders"| node_frontend_views
node_live_exam_controller -->|"renders"| node_frontend_views
node_admin_controllers -->|"renders"| node_admin_views
node_auth_controllers -->|"uses"| node_app_layouts
node_frontend_controller -->|"uses"| node_app_layouts
node_admin_controllers -->|"uses"| node_app_layouts
node_quiz_controller -->|"scores with"| node_quiz_scoring
node_live_exam_controller -->|"queues"| node_live_exam_job
node_quiz_scoring -->|"reads/writes"| node_domain_models
node_live_exam_job -->|"updates"| node_domain_models
node_admin_controllers -->|"manages"| node_domain_models
node_imports_exports -->|"moves data for"| node_domain_models
node_rbac_config -->|"authorizes"| node_admin_controllers
node_locale_files -->|"drives"| node_set_locale
node_pwa_assets -->|"supports"| node_frontend_views
node_db_schema -->|"backing store"| node_domain_models

click node_public_index "https://github.com/tauhid219/pwapractice/blob/main/public/index.php"
click node_web_routes "https://github.com/tauhid219/pwapractice/blob/main/routes/web.php"
click node_auth_routes "https://github.com/tauhid219/pwapractice/blob/main/routes/auth.php"
click node_set_locale "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/SetLocale.php"
click node_security_headers "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/SecurityHeaders.php"
click node_is_admin "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/IsAdmin.php"
click node_check_level_access "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/CheckLevelAccess.php"
click node_app_layouts "https://github.com/tauhid219/pwapractice/tree/main/app/View/Components"
click node_frontend_views "https://github.com/tauhid219/pwapractice/tree/main/resources/views/frontend"
click node_admin_views "https://github.com/tauhid219/pwapractice/tree/main/resources/views/admin"
click node_auth_controllers "https://github.com/tauhid219/pwapractice/tree/main/app/Http/Controllers/Auth"
click node_frontend_controller "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/FrontendController.php"
click node_quiz_controller "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/Frontend/QuizController.php"
click node_live_exam_controller "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/Frontend/LiveExamController.php"
click node_profile_controller "https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/ProfileController.php"
click node_admin_controllers "https://github.com/tauhid219/pwapractice/tree/main/app/Http/Controllers/Admin"
click node_quiz_scoring "https://github.com/tauhid219/pwapractice/blob/main/app/Services/QuizScoringService.php"
click node_live_exam_job "https://github.com/tauhid219/pwapractice/blob/main/app/Jobs/ProcessLiveExamScore.php"
click node_domain_models "https://github.com/tauhid219/pwapractice/tree/main/app/Models"
click node_imports_exports "https://github.com/tauhid219/pwapractice/tree/main/app/Imports"
click node_rbac_config "https://github.com/tauhid219/pwapractice/blob/main/config/permission.php"
click node_locale_files "https://github.com/tauhid219/pwapractice/tree/main/lang"
click node_pwa_assets "https://github.com/tauhid219/pwapractice/blob/main/public/manifest.json"
click node_db_schema "https://github.com/tauhid219/pwapractice/tree/main/database/migrations"

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_public_index,node_web_routes,node_auth_routes toneBlue
class node_app_layouts,node_frontend_views,node_admin_views toneAmber
class node_auth_controllers,node_frontend_controller,node_quiz_controller,node_live_exam_controller,node_profile_controller toneMint
class node_admin_controllers toneRose
class node_quiz_scoring,node_live_exam_job,node_domain_models,node_imports_exports,node_db_schema toneIndigo
class node_set_locale,node_security_headers,node_is_admin,node_check_level_access,node_rbac_config,node_locale_files,node_pwa_assets toneTeal
```

## Components

### Entry & routing

HTTP entry points, route definitions, and request boundary concerns.

- [Front controller](https://github.com/tauhid219/pwapractice/blob/main/public/index.php): HTTP entry · Laravel front controller that boots the application and receives web requests. · `public/index.php`
- [Web routes](https://github.com/tauhid219/pwapractice/blob/main/routes/web.php): route map · Main route definitions for guest, frontend, and admin flows. · `routes/web.php`
- [Auth routes](https://github.com/tauhid219/pwapractice/blob/main/routes/auth.php): route map · Authentication and session-related route definitions. · `routes/auth.php`

### Presentation layer

Blade layouts and UI shells for guest, frontend, and admin surfaces.

- [Layout shells](https://github.com/tauhid219/pwapractice/tree/main/app/View/Components): view components · Shared app, guest, and admin layout components. · `app/View/Components`
- [Student views](https://github.com/tauhid219/pwapractice/tree/main/resources/views/frontend): Blade screens · Learner-facing pages for levels, quizzes, and live exams. · `resources/views/frontend`
- [Admin views](https://github.com/tauhid219/pwapractice/tree/main/resources/views/admin): Blade screens · Management screens for catalog, users, permissions, and live exams. · `resources/views/admin`

### Learner flow

Student-facing quiz and live-exam experience.

- [Auth controllers](https://github.com/tauhid219/pwapractice/tree/main/app/Http/Controllers/Auth): controllers · Login, registration, verification, and password flows. · `app/Http/Controllers/Auth`
- [Frontend shell](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/FrontendController.php): controller · Main frontend page controller for the student experience. · `app/Http/Controllers/FrontendController.php`
- [Quiz flow](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/Frontend/QuizController.php): controller · Handles quiz browsing, taking, and submission. · `app/Http/Controllers/Frontend/QuizController.php`
- [Live exam flow](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/Frontend/LiveExamController.php): controller · Handles live-exam browsing, taking, and result screens. · `app/Http/Controllers/Frontend/LiveExamController.php`
- [Profile](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Controllers/ProfileController.php): controller · Shared account and progress management. · `app/Http/Controllers/ProfileController.php`

### Admin control plane

Content, user, role, and live-exam administration.

- [Admin controllers](https://github.com/tauhid219/pwapractice/tree/main/app/Http/Controllers/Admin): controllers · CRUD and operational controllers for admin-managed content. · `app/Http/Controllers/Admin`

### Domain & persistence

Core models, scoring logic, queue work, and schema-backed state.

- [Scoring service](https://github.com/tauhid219/pwapractice/blob/main/app/Services/QuizScoringService.php): service · Encapsulates quiz grading and scoring rules. · `app/Services/QuizScoringService.php`
- [Score job](https://github.com/tauhid219/pwapractice/blob/main/app/Jobs/ProcessLiveExamScore.php): queue job · Queued post-processing for live-exam scoring. · `app/Jobs/ProcessLiveExamScore.php`
- [Domain models](https://github.com/tauhid219/pwapractice/tree/main/app/Models): Eloquent models · Core content, attempt, progress, and live-exam entities. · `app/Models`
- [Import/export](https://github.com/tauhid219/pwapractice/tree/main/app/Imports): data pipeline · Bulk question and live-exam template import/export boundary. · `app/Imports`
- [Schema & seed](https://github.com/tauhid219/pwapractice/tree/main/database/migrations): migrations and seeders · Tables and baseline data for users, content, attempts, and permissions. · `database/migrations`

### Platform services

Localization, middleware, PWA assets, and RBAC configuration.

- [Locale](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/SetLocale.php): middleware · Sets request locale for bilingual UI and content. · `app/Http/Middleware/SetLocale.php`
- [Security headers](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/SecurityHeaders.php): middleware · Adds response hardening headers. · `app/Http/Middleware/SecurityHeaders.php`
- [Admin gate](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/IsAdmin.php): middleware · Protects admin surfaces with role-based access control. · `app/Http/Middleware/IsAdmin.php`
- [Level gate](https://github.com/tauhid219/pwapractice/blob/main/app/Http/Middleware/CheckLevelAccess.php): middleware · Enforces content-level access boundaries for learners. · `app/Http/Middleware/CheckLevelAccess.php`
- [RBAC config](https://github.com/tauhid219/pwapractice/blob/main/config/permission.php): permission config · Permission table configuration for role and permission management. · `config/permission.php`
- [Translations](https://github.com/tauhid219/pwapractice/tree/main/lang): i18n assets · English and Bengali UI/content strings. · `lang`
- [PWA assets](https://github.com/tauhid219/pwapractice/blob/main/public/manifest.json): offline runtime · Manifest, service worker, timer worker, and client-side exam assets. · `public/manifest.json`

## Connections

- Front controller → Web routes: dispatches to · Front controller hands requests to route definitions.
- Web routes → Auth routes: includes · Web routing composes authentication routes.
- Web routes → Locale: applies · Localized request handling is part of the HTTP pipeline.
- Web routes → Security headers: applies · Response hardening is enforced at the boundary.
- Web routes → Admin gate: guards admin · Admin routes are protected by explicit authorization.
- Web routes → Level gate: guards content · Learner access is filtered by level/content rules.
- Web routes → Auth controllers: routes to · Authentication endpoints connect to auth controllers.
- Web routes → Frontend shell: routes to · Student landing and navigation flow through the frontend shell.
- Web routes → Quiz flow: routes to · Quiz pages and submissions are handled here.
- Web routes → Live exam flow: routes to · Live-exam pages and submissions are handled here.
- Web routes → Profile: routes to · Profile and progress pages are shared concerns.
- Web routes → Admin controllers: routes to · Admin CRUD endpoints map to management controllers.
- Frontend shell → Student views: renders · Student-facing screens are Blade-rendered.
- Quiz flow → Student views: renders · Quiz taking and result pages live in the frontend view family.
- Live exam flow → Student views: renders · Live-exam taking and result pages live in the frontend view family.
- Admin controllers → Admin views: renders · Admin CRUD and reporting screens are Blade-rendered.
- Auth controllers → Layout shells: uses · Guest and app shells are shared across auth flows.
- Frontend shell → Layout shells: uses · Frontend pages use shared layout components.
- Admin controllers → Layout shells: uses · Admin pages use a dedicated layout family.
- Quiz flow → Scoring service: scores with · Quiz evaluation is centralized in a scoring service.
- Live exam flow → Score job: queues · Live-exam submission triggers background scoring.
- Scoring service → Domain models: reads/writes · Scoring depends on quiz attempts, questions, and progress models.
- Score job → Domain models: updates · Queued processing persists live-exam results and analytics.
- Admin controllers → Domain models: manages · Admin CRUD operates on core catalog and exam entities.
- Import/export → Domain models: moves data for · Bulk import/export bridges external files and question models.
- RBAC config → Admin controllers: authorizes · RBAC configuration underpins admin access control.
- Translations → Locale: drives · Locale middleware selects translated strings.
- PWA assets → Student views: supports · Offline runtime and timing assets augment learner screens.
- Schema & seed → Domain models: backing store · Migrations and seeders define the persistence shape for the models.