How vanshj2006/quizcraft works
1. Repository shape
- This is a two-tier monorepo: backend/ is an Express + MongoDB API, and frontend/ is a React SPA built with Vite.
- The main architectural boundary is browser UI → HTTP API / Socket.IO backend → MongoDB and external services.
2. Backend layering
- The backend follows a clean MVC-style split:
- routes/ define API endpoints
- controllers/ contain request handling and orchestration
- models/ define Mongoose schemas
- services/ hold session-specific business logic
- middlewares/ enforce auth
- utils/ contains cross-cutting helpers like JWT, email, and code generation
- src/index.js is the server entrypoint, and src/config/db.js connects to MongoDB.
3. Core data model
- The main persisted entities are:
- User for accounts, profile, auth state, and stats
- Quiz for quiz definitions and visibility/publication
- Question for reusable question-bank items
- QuizAttempt for completed quiz results and history
- LiveSession for active real-time game rooms
- These models are the primary source of truth for dashboard, quiz creation, attempts, and live gameplay.
4. Authentication and account flows
- Auth is a dedicated backend subsystem exposed under /api/auth.
- It supports email/password login, Google OAuth login, refresh-token based session renewal, email verification, and forgot/reset password flows.
- JWT handling is centralized in utils/jwt.js, while transactional emails are handled through utils/email.js.
- Protected routes use middlewares/auth.middleware.js, which is the boundary between anonymous and authenticated API access.
5. Quiz and question management
- Quizzes and questions are separate concerns:
- question.routes.js and question.controller.js manage the reusable question bank
- quiz.routes.js and quiz.controller.js manage quiz creation, updates, deletion, public listing, and attempt submission
- This separation lets the UI build quizzes either manually or from existing banked questions, and also supports community/public quizzes.
6. AI generation subsystem
- The /api/ai routes expose question and quiz generation powered by Google Gemini.
- The backend supports generation from a topic, from uploaded files, and full quiz generation that can be saved directly.
- This is an external-service integration boundary: the app’s content creation pipeline can come from either user-authored data or Gemini-generated content.
7. Live session architecture
- Real-time quiz play is handled as a distinct subsystem under /api/live plus src/socket/.
- liveSession.service.js encapsulates session lifecycle logic, while Socket.IO provides live updates such as lobby state and leaderboard progression.
- Join codes are generated in utils/generateCode.js, and the live session model stores room/session state.
- This is the only part of the system that depends on bidirectional real-time messaging rather than standard request/response HTTP.
8. Frontend application shell
- The frontend is a React single-page app with route-based pages under src/pages/.
- App.jsx and main.jsx set up the app root, while components/layout/ provides the shared shell: sidebar, top navigation, app layout, and protected-route wrapper.
- The app includes separate page groups for landing, auth, dashboard, quiz management, question bank, profile, live lobby/session, and solo quiz play/results.
9. Frontend state and API integration
- Global client state is split by domain using Zustand stores:
- authStore.js
- quizStore.js
- questionStore.js
- useLiveStore.js
- HTTP access goes through src/lib/axios.js, which is the likely place where token attachment and refresh handling are centralized.
- This creates a clear client-side boundary between view components and backend data fetching.
10. User-facing flows
- The app supports several distinct flows:
- onboarding/authentication
- dashboard/statistics review
- quiz authoring
- question bank management
- solo quiz play and results
- live session hosting/joining via code
- The live flow is especially important: a host creates a session, players join via a code, and the session page consumes real-time updates.
11. External systems
- MongoDB is the primary database.
- Google services are used in two places: OAuth login and Gemini-based AI generation.
- Nodemailer sends verification and password-reset emails through SMTP, typically Gmail App Password configuration.
- Socket.IO is the runtime transport for live gameplay events.
12. Deployment/runtime split
- The backend runs as a Node.js/Express server, configured through backend/.env.
- The frontend is a separate Vite build/runtime with its own environment variables for API and socket endpoints.
- frontend/vercel.json suggests the SPA is intended for static hosting, independent from the API server.
13. How to draw the architecture
- A good diagram would show:
- Browser/React SPA on one side
- Express API on the other
- MongoDB as the shared persistence layer
- Socket.IO as a parallel real-time channel for live sessions
- Google/Gemini and email SMTP as external integrations
- The main functional clusters are auth, quiz/question content, AI generation, and live multiplayer.
Main entry points: index.js Server entry · auth.controller.js Auth logic · User.model.js Domain models · App.jsx App shell
Components 26
Frontend SPA
React + Vite client application
- App shell · Bootstraps the SPA and top-level routing
frontend/src/App.jsx - UI layout · Sidebar, top nav, protected route wrapper, and app layout
frontend/src/components/layout/AppLayout.jsx - Auth pages · Login, register, verify email, and password reset screens
frontend/src/pages/auth/LoginPage.jsx - Main pages · Dashboard, quizzes, question bank, profile, and landing pages
frontend/src/pages/DashboardPage.jsx - Play pages · Solo quiz play, live lobby, live session, join, and results screens
frontend/src/pages/QuizPlayPage.jsx - Client state · Auth, quiz, question, and live session state
frontend/src/store/authStore.js - API client · Axios wrapper for backend requests and token handling
frontend/src/lib/axios.js
Backend API
Express + MongoDB server and real-time services
- Server entry · Starts the API server and wires runtime startup
backend/src/index.js - Mongo connect · Database connection setup
backend/src/config/db.js - Auth API · Login, OAuth, refresh, verification, and password reset endpoints
backend/src/routes/auth.routes.js - Quiz API · Quiz CRUD, public listing, and attempt submission endpoints
backend/src/routes/quiz.routes.js - Question API · Reusable question-bank endpoints
backend/src/routes/question.routes.js - AI API · Gemini-backed content generation endpoints
backend/src/routes/ai.routes.js - Live API · Live session lifecycle and room endpoints
backend/src/routes/live.routes.js - Auth logic · Handles authentication and account workflows
backend/src/controllers/auth.controller.js - Quiz logic · Orchestrates quiz creation, updates, and attempts
backend/src/controllers/quiz.controller.js - Question logic · Manages the question bank
backend/src/controllers/question.controller.js - AI logic · Coordinates topic/file/quiz generation flows
backend/src/controllers/ai.controller.js - Live session svc · Session lifecycle, lobby state, and leaderboard progression
backend/src/services/liveSession.service.js - Domain models · Users, quizzes, questions, attempts, and live sessions
backend/src/models/User.model.js - Auth guard · Protects authenticated API boundaries
backend/src/middlewares/auth.middleware.js - Socket.IO · Bidirectional live gameplay channel
backend/src/socket/index.js - Shared utils · JWT, email delivery, and join-code generation
backend/src/utils/jwt.js
External systems
Third-party services used by the app
- MongoDB · Primary persistence layer
- Google services · Google OAuth login and Gemini content generation
- SMTP email · Verification and password-reset emails
Connections 33
- App shell → UI layout: renders with · App shell uses the shared layout and route protections
- App shell → Auth pages: routes to · Auth-related pages are mounted in the client router
- App shell → Main pages: routes to · Primary dashboard and content pages are mounted in the client router
- App shell → Play pages: routes to · Quiz play and live session pages are mounted in the client router
- Auth pages → Client state: reads/writes · Auth screens update global authentication state
- Main pages → Client state: reads/writes · Dashboard and content pages consume domain state
- Play pages → Client state: reads/writes · Play flow and live session pages consume live state
- Client state → API client: calls · Stores trigger HTTP requests through the shared API client
- API client → Server entry: requests · Client talks to the backend API over HTTP
- Server entry → Mongo connect: connects · Server initializes database connectivity
- Server entry → Auth API: mounts · Auth routes are registered on the API server
- Server entry → Quiz API: mounts · Quiz routes are registered on the API server
- Server entry → Question API: mounts · Question routes are registered on the API server
- Server entry → AI API: mounts · AI routes are registered on the API server
- Server entry → Live API: mounts · Live routes are registered on the API server
- Auth API → Auth logic: delegates to · Auth endpoints hand off to controller logic
- Quiz API → Quiz logic: delegates to · Quiz endpoints hand off to controller logic
- Question API → Question logic: delegates to · Question endpoints hand off to controller logic
- AI API → AI logic: delegates to · AI endpoints hand off to controller logic
- Live API → Live session svc: delegates to · Live session endpoints use the session service
- Auth logic → Domain models: uses · Auth flows persist and read user records
- Quiz logic → Domain models: uses · Quiz flows persist quiz and attempt records
- Question logic → Domain models: uses · Question bank operations persist question records
- Live session svc → Domain models: uses · Live rooms and session state are stored in MongoDB
- Auth logic → Auth guard: protected by · Authenticated routes are guarded by middleware
- Auth logic → Shared utils: uses · JWT and email helpers support auth flows
- AI logic → Google services: calls · Content generation uses Gemini and Google integrations
- Auth logic → Google services: calls · OAuth login depends on Google identity services
- Auth logic → SMTP email: calls · Verification and reset emails are sent via SMTP
- Domain models → Mongo connect: persists via · Domain models are stored in MongoDB
- Socket.IO → Live session svc: syncs with · Socket events reflect live session lifecycle
- Socket.IO → Play pages: streams to · Live pages consume real-time quiz events
- Live session svc → Shared utils: uses · Join-code generation supports live room creation