githubtron/quizmaster

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.