# githubtron/quizmaster architecture

> Architecture diagram of the GitHub repository githubtron/quizmaster, 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/githubtron/quizmaster
- Repository: https://github.com/githubtron/quizmaster

## Overview

1. **System shape**
   - QuizMaster is a two-tier application: a **React SPA frontend** and a **FastAPI backend** backed by **PostgreSQL**.
   - The backend is not monolithic in practice; it is split into routers, domain models, schemas, and services, which makes the API layer and business logic clearly separable.

2. **Frontend boundary**
   - The frontend lives under `frontend/src` and is organized by **pages**, **reusable UI components**, **feature components** for quizzes, and **custom hooks**.
   - `src/services/api.js` is the main browser-to-backend boundary, while hooks like `useAuth`, `useQuiz`, `useTimer`, and `useNotifications` centralize stateful client behavior.
   - `Navbar`, `NotificationBell`, `QuestionCard`, `QuizTimer`, and `ResultCard` indicate a role-driven UX with quiz execution, timing, and post-exam feedback as core flows.

3. **Frontend user journeys**
   - The page structure maps directly to product roles: `AdminDashboard`, `ProfessorDashboard`, `StudentDashboard`, `TakeQuiz`, `Results`, `Profile`, `Login`, `Register`, and `AIGenerator`.
   - This suggests the SPA is the presentation layer for all major workflows: authentication, exam taking, exam creation, analytics, and report viewing.

4. **Backend entry point and core infrastructure**
   - `backend/main.py` is the FastAPI composition root that likely mounts all routers and initializes middleware.
   - `backend/core/` holds cross-cutting infrastructure: `config.py` for environment/config loading, `database.py` for DB session setup, `dependencies.py` for FastAPI dependency injection, and `security.py` for JWT/auth utilities.

5. **Domain model and persistence**
   - The ORM layer in `backend/models/` captures the core entities: `User`, `Exam`, `Question`, `Category`, `ExamSet`, and `Attempt`.
   - This indicates the main persistence boundary is centered on exam authoring, question bank management, paper-set generation, and student submissions.
   - Alembic migrations in `backend/alembic/versions/` show the schema is managed over time, including additions like **professor role** and **exam scheduling**.

6. **API surface**
   - Routers in `backend/routers/` are segmented by business capability: `auth`, `users`, `admin`, `categories`, `questions`, `exams`, `exam_sets`, `attempts`, `reports`, `analytics`, `ai_generator`, and `ws`.
   - This is a strong signal that the backend exposes a role-aware REST API plus a WebSocket channel for real-time updates or notifications.

7. **Business logic services**
   - `backend/services/` contains the non-trivial workflows:
     - `ai_question_service.py` for AI-assisted question generation from uploaded content
     - `exam_set_service.py` for generating distinct paper sets
     - `grading_service.py` for automatic scoring of submissions
     - `pdf_service.py` and `pdf_report_service.py` for report generation
     - `email_service.py` for outbound notifications
   - These services sit between routers and models, so the routers appear thin and the complex rules are centralized.

8. **AI and content generation flow**
   - The README and service layout show an AI pipeline where a PDF is uploaded, questions are extracted/generated, validated, and then stored as part of the question bank or an exam.
   - The project uses **Google Gemini** as the primary model and **Groq** as fallback, so AI generation is an external integration rather than a local model.

9. **Exam delivery flow**
   - The core runtime flow is: professor creates an exam/question pool → the system generates exam sets → each student receives a unique set → the frontend timer counts down → submission is auto-graded → attempt/result data is persisted.
   - `attempts`, `exam_sets`, and `grading_service` are the key backend points in this path.

10. **Reporting and analytics**
   - Reporting is a first-class subsystem, not a postscript: students get result PDFs, professors get per-exam and overall analytics, and admins get platform-wide reports.
   - The presence of both `reports` and `analytics` routers, plus PDF-focused services and example PDFs in the repo, suggests report generation is produced server-side and then downloaded or viewed by the client.

