# keshavraj7/quizai architecture

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

- Interactive diagram: https://gitdiagram.com/keshavraj7/quizai
- Repository: https://github.com/keshavraj7/quizai

## Overview

1. **Overall shape**
   - QuizAI is a two-tier application: a **React/Vite frontend** in `client/` and an **Express/MongoDB backend** in `server/`.
   - The frontend handles all user interaction and routing; the backend exposes REST APIs, persists state in MongoDB, and powers real-time room play with Socket.IO.

2. **Frontend boundary**
   - The client is a single-page app built with **React** and **Vite**.
   - `src/main.jsx` and `App.jsx` are the entry points, while the pages under `src/pages/` represent the main user flows: auth, quiz creation, quiz taking, dashboards, analysis, profile, and live room participation.
   - `ProtectedRoute.jsx` is the key access boundary for authenticated pages.

3. **Client-side feature areas**
   - `CreateTest.jsx` handles AI-driven quiz creation.
   - `QuizPage.jsx`, `Analysis.jsx`, and `Leaderboard.jsx` handle normal quiz taking and review.
   - `Room.jsx`, `RoomQuiz.jsx`, and `RoomLeaderboard.jsx` handle the live multiplayer room flow.
   - `Dashboard.jsx` and `Profile.jsx` expose user history and personal stats.
   - `JoinTest.jsx` appears to be the entry point for joining an existing quiz/room.

4. **Real-time layer**
   - `client/src/socket.js` indicates a dedicated Socket.IO client connection for multiplayer quiz rooms.
   - This real-time channel is separate from normal REST API traffic and is used for room state updates such as joining, waiting-room coordination, quiz start, and leaderboard updates.

5. **Backend API boundary**
   - The backend is organized into **routes → controllers → models/services**.
   - Route files in `server/routes/` split the API by domain: `authRoutes`, `quizRoutes`, and `roomRoutes`.
   - Controllers in `server/controllers/` contain the request handling for authentication, quiz generation/management, and room lifecycle logic.

6. **Data persistence**
   - MongoDB is the main system of record, with models in `server/models/`: `User`, `Quiz`, `Room`, and `Attempt`.
   - `User` stores identity and account data.
   - `Quiz` stores generated quiz content and metadata.
   - `Room` stores live-session state.
   - `Attempt` stores quiz results and supports history, leaderboard, and analysis views.

7. **AI generation path**
   - `server/services/geminiService.js` is the AI integration point and likely the place where quiz generation requests are sent to **Google Gemini**.
   - The quiz creation flow combines user input such as topic, difficulty, question count, and optional instructions with Gemini-generated questions and choices.
   - This service is used by quiz-related backend controllers rather than being called directly from the client.

8. **PDF upload and content extraction**
   - `server/middleware/uploadMiddleware.js` indicates backend handling for file uploads, specifically PDFs mentioned in the README.
   - This creates a second quiz-generation path: user uploads study material, the backend processes the file, extracts content, and then passes that content into the quiz generation flow.

9. **Authentication and access control**
   - `authController.js` and `authRoutes.js` implement account creation and login.
   - `authMiddleware.js` protects private endpoints and likely validates JWTs before allowing access to user-specific quizzes, rooms, or attempt history.
   - This security boundary is mirrored on the frontend with protected routes.

10. **Quiz lifecycle**
   - The normal flow is: user creates or loads a quiz → takes the quiz in the frontend → backend records the attempt → analysis and leaderboard pages read the stored results.
   - The presence of `Attempt` plus `Analysis.jsx` and `Leaderboard.jsx` suggests post-quiz scoring, review of correct/incorrect answers, and ranking based on stored attempt data.

11. **Live room lifecycle**
   - Live rooms are a separate subsystem from standard quizzes.
   - `roomController.js` and `roomRoutes.js` manage room creation, joining, and quiz session state.
   - The frontend room pages likely coordinate a host-controlled start, participant join codes, timer-based submission, and leaderboard updates through Socket.IO plus backend persistence.

12. **Deployment/runtime boundaries**
   - The architecture is split across separate deployments: **frontend on Vercel**, **backend on Render**, and **MongoDB Atlas** for persistence.
   - That separation matters because the UI must communicate with an external API and an external realtime endpoint rather than a local monolith.

