# vanshj2006/quizcraft architecture

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

- Interactive diagram: https://gitdiagram.com/vanshj2006/quizcraft
- Repository: https://github.com/vanshj2006/quizcraft

## Overview

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: [`backend/src/index.js`](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/index.js) (Server entry), [`backend/src/controllers/auth.controller.js`](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/auth.controller.js) (Auth logic), [`backend/src/models/User.model.js`](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/models/User.model.js) (Domain models), [`frontend/src/App.jsx`](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_app["App shell<br/>React root<br/>[App.jsx]"]
  node_frontend_layout["UI layout<br/>shared shell<br/>[AppLayout.jsx]"]
  node_frontend_pages_auth["Auth pages<br/>route pages<br/>[LoginPage.jsx]"]
  node_frontend_pages_core["Main pages<br/>route pages<br/>[DashboardPage.jsx]"]
  node_frontend_pages_play["Play pages<br/>route pages<br/>[QuizPlayPage.jsx]"]
  node_frontend_state["Client state<br/>Zustand stores<br/>[authStore.js]"]
  node_frontend_api["API client<br/>HTTP client<br/>[axios.js]"]
end

subgraph group_backend["Backend API"]
  node_backend_entry["Server entry<br/>Express bootstrap<br/>[index.js]"]
  node_backend_db[("Mongo connect<br/>DB config<br/>[db.js]")]
  node_backend_auth_routes["Auth API<br/>routes<br/>[auth.routes.js]"]
  node_backend_quiz_routes["Quiz API<br/>routes<br/>[quiz.routes.js]"]
  node_backend_question_routes["Question API<br/>routes<br/>[question.routes.js]"]
  node_backend_ai_routes["AI API<br/>routes<br/>[ai.routes.js]"]
  node_backend_live_routes["Live API<br/>routes<br/>[live.routes.js]"]
  node_backend_auth_ctrl["Auth logic<br/>controller<br/>[auth.controller.js]"]
  node_backend_quiz_ctrl["Quiz logic<br/>controller<br/>[quiz.controller.js]"]
  node_backend_question_ctrl["Question logic<br/>controller"]
  node_backend_ai_ctrl["AI logic<br/>controller<br/>[ai.controller.js]"]
  node_backend_live_service["Live session svc"]
  node_backend_models[("Domain models<br/>Mongoose models<br/>[User.model.js]")]
  node_backend_auth_mw["Auth guard<br/>middleware<br/>[auth.middleware.js]"]
  node_backend_socket(("Socket.IO<br/>realtime transport<br/>[index.js]"))
  node_backend_utils["Shared utils<br/>helpers<br/>[jwt.js]"]
end

subgraph group_external["External systems"]
  node_external_mongo[("MongoDB<br/>database")]
  node_external_google{{"Google services<br/>oauth + gemini"}}
  node_external_email{{"SMTP email<br/>mail delivery"}}
end

node_frontend_app -->|"renders with"| node_frontend_layout
node_frontend_app -->|"routes to"| node_frontend_pages_auth
node_frontend_app -->|"routes to"| node_frontend_pages_core
node_frontend_app -->|"routes to"| node_frontend_pages_play
node_frontend_pages_auth -->|"reads/writes"| node_frontend_state
node_frontend_pages_core -->|"reads/writes"| node_frontend_state
node_frontend_pages_play -->|"reads/writes"| node_frontend_state
node_frontend_state -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_entry
node_backend_entry -->|"connects"| node_backend_db
node_backend_entry -->|"mounts"| node_backend_auth_routes
node_backend_entry -->|"mounts"| node_backend_quiz_routes
node_backend_entry -->|"mounts"| node_backend_question_routes
node_backend_entry -->|"mounts"| node_backend_ai_routes
node_backend_entry -->|"mounts"| node_backend_live_routes
node_backend_auth_routes -->|"delegates to"| node_backend_auth_ctrl
node_backend_quiz_routes -->|"delegates to"| node_backend_quiz_ctrl
node_backend_question_routes -->|"delegates to"| node_backend_question_ctrl
node_backend_ai_routes -->|"delegates to"| node_backend_ai_ctrl
node_backend_live_routes -->|"delegates to"| node_backend_live_service
node_backend_auth_ctrl -->|"uses"| node_backend_models
node_backend_quiz_ctrl -->|"uses"| node_backend_models
node_backend_question_ctrl -->|"uses"| node_backend_models
node_backend_live_service -->|"uses"| node_backend_models
node_backend_auth_ctrl -->|"protected by"| node_backend_auth_mw
node_backend_auth_ctrl -->|"uses"| node_backend_utils
node_backend_ai_ctrl -->|"calls"| node_external_google
node_backend_auth_ctrl -->|"calls"| node_external_google
node_backend_auth_ctrl -->|"calls"| node_external_email
node_backend_models -->|"persists via"| node_backend_db
node_backend_socket -->|"syncs with"| node_backend_live_service
node_backend_socket -->|"streams to"| node_frontend_pages_play
node_backend_live_service -->|"uses"| node_backend_utils

click node_frontend_app "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/App.jsx"
click node_frontend_layout "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/components/layout/AppLayout.jsx"
click node_frontend_pages_auth "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/pages/auth/LoginPage.jsx"
click node_frontend_pages_core "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_frontend_pages_play "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/pages/QuizPlayPage.jsx"
click node_frontend_state "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/store/authStore.js"
click node_frontend_api "https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/lib/axios.js"
click node_backend_entry "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/index.js"
click node_backend_db "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/config/db.js"
click node_backend_auth_routes "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/auth.routes.js"
click node_backend_quiz_routes "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/quiz.routes.js"
click node_backend_question_routes "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/question.routes.js"
click node_backend_ai_routes "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/ai.routes.js"
click node_backend_live_routes "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/live.routes.js"
click node_backend_auth_ctrl "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/auth.controller.js"
click node_backend_quiz_ctrl "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/quiz.controller.js"
click node_backend_question_ctrl "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/question.controller.js"
click node_backend_ai_ctrl "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/ai.controller.js"
click node_backend_live_service "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/services/liveSession.service.js"
click node_backend_models "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/models/User.model.js"
click node_backend_auth_mw "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/middlewares/auth.middleware.js"
click node_backend_socket "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/socket/index.js"
click node_backend_utils "https://github.com/vanshj2006/quizcraft/blob/main/backend/src/utils/jwt.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_frontend_app,node_frontend_layout,node_frontend_pages_auth,node_frontend_pages_core,node_frontend_pages_play,node_frontend_state,node_frontend_api toneBlue
class node_backend_entry,node_backend_db,node_backend_auth_routes,node_backend_quiz_routes,node_backend_question_routes,node_backend_ai_routes,node_backend_live_routes,node_backend_auth_ctrl,node_backend_quiz_ctrl,node_backend_question_ctrl,node_backend_ai_ctrl,node_backend_live_service,node_backend_models,node_backend_auth_mw,node_backend_socket,node_backend_utils toneAmber
class node_external_mongo,node_external_google,node_external_email toneMint
```

## Components

### Frontend SPA

React + Vite client application

- [App shell](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/App.jsx): React root · Bootstraps the SPA and top-level routing · `frontend/src/App.jsx`
- [UI layout](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/components/layout/AppLayout.jsx): shared shell · Sidebar, top nav, protected route wrapper, and app layout · `frontend/src/components/layout/AppLayout.jsx`
- [Auth pages](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/pages/auth/LoginPage.jsx): route pages · Login, register, verify email, and password reset screens · `frontend/src/pages/auth/LoginPage.jsx`
- [Main pages](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/pages/DashboardPage.jsx): route pages · Dashboard, quizzes, question bank, profile, and landing pages · `frontend/src/pages/DashboardPage.jsx`
- [Play pages](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/pages/QuizPlayPage.jsx): route pages · Solo quiz play, live lobby, live session, join, and results screens · `frontend/src/pages/QuizPlayPage.jsx`
- [Client state](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/store/authStore.js): Zustand stores · Auth, quiz, question, and live session state · `frontend/src/store/authStore.js`
- [API client](https://github.com/vanshj2006/quizcraft/blob/main/frontend/src/lib/axios.js): HTTP 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](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/index.js): Express bootstrap · Starts the API server and wires runtime startup · `backend/src/index.js`
- [Mongo connect](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/config/db.js): DB config · Database connection setup · `backend/src/config/db.js`
- [Auth API](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/auth.routes.js): routes · Login, OAuth, refresh, verification, and password reset endpoints · `backend/src/routes/auth.routes.js`
- [Quiz API](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/quiz.routes.js): routes · Quiz CRUD, public listing, and attempt submission endpoints · `backend/src/routes/quiz.routes.js`
- [Question API](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/question.routes.js): routes · Reusable question-bank endpoints · `backend/src/routes/question.routes.js`
- [AI API](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/ai.routes.js): routes · Gemini-backed content generation endpoints · `backend/src/routes/ai.routes.js`
- [Live API](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/routes/live.routes.js): routes · Live session lifecycle and room endpoints · `backend/src/routes/live.routes.js`
- [Auth logic](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/auth.controller.js): controller · Handles authentication and account workflows · `backend/src/controllers/auth.controller.js`
- [Quiz logic](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/quiz.controller.js): controller · Orchestrates quiz creation, updates, and attempts · `backend/src/controllers/quiz.controller.js`
- [Question logic](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/question.controller.js): controller · Manages the question bank · `backend/src/controllers/question.controller.js`
- [AI logic](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/controllers/ai.controller.js): controller · Coordinates topic/file/quiz generation flows · `backend/src/controllers/ai.controller.js`
- [Live session svc](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/services/liveSession.service.js): service · Session lifecycle, lobby state, and leaderboard progression · `backend/src/services/liveSession.service.js`
- [Domain models](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/models/User.model.js): Mongoose models · Users, quizzes, questions, attempts, and live sessions · `backend/src/models/User.model.js`
- [Auth guard](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/middlewares/auth.middleware.js): middleware · Protects authenticated API boundaries · `backend/src/middlewares/auth.middleware.js`
- [Socket.IO](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/socket/index.js): realtime transport · Bidirectional live gameplay channel · `backend/src/socket/index.js`
- [Shared utils](https://github.com/vanshj2006/quizcraft/blob/main/backend/src/utils/jwt.js): helpers · JWT, email delivery, and join-code generation · `backend/src/utils/jwt.js`

### External systems

Third-party services used by the app

- **MongoDB**: database · Primary persistence layer
- **Google services**: oauth + gemini · Google OAuth login and Gemini content generation
- **SMTP email**: mail delivery · Verification and password-reset emails

## Connections

- 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