11. **Authentication and authorization**
   - JWT-based auth is central, with role separation across **Admin**, **Professor**, and **Student**.
   - `core/security.py`, `routers/auth.py`, and role-specific dashboards imply authorization is enforced at the API layer, not just in the UI.

12. **Deployment and operational boundaries**
   - The repo is containerized with Docker on both frontend and backend, and `render.yaml` suggests deployment on **Render**.
   - The frontend uses `nginx.conf` for production serving, while the backend likely runs via Uvicorn/Gunicorn-style ASGI hosting.
   - Alembic migrations and `seed_demo_users.py` indicate the project has explicit setup/bootstrap operations for schema and sample identities.

13. **How to draw the architecture**
   - Draw four main boxes: **React client**, **FastAPI API**, **service layer**, and **PostgreSQL**.
   - Add external boxes for **Gemini/Groq**, **PDF generation**, and **email**.
   - Show the main data flow as client requests → routers → services → models/database, with reports and AI generation branching out through the specialized service layer.

Main entry points: [`backend/routers`](https://github.com/githubtron/quizmaster/tree/main/backend/routers) (Routers), [`frontend/src/App.jsx`](https://github.com/githubtron/quizmaster/blob/main/frontend/src/App.jsx) (React SPA), [`backend/models`](https://github.com/githubtron/quizmaster/tree/main/backend/models) (ORM models), [`backend/services/ai_question_service.py`](https://github.com/githubtron/quizmaster/blob/main/backend/services/ai_question_service.py) (AI generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_frontend_app["React SPA<br/>frontend app<br/>[App.jsx]"]
  node_frontend_api["API client<br/>browser client<br/>[api.js]"]
  node_frontend_auth["Auth hook<br/>state hook<br/>[useAuth.jsx]"]
  node_frontend_quiz_state["Quiz state<br/>state hook<br/>[useQuiz.js]"]
  node_frontend_timer["Timer hook<br/>state hook<br/>[useTimer.js]"]
  node_frontend_notifications["Notify hook<br/>state hook"]
  node_frontend_pages["Role pages"]
  node_frontend_layout["Shell UI<br/>components"]
  node_frontend_quiz_ui["Quiz UI<br/>components"]
  node_frontend_ui["UI kit<br/>components"]
end

subgraph group_backend_api["FastAPI API"]
  node_backend_main["API root<br/>fastapi app<br/>[main.py]"]
  node_backend_routers["Routers<br/>api routes"]
  node_backend_auth["Auth router<br/>[auth.py]"]
  node_backend_exams["Exam router<br/>[exams.py]"]
  node_backend_attempts["Attempt router<br/>[attempts.py]"]
  node_backend_reports["Reports API<br/>router<br/>[reports.py]"]
  node_backend_ai_router["AI router<br/>[ai_generator.py]"]
end

subgraph group_backend_domain["Domain model"]
  node_backend_models[("ORM models<br/>persistence models")]
  node_backend_schemas["Schemas"]
end

subgraph group_backend_service["Service layer"]
  node_backend_grading["Grading service<br/>[grading_service.py]"]
  node_backend_examsets["Set generator"]
  node_backend_ai_service["AI generator"]
  node_backend_pdf["PDF service<br/>[pdf_service.py]"]
  node_backend_pdf_report["PDF reports"]
  node_backend_email["Email service<br/>[email_service.py]"]
end

subgraph group_backend_core["Core infra"]
  node_backend_core["Core infra<br/>infrastructure"]
end

subgraph group_external["External systems"]
  node_postgres[("PostgreSQL<br/>database")]
  node_gemini_groq{{"Gemini/Groq<br/>ai providers"}}
  node_pdf_output["PDF output<br/>generated docs"]
end

node_frontend_app -->|"renders"| node_frontend_layout
node_frontend_app -->|"navigates"| node_frontend_pages
node_frontend_app -->|"uses"| node_frontend_quiz_ui
node_frontend_app -->|"uses"| node_frontend_ui
node_frontend_auth -->|"calls"| node_frontend_api
node_frontend_quiz_state -->|"calls"| node_frontend_api
node_frontend_timer -->|"supports"| node_frontend_quiz_ui
node_frontend_notifications -->|"feeds"| node_frontend_layout
node_frontend_pages -->|"calls"| node_frontend_api
node_backend_main -->|"mounts"| node_backend_routers
node_backend_routers -->|"includes"| node_backend_auth
node_backend_routers -->|"includes"| node_backend_exams
node_backend_routers -->|"includes"| node_backend_attempts
node_backend_routers -->|"includes"| node_backend_reports
node_backend_routers -->|"includes"| node_backend_ai_router
node_backend_auth -->|"depends on"| node_backend_core
node_backend_exams -->|"delegates to"| node_backend_examsets
node_backend_attempts -->|"delegates to"| node_backend_grading
node_backend_ai_router -->|"delegates to"| node_backend_ai_service
node_backend_ai_service -->|"integrates"| node_gemini_groq
node_backend_reports -->|"delegates to"| node_backend_pdf_report
node_backend_pdf_report -->|"uses"| node_backend_pdf
node_backend_grading -->|"reads/writes"| node_backend_models
node_backend_examsets -->|"reads/writes"| node_backend_models
node_backend_ai_service -->|"writes"| node_backend_models
node_backend_pdf_report -->|"writes"| node_pdf_output
node_backend_pdf -->|"writes"| node_pdf_output
node_backend_models -->|"persists to"| node_postgres
node_backend_schemas -.->|"shapes"| node_backend_routers
node_backend_core -->|"connects to"| node_postgres
node_backend_email -->|"uses"| node_backend_core
node_backend_email -.->|"notifies"| node_backend_reports

click node_frontend_app "https://github.com/githubtron/quizmaster/blob/main/frontend/src/App.jsx"
click node_frontend_api "https://github.com/githubtron/quizmaster/blob/main/frontend/src/services/api.js"
click node_frontend_auth "https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useAuth.jsx"
click node_frontend_quiz_state "https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useQuiz.js"
click node_frontend_timer "https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useTimer.js"
click node_frontend_notifications "https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useNotifications.js"
click node_frontend_pages "https://github.com/githubtron/quizmaster/tree/main/frontend/src/pages"
click node_frontend_layout "https://github.com/githubtron/quizmaster/tree/main/frontend/src/components/layout"
click node_frontend_quiz_ui "https://github.com/githubtron/quizmaster/tree/main/frontend/src/components/quiz"
click node_frontend_ui "https://github.com/githubtron/quizmaster/tree/main/frontend/src/components/ui"
click node_backend_main "https://github.com/githubtron/quizmaster/blob/main/backend/main.py"
click node_backend_routers "https://github.com/githubtron/quizmaster/tree/main/backend/routers"
click node_backend_auth "https://github.com/githubtron/quizmaster/blob/main/backend/routers/auth.py"
click node_backend_exams "https://github.com/githubtron/quizmaster/blob/main/backend/routers/exams.py"
click node_backend_attempts "https://github.com/githubtron/quizmaster/blob/main/backend/routers/attempts.py"
click node_backend_reports "https://github.com/githubtron/quizmaster/blob/main/backend/routers/reports.py"
click node_backend_ai_router "https://github.com/githubtron/quizmaster/blob/main/backend/routers/ai_generator.py"
click node_backend_core "https://github.com/githubtron/quizmaster/tree/main/backend/core"
click node_backend_models "https://github.com/githubtron/quizmaster/tree/main/backend/models"
click node_backend_schemas "https://github.com/githubtron/quizmaster/tree/main/backend/schemas"
click node_backend_grading "https://github.com/githubtron/quizmaster/blob/main/backend/services/grading_service.py"
click node_backend_examsets "https://github.com/githubtron/quizmaster/blob/main/backend/services/exam_set_service.py"
click node_backend_ai_service "https://github.com/githubtron/quizmaster/blob/main/backend/services/ai_question_service.py"
click node_backend_pdf "https://github.com/githubtron/quizmaster/blob/main/backend/services/pdf_service.py"
click node_backend_pdf_report "https://github.com/githubtron/quizmaster/blob/main/backend/services/pdf_report_service.py"
click node_backend_email "https://github.com/githubtron/quizmaster/blob/main/backend/services/email_service.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_frontend_app,node_frontend_api,node_frontend_auth,node_frontend_quiz_state,node_frontend_timer,node_frontend_notifications,node_frontend_pages,node_frontend_layout,node_frontend_quiz_ui,node_frontend_ui toneBlue
class node_backend_main,node_backend_routers,node_backend_auth,node_backend_exams,node_backend_attempts,node_backend_reports,node_backend_ai_router toneAmber
class node_backend_models,node_backend_schemas toneMint
class node_backend_grading,node_backend_examsets,node_backend_ai_service,node_backend_pdf,node_backend_pdf_report,node_backend_email toneRose
class node_backend_core toneIndigo
class node_postgres,node_gemini_groq,node_pdf_output toneTeal
```

## Components

### React client

SPA UI, state, and browser-to-API boundary

- [React SPA](https://github.com/githubtron/quizmaster/blob/main/frontend/src/App.jsx): frontend app · Browser application entry and route composition · `frontend/src/App.jsx`
- [API client](https://github.com/githubtron/quizmaster/blob/main/frontend/src/services/api.js): browser client · Main HTTP boundary to backend · `frontend/src/services/api.js`
- [Auth hook](https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useAuth.jsx): state hook · Client authentication state and session handling · `frontend/src/hooks/useAuth.jsx`
- [Quiz state](https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useQuiz.js): state hook · Quiz progress and answer workflow · `frontend/src/hooks/useQuiz.js`
- [Timer hook](https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useTimer.js): state hook · Countdown and time control for quiz taking · `frontend/src/hooks/useTimer.js`
- [Notify hook](https://github.com/githubtron/quizmaster/blob/main/frontend/src/hooks/useNotifications.js): state hook · Client notifications and alerts · `frontend/src/hooks/useNotifications.js`
- [Role pages](https://github.com/githubtron/quizmaster/tree/main/frontend/src/pages): pages · Admin, professor, student, profile, login, register, results, quiz, and AI generator screens · `frontend/src/pages`
- [Shell UI](https://github.com/githubtron/quizmaster/tree/main/frontend/src/components/layout): components · Navigation and notification chrome · `frontend/src/components/layout`
- [Quiz UI](https://github.com/githubtron/quizmaster/tree/main/frontend/src/components/quiz): components · Question, timer, and result presentation · `frontend/src/components/quiz`
- [UI kit](https://github.com/githubtron/quizmaster/tree/main/frontend/src/components/ui): components · Reusable visual primitives · `frontend/src/components/ui`

### FastAPI API

Request routing and role-aware endpoints

- [API root](https://github.com/githubtron/quizmaster/blob/main/backend/main.py): fastapi app · Composition root that mounts routers and middleware · `backend/main.py`
- [Routers](https://github.com/githubtron/quizmaster/tree/main/backend/routers): api routes · Auth, users, admin, categories, questions, exams, exam sets, attempts, reports, analytics, AI, and WebSocket endpoints · `backend/routers`
- [Auth router](https://github.com/githubtron/quizmaster/blob/main/backend/routers/auth.py): router · Login, registration, and identity flows · `backend/routers/auth.py`
- [Exam router](https://github.com/githubtron/quizmaster/blob/main/backend/routers/exams.py): router · Exam authoring and exam access endpoints · `backend/routers/exams.py`
- [Attempt router](https://github.com/githubtron/quizmaster/blob/main/backend/routers/attempts.py): router · Submission and attempt lifecycle endpoints · `backend/routers/attempts.py`
- [Reports API](https://github.com/githubtron/quizmaster/blob/main/backend/routers/reports.py): router · Result and report delivery endpoints · `backend/routers/reports.py`
- [AI router](https://github.com/githubtron/quizmaster/blob/main/backend/routers/ai_generator.py): router · AI-assisted question generation endpoints · `backend/routers/ai_generator.py`

### Domain model

Persistent quiz, user, and attempt entities

- [ORM models](https://github.com/githubtron/quizmaster/tree/main/backend/models): persistence models · User, exam, question, category, exam set, and attempt entities · `backend/models`
- [Schemas](https://github.com/githubtron/quizmaster/tree/main/backend/schemas): pydantic schemas · Request and response shapes for API payloads · `backend/schemas`

### Service layer

Business workflows and document generation

- [Grading service](https://github.com/githubtron/quizmaster/blob/main/backend/services/grading_service.py): service · Automatic scoring and result computation · `backend/services/grading_service.py`
- [Set generator](https://github.com/githubtron/quizmaster/blob/main/backend/services/exam_set_service.py): service · Distinct exam set generation workflow · `backend/services/exam_set_service.py`
- [AI generator](https://github.com/githubtron/quizmaster/blob/main/backend/services/ai_question_service.py): service · Question extraction and generation from content · `backend/services/ai_question_service.py`
- [PDF service](https://github.com/githubtron/quizmaster/blob/main/backend/services/pdf_service.py): service · Report and document rendering · `backend/services/pdf_service.py`
- [PDF reports](https://github.com/githubtron/quizmaster/blob/main/backend/services/pdf_report_service.py): service · Exam and result report generation · `backend/services/pdf_report_service.py`
- [Email service](https://github.com/githubtron/quizmaster/blob/main/backend/services/email_service.py): service · Outbound notification delivery · `backend/services/email_service.py`

### Core infra

Config, DB, dependencies, and security

- [Core infra](https://github.com/githubtron/quizmaster/tree/main/backend/core): infrastructure · Shared config, database, dependency, and security foundations · `backend/core`

### External systems

Datastore and third-party integrations

- **PostgreSQL**: database · Primary persistent store
- **Gemini/Groq**: ai providers · External model providers for AI question generation
- **PDF output**: generated docs · Server-generated result and report files

## Connections

- React SPA → Shell UI: renders · App composes shared shell UI
- React SPA → Role pages: navigates · Routes major role-based pages
- React SPA → Quiz UI: uses · Quiz screens reuse execution components
- React SPA → UI kit: uses · Common visual primitives across screens
- Auth hook → API client: calls · Client auth flows hit backend endpoints
- Quiz state → API client: calls · Quiz loading and submission use API client
- Timer hook → Quiz UI: supports · Countdown drives quiz execution UI
- Notify hook → Shell UI: feeds · Notification state surfaces in shell chrome
- Role pages → API client: calls · Pages fetch data and trigger actions through API client
- API root → Routers: mounts · Main app aggregates route modules
- Routers → Auth router: includes · Auth is one of the main route groups
- Routers → Exam router: includes · Exam management routes are exposed
- Routers → Attempt router: includes · Submission and attempt routes are exposed
- Routers → Reports API: includes · Reporting routes are exposed
- Routers → AI router: includes · AI generation routes are exposed
- Auth router → Core infra: depends on · Authentication uses shared security and dependencies
- Exam router → Set generator: delegates to · Exam routes rely on set generation service
- Attempt router → Grading service: delegates to · Submissions are auto-graded by service layer
- AI router → AI generator: delegates to · Router hands generation work to service layer
- AI generator → Gemini/Groq: integrates · Generation uses external AI providers
- Reports API → PDF reports: delegates to · Report routes produce PDF-backed outputs
- PDF reports → PDF service: uses · Report generation builds on PDF rendering utilities
- Grading service → ORM models: reads/writes · Grading works over attempts, exams, and questions
- Set generator → ORM models: reads/writes · Set generation persists exam set records
- AI generator → ORM models: writes · Generated questions become stored domain objects
- PDF reports → PDF output: writes · Server emits downloadable reports
- PDF service → PDF output: writes · PDF rendering produces files and streams
- ORM models → PostgreSQL: persists to · ORM layer maps domain data to PostgreSQL
- Schemas → Routers: shapes · API payload contracts define router inputs and outputs
- Core infra → PostgreSQL: connects to · Database session management targets PostgreSQL
- Email service → Core infra: uses · Email delivery uses shared configuration
- Email service → Reports API: notifies · Report workflows can trigger outbound email