13. **Primary data flows to diagram**
   - Browser → React pages/components → Axios/Socket.IO client
   - Axios/Socket.IO → Express routes/controllers
   - Controllers → MongoDB models / Gemini service / upload middleware
   - Backend → MongoDB Atlas and Gemini API
   - Backend Socket.IO → connected clients in live rooms

Main entry points: [`client/src/App.jsx`](https://github.com/keshavraj7/quizai/blob/main/client/src/App.jsx) (App.jsx), [`server/controllers/quizController.js`](https://github.com/keshavraj7/quizai/blob/main/server/controllers/quizController.js) (quizController), [`server/server.js`](https://github.com/keshavraj7/quizai/blob/main/server/server.js) (server.js), [`server/controllers/authController.js`](https://github.com/keshavraj7/quizai/blob/main/server/controllers/authController.js) (authController)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_client_main["main.jsx<br/>react entry<br/>[main.jsx]"]
  node_client_app["App.jsx<br/>router shell<br/>[App.jsx]"]
  node_client_protected["ProtectedRoute<br/>access guard<br/>[ProtectedRoute.jsx]"]
  node_client_socket["socket.js<br/>socket client<br/>[socket.js]"]
  node_client_login["Login<br/>auth page<br/>[Login.jsx]"]
  node_client_signup["Signup<br/>auth page<br/>[Signup.jsx]"]
  node_client_create["CreateTest<br/>quiz builder<br/>[CreateTest.jsx]"]
  node_client_quiz["QuizPage<br/>quiz taking<br/>[QuizPage.jsx]"]
  node_client_analysis["Analysis<br/>results page<br/>[Analysis.jsx]"]
  node_client_leaderboard["Leaderboard<br/>ranking page<br/>[Leaderboard.jsx]"]
  node_client_dashboard["Dashboard<br/>history page<br/>[Dashboard.jsx]"]
  node_client_profile["Profile<br/>[Profile.jsx]"]
  node_client_join["JoinTest<br/>join page<br/>[JoinTest.jsx]"]
  node_client_room["Room<br/>[Room.jsx]"]
  node_client_roomquiz["RoomQuiz<br/>live quiz<br/>[RoomQuiz.jsx]"]
  node_client_roomboard["RoomLeaderboard<br/>live ranking"]
end

subgraph group_server["Backend"]
  node_server_main["server.js<br/>api bootstrap<br/>[server.js]"]
  node_server_auth_routes["authRoutes<br/>route layer<br/>[authRoutes.js]"]
  node_server_quiz_routes["quizRoutes<br/>route layer<br/>[quizRoutes.js]"]
  node_server_room_routes["roomRoutes<br/>route layer<br/>[roomRoutes.js]"]
  node_server_auth_ctrl["authController<br/>auth controller<br/>[authController.js]"]
  node_server_quiz_ctrl["quizController<br/>quiz controller<br/>[quizController.js]"]
  node_server_room_ctrl["roomController<br/>room controller<br/>[roomController.js]"]
  node_server_auth_mw["authMiddleware<br/>security middleware<br/>[authMiddleware.js]"]
  node_server_upload_mw["uploadMiddleware<br/>file middleware"]
  node_server_gemini["geminiService<br/>ai service<br/>[geminiService.js]"]
  node_server_db["db.js<br/>database config<br/>[db.js]"]
  node_model_user[("User<br/>Mongo model<br/>[User.js]")]
  node_model_quiz[("Quiz<br/>Mongo model<br/>[Quiz.js]")]
  node_model_room[("Room<br/>Mongo model<br/>[Room.js]")]
  node_model_attempt[("Attempt<br/>Mongo model<br/>[Attempt.js]")]
end

subgraph group_external["External systems"]
  node_external_mongo[("MongoDB Atlas<br/>managed database")]
  node_external_gemini{{"Gemini API<br/>ai backend"}}
end

node_client_main -->|"mounts"| node_client_app
node_client_app -->|"guards"| node_client_protected
node_client_app -->|"routes to"| node_client_login
node_client_app -->|"routes to"| node_client_signup
node_client_app -->|"routes to"| node_client_create
node_client_app -->|"routes to"| node_client_quiz
node_client_app -->|"routes to"| node_client_analysis
node_client_app -->|"routes to"| node_client_leaderboard
node_client_app -->|"routes to"| node_client_dashboard
node_client_app -->|"routes to"| node_client_profile
node_client_app -->|"routes to"| node_client_join
node_client_app -->|"routes to"| node_client_room
node_client_app -->|"routes to"| node_client_roomquiz
node_client_app -->|"routes to"| node_client_roomboard
node_client_room -->|"uses"| node_client_socket
node_client_roomquiz -->|"uses"| node_client_socket
node_client_roomboard -->|"uses"| node_client_socket
node_server_main -->|"connects"| node_server_db
node_server_main -->|"mounts"| node_server_auth_routes
node_server_main -->|"mounts"| node_server_quiz_routes
node_server_main -->|"mounts"| node_server_room_routes
node_server_auth_routes -->|"delegates to"| node_server_auth_ctrl
node_server_quiz_routes -->|"delegates to"| node_server_quiz_ctrl
node_server_room_routes -->|"delegates to"| node_server_room_ctrl
node_server_auth_ctrl -->|"checks"| node_server_auth_mw
node_server_quiz_ctrl -->|"checks"| node_server_auth_mw
node_server_quiz_ctrl -->|"accepts"| node_server_upload_mw
node_server_quiz_ctrl -->|"generates with"| node_server_gemini
node_server_room_ctrl -->|"checks"| node_server_auth_mw
node_server_auth_ctrl -->|"reads/writes"| node_model_user
node_server_quiz_ctrl -->|"reads/writes"| node_model_quiz
node_server_quiz_ctrl -->|"reads/writes"| node_model_attempt
node_server_room_ctrl -->|"reads/writes"| node_model_room
node_model_user -->|"stored in"| node_external_mongo
node_model_quiz -->|"stored in"| node_external_mongo
node_model_room -->|"stored in"| node_external_mongo
node_model_attempt -->|"stored in"| node_external_mongo
node_server_gemini -->|"calls"| node_external_gemini

click node_client_main "https://github.com/keshavraj7/quizai/blob/main/client/src/main.jsx"
click node_client_app "https://github.com/keshavraj7/quizai/blob/main/client/src/App.jsx"
click node_client_protected "https://github.com/keshavraj7/quizai/blob/main/client/src/components/ProtectedRoute.jsx"
click node_client_socket "https://github.com/keshavraj7/quizai/blob/main/client/src/socket.js"
click node_client_login "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Login.jsx"
click node_client_signup "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Signup.jsx"
click node_client_create "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/CreateTest.jsx"
click node_client_quiz "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/QuizPage.jsx"
click node_client_analysis "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Analysis.jsx"
click node_client_leaderboard "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Leaderboard.jsx"
click node_client_dashboard "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Dashboard.jsx"
click node_client_profile "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Profile.jsx"
click node_client_join "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/JoinTest.jsx"
click node_client_room "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Room.jsx"
click node_client_roomquiz "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/RoomQuiz.jsx"
click node_client_roomboard "https://github.com/keshavraj7/quizai/blob/main/client/src/pages/RoomLeaderboard.jsx"
click node_server_main "https://github.com/keshavraj7/quizai/blob/main/server/server.js"
click node_server_auth_routes "https://github.com/keshavraj7/quizai/blob/main/server/routes/authRoutes.js"
click node_server_quiz_routes "https://github.com/keshavraj7/quizai/blob/main/server/routes/quizRoutes.js"
click node_server_room_routes "https://github.com/keshavraj7/quizai/blob/main/server/routes/roomRoutes.js"
click node_server_auth_ctrl "https://github.com/keshavraj7/quizai/blob/main/server/controllers/authController.js"
click node_server_quiz_ctrl "https://github.com/keshavraj7/quizai/blob/main/server/controllers/quizController.js"
click node_server_room_ctrl "https://github.com/keshavraj7/quizai/blob/main/server/controllers/roomController.js"
click node_server_auth_mw "https://github.com/keshavraj7/quizai/blob/main/server/middleware/authMiddleware.js"
click node_server_upload_mw "https://github.com/keshavraj7/quizai/blob/main/server/middleware/uploadMiddleware.js"
click node_server_gemini "https://github.com/keshavraj7/quizai/blob/main/server/services/geminiService.js"
click node_server_db "https://github.com/keshavraj7/quizai/blob/main/server/config/db.js"
click node_model_user "https://github.com/keshavraj7/quizai/blob/main/server/models/User.js"
click node_model_quiz "https://github.com/keshavraj7/quizai/blob/main/server/models/Quiz.js"
click node_model_room "https://github.com/keshavraj7/quizai/blob/main/server/models/Room.js"
click node_model_attempt "https://github.com/keshavraj7/quizai/blob/main/server/models/Attempt.js"

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_client_main,node_client_app,node_client_protected,node_client_socket,node_client_login,node_client_signup,node_client_create,node_client_quiz,node_client_analysis,node_client_leaderboard,node_client_dashboard,node_client_profile,node_client_join,node_client_room,node_client_roomquiz,node_client_roomboard toneBlue
class node_server_main,node_server_auth_routes,node_server_quiz_routes,node_server_room_routes,node_server_auth_ctrl,node_server_quiz_ctrl,node_server_room_ctrl,node_server_auth_mw,node_server_upload_mw,node_server_gemini,node_server_db,node_model_user,node_model_quiz,node_model_room,node_model_attempt toneAmber
class node_external_mongo,node_external_gemini toneMint
```

## Components

### Frontend

React/Vite single-page app and user-facing flows

- [main.jsx](https://github.com/keshavraj7/quizai/blob/main/client/src/main.jsx): react entry · Bootstraps the SPA · `client/src/main.jsx`
- [App.jsx](https://github.com/keshavraj7/quizai/blob/main/client/src/App.jsx): router shell · Defines app-level routing and layout · `client/src/App.jsx`
- [ProtectedRoute](https://github.com/keshavraj7/quizai/blob/main/client/src/components/ProtectedRoute.jsx): access guard · Gate for authenticated pages · `client/src/components/ProtectedRoute.jsx`
- [socket.js](https://github.com/keshavraj7/quizai/blob/main/client/src/socket.js): socket client · Dedicated Socket.IO connection for live rooms · `client/src/socket.js`
- [Login](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Login.jsx): auth page · Sign-in flow · `client/src/pages/Login.jsx`
- [Signup](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Signup.jsx): auth page · Account creation flow · `client/src/pages/Signup.jsx`
- [CreateTest](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/CreateTest.jsx): quiz builder · AI-assisted quiz creation · `client/src/pages/CreateTest.jsx`
- [QuizPage](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/QuizPage.jsx): quiz taking · Standard quiz play flow · `client/src/pages/QuizPage.jsx`
- [Analysis](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Analysis.jsx): results page · Answer review and scoring · `client/src/pages/Analysis.jsx`
- [Leaderboard](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Leaderboard.jsx): ranking page · Quiz ranking and comparison · `client/src/pages/Leaderboard.jsx`
- [Dashboard](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Dashboard.jsx): history page · User quiz history and overview · `client/src/pages/Dashboard.jsx`
- [Profile](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Profile.jsx): profile page · Personal stats and account view · `client/src/pages/Profile.jsx`
- [JoinTest](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/JoinTest.jsx): join page · Entry point for existing quizzes or rooms · `client/src/pages/JoinTest.jsx`
- [Room](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/Room.jsx): live room · Multiplayer room entry and coordination · `client/src/pages/Room.jsx`
- [RoomQuiz](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/RoomQuiz.jsx): live quiz · Participant quiz view in a room · `client/src/pages/RoomQuiz.jsx`
- [RoomLeaderboard](https://github.com/keshavraj7/quizai/blob/main/client/src/pages/RoomLeaderboard.jsx): live ranking · Realtime room leaderboard view · `client/src/pages/RoomLeaderboard.jsx`

### Backend

Express API, realtime room logic, and data access

- [server.js](https://github.com/keshavraj7/quizai/blob/main/server/server.js): api bootstrap · Starts Express and realtime backend · `server/server.js`
- [authRoutes](https://github.com/keshavraj7/quizai/blob/main/server/routes/authRoutes.js): route layer · Authentication API endpoints · `server/routes/authRoutes.js`
- [quizRoutes](https://github.com/keshavraj7/quizai/blob/main/server/routes/quizRoutes.js): route layer · Quiz creation and attempt APIs · `server/routes/quizRoutes.js`
- [roomRoutes](https://github.com/keshavraj7/quizai/blob/main/server/routes/roomRoutes.js): route layer · Live room APIs · `server/routes/roomRoutes.js`
- [authController](https://github.com/keshavraj7/quizai/blob/main/server/controllers/authController.js): auth controller · Login and signup handling · `server/controllers/authController.js`
- [quizController](https://github.com/keshavraj7/quizai/blob/main/server/controllers/quizController.js): quiz controller · Quiz generation, storage, and results · `server/controllers/quizController.js`
- [roomController](https://github.com/keshavraj7/quizai/blob/main/server/controllers/roomController.js): room controller · Room lifecycle and session state · `server/controllers/roomController.js`
- [authMiddleware](https://github.com/keshavraj7/quizai/blob/main/server/middleware/authMiddleware.js): security middleware · Protects private endpoints · `server/middleware/authMiddleware.js`
- [uploadMiddleware](https://github.com/keshavraj7/quizai/blob/main/server/middleware/uploadMiddleware.js): file middleware · Handles PDF uploads for quiz inputs · `server/middleware/uploadMiddleware.js`
- [geminiService](https://github.com/keshavraj7/quizai/blob/main/server/services/geminiService.js): ai service · Generates quiz content via Gemini · `server/services/geminiService.js`
- [db.js](https://github.com/keshavraj7/quizai/blob/main/server/config/db.js): database config · Connects Express to MongoDB · `server/config/db.js`
- [User](https://github.com/keshavraj7/quizai/blob/main/server/models/User.js): Mongo model · Accounts and identity · `server/models/User.js`
- [Quiz](https://github.com/keshavraj7/quizai/blob/main/server/models/Quiz.js): Mongo model · Generated quiz content and metadata · `server/models/Quiz.js`
- [Room](https://github.com/keshavraj7/quizai/blob/main/server/models/Room.js): Mongo model · Live room state · `server/models/Room.js`
- [Attempt](https://github.com/keshavraj7/quizai/blob/main/server/models/Attempt.js): Mongo model · Quiz results and history · `server/models/Attempt.js`

### External systems

Managed services used by the app

- **MongoDB Atlas**: managed database · System of record for users, quizzes, rooms, and attempts
- **Gemini API**: ai backend · Generates quiz questions and choices

## Connections

- main.jsx → App.jsx: mounts · Bootstraps the application shell
- App.jsx → ProtectedRoute: guards · Wraps private routes with auth checks
- App.jsx → Login: routes to · Public auth entry
- App.jsx → Signup: routes to · Public auth entry
- App.jsx → CreateTest: routes to · Quiz creation flow
- App.jsx → QuizPage: routes to · Standard quiz flow
- App.jsx → Analysis: routes to · Results review flow
- App.jsx → Leaderboard: routes to · Ranking view
- App.jsx → Dashboard: routes to · User overview
- App.jsx → Profile: routes to · User profile
- App.jsx → JoinTest: routes to · Join existing session
- App.jsx → Room: routes to · Live room entry
- App.jsx → RoomQuiz: routes to · Room quiz play view
- App.jsx → RoomLeaderboard: routes to · Room leaderboard view
- Room → socket.js: uses · Realtime room coordination
- RoomQuiz → socket.js: uses · Realtime answer and timer updates
- RoomLeaderboard → socket.js: uses · Realtime leaderboard updates
- server.js → db.js: connects · Initializes MongoDB connection
- server.js → authRoutes: mounts · Registers auth endpoints
- server.js → quizRoutes: mounts · Registers quiz endpoints
- server.js → roomRoutes: mounts · Registers room endpoints
- authRoutes → authController: delegates to · Request handling for auth
- quizRoutes → quizController: delegates to · Request handling for quiz lifecycle
- roomRoutes → roomController: delegates to · Request handling for rooms
- authController → authMiddleware: checks · Protects authenticated account operations
- quizController → authMiddleware: checks · Protects user-specific quiz operations
- quizController → uploadMiddleware: accepts · Handles uploaded study PDFs
- quizController → geminiService: generates with · Builds quizzes from prompts and content
- roomController → authMiddleware: checks · Protects room operations
- authController → User: reads/writes · Creates and validates accounts
- quizController → Quiz: reads/writes · Stores quiz definitions
- quizController → Attempt: reads/writes · Persists submissions and results
- roomController → Room: reads/writes · Persists live room state
- User → MongoDB Atlas: stored in · MongoDB persistence
- Quiz → MongoDB Atlas: stored in · MongoDB persistence
- Room → MongoDB Atlas: stored in · MongoDB persistence
- Attempt → MongoDB Atlas: stored in · MongoDB persistence
- geminiService → Gemini API: calls · AI quiz generation requests