How keshavraj7/quizai works
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: App.jsx App.jsx · quizController.js quizController · server.js server.js · authController.js authController
Components 33
Frontend
React/Vite single-page app and user-facing flows
- main.jsx · Bootstraps the SPA
client/src/main.jsx - App.jsx · Defines app-level routing and layout
client/src/App.jsx - ProtectedRoute · Gate for authenticated pages
client/src/components/ProtectedRoute.jsx - socket.js · Dedicated Socket.IO connection for live rooms
client/src/socket.js - Login · Sign-in flow
client/src/pages/Login.jsx - Signup · Account creation flow
client/src/pages/Signup.jsx - CreateTest · AI-assisted quiz creation
client/src/pages/CreateTest.jsx - QuizPage · Standard quiz play flow
client/src/pages/QuizPage.jsx - Analysis · Answer review and scoring
client/src/pages/Analysis.jsx - Leaderboard · Quiz ranking and comparison
client/src/pages/Leaderboard.jsx - Dashboard · User quiz history and overview
client/src/pages/Dashboard.jsx - Profile · Personal stats and account view
client/src/pages/Profile.jsx - JoinTest · Entry point for existing quizzes or rooms
client/src/pages/JoinTest.jsx - Room · Multiplayer room entry and coordination
client/src/pages/Room.jsx - RoomQuiz · Participant quiz view in a room
client/src/pages/RoomQuiz.jsx - RoomLeaderboard · Realtime room leaderboard view
client/src/pages/RoomLeaderboard.jsx
Backend
Express API, realtime room logic, and data access
- server.js · Starts Express and realtime backend
server/server.js - authRoutes · Authentication API endpoints
server/routes/authRoutes.js - quizRoutes · Quiz creation and attempt APIs
server/routes/quizRoutes.js - roomRoutes · Live room APIs
server/routes/roomRoutes.js - authController · Login and signup handling
server/controllers/authController.js - quizController · Quiz generation, storage, and results
server/controllers/quizController.js - roomController · Room lifecycle and session state
server/controllers/roomController.js - authMiddleware · Protects private endpoints
server/middleware/authMiddleware.js - uploadMiddleware · Handles PDF uploads for quiz inputs
server/middleware/uploadMiddleware.js - geminiService · Generates quiz content via Gemini
server/services/geminiService.js - db.js · Connects Express to MongoDB
server/config/db.js - User · Accounts and identity
server/models/User.js - Quiz · Generated quiz content and metadata
server/models/Quiz.js - Room · Live room state
server/models/Room.js - Attempt · Quiz results and history
server/models/Attempt.js
External systems
Managed services used by the app
- MongoDB Atlas · System of record for users, quizzes, rooms, and attempts
- Gemini API · Generates quiz questions and choices
Connections 38
- 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