# syedwasif1234/quizmaster architecture

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

- Interactive diagram: https://gitdiagram.com/syedwasif1234/quizmaster
- Repository: https://github.com/syedwasif1234/quizmaster

## Overview

QuizMaster is a role-aware quiz authoring and play application with a separate real-time 1v1 battle mode. Users authenticate, browse categories and quizzes, answer questions, and submit quiz attempts; faculty/admin capabilities cover content management. In the battle flow, a player creates or joins a room, the server loads a quiz, stores transient room state in Redis, validates answers, and broadcasts progress and results. The tree and README establish the major subsystems; unsampled page and controller wiring is represented only where documented or visible in sampled source.

Main entry points: [`backend/src/index.js`](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/index.js) (HTTP and socket server), [`frontend/src/App.jsx`](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/App.jsx) (App routing), [`backend/src/quiz/quiz.controller.js`](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/quiz/quiz.controller.js) (Quiz management), [`backend/src/socket/socketHandler.js`](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/socket/socketHandler.js) (Battle event handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routing<br/>[App.jsx]"]
  node_authui["Auth state<br/>[useAuthStore.js]"]
  node_categoryui["Category state"]
  node_quizui["Quiz state"]
  node_battleui["Battle state<br/>[useSocketStore.js]"]
  node_authpages["Login and signup<br/>[LoginPage.jsx]"]
  node_quizpages["Quiz pages<br/>[HomePage.jsx]"]
  node_battlepages["Battle pages<br/>[BattleMode.jsx]"]
  node_api["HTTP client<br/>[axios.js]"]
end

subgraph group_identity["Identity and access"]
  node_authroutes["Auth routes<br/>[auth.router.js]"]
  node_authcontroller["Auth operations<br/>[auth.controller.js]"]
  node_authguard["Session guard<br/>[auth.middleware.js]"]
  node_roles["Role checks"]
end

subgraph group_content["Quiz content"]
  node_categories["Category management"]
  node_quizzes["Quiz management<br/>[quiz.controller.js]"]
  node_questions["Question and scoring"]
  node_postgres[("PostgreSQL via Prisma<br/>[db.js]")]
end

subgraph group_battle["Live battles"]
  node_battles["Battle event handler<br/>[socketHandler.js]"]
  node_redis[("Redis room state<br/>[redis.js]")]
end

node_player(("User"))
node_server["HTTP and socket server<br/>[index.js]"]

node_player -->|"uses"| node_app
node_app -->|"routes to"| node_authpages
node_app -->|"routes to"| node_quizpages
node_app -->|"routes to"| node_battlepages
node_app -->|"checks session"| node_authui
node_authpages -->|"updates auth"| node_authui
node_authui -->|"sends requests"| node_api
node_api -->|"HTTP requests"| node_server
node_server -->|"mounts routes"| node_authroutes
node_authroutes -->|"guards routes"| node_authguard
node_authroutes -->|"dispatches"| node_authcontroller
node_authcontroller -->|"reads and writes"| node_postgres
node_server -->|"mounts category API"| node_categories
node_server -->|"mounts quiz API"| node_quizzes
node_server -->|"mounts question API"| node_questions
node_categories -->|"reads and writes"| node_postgres
node_quizzes -->|"reads and writes"| node_postgres
node_questions -->|"reads and writes"| node_postgres
node_quizzes -->|"loads quiz data"| node_questions
node_server -->|"initializes sockets"| node_battles
node_battles -->|"fetches quiz"| node_quizzes
node_battles -->|"stores room state"| node_redis
node_battleui -->|"socket events"| node_battles
node_battlepages -->|"uses battle state"| node_battleui
node_quizpages -->|"browses categories"| node_categoryui
node_quizpages -->|"uses quiz state"| node_quizui
node_roles -->|"restricts actions"| node_categories
node_roles -->|"restricts actions"| node_quizzes

click node_app "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useAuthStore.js"
click node_categoryui "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useCategoryStore.js"
click node_quizui "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useQuiz_QuesStore.js"
click node_battleui "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useSocketStore.js"
click node_authpages "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/pages/LoginPage.jsx"
click node_quizpages "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/pages/HomePage.jsx"
click node_battlepages "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/pages/BattleMode.jsx"
click node_api "https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/lib/axios.js"
click node_server "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/index.js"
click node_authroutes "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/auth/auth.router.js"
click node_authcontroller "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/auth/auth.controller.js"
click node_authguard "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/middleware/auth.middleware.js"
click node_roles "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/middleware/admin%26faculty.middleware.js"
click node_categories "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/category/category.controller.js"
click node_quizzes "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/quiz/quiz.controller.js"
click node_questions "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/questions/questions.controller.js"
click node_battles "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/socket/socketHandler.js"
click node_postgres "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/lib/db.js"
click node_redis "https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/lib/redis.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_app,node_authui,node_categoryui,node_quizui,node_battleui,node_authpages,node_quizpages,node_battlepages,node_api,node_player toneBlue
class node_authroutes,node_authcontroller,node_authguard,node_roles toneAmber
class node_categories,node_quizzes,node_questions,node_postgres,node_server toneMint
class node_battles,node_redis toneRose
```

## Components

### Web client

- [App routing](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useAuthStore.js): `frontend/src/store/useAuthStore.js`
- [Category state](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useCategoryStore.js): `frontend/src/store/useCategoryStore.js`
- [Quiz state](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useQuiz_QuesStore.js): `frontend/src/store/useQuiz_QuesStore.js`
- [Battle state](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/store/useSocketStore.js): `frontend/src/store/useSocketStore.js`
- [Login and signup](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/pages/LoginPage.jsx): `frontend/src/pages/LoginPage.jsx`
- [Quiz pages](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/pages/HomePage.jsx): `frontend/src/pages/HomePage.jsx`
- [Battle pages](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/pages/BattleMode.jsx): `frontend/src/pages/BattleMode.jsx`
- [HTTP client](https://github.com/syedwasif1234/quizmaster/blob/main/frontend/src/lib/axios.js): `frontend/src/lib/axios.js`

### Identity and access

- [Auth routes](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/auth/auth.router.js): `backend/src/auth/auth.router.js`
- [Auth operations](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/auth/auth.controller.js): `backend/src/auth/auth.controller.js`
- [Session guard](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/middleware/auth.middleware.js): `backend/src/middleware/auth.middleware.js`
- [Role checks](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/middleware/admin%26faculty.middleware.js): `backend/src/middleware/admin&faculty.middleware.js`

### Quiz content

- [Category management](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/category/category.controller.js): `backend/src/category/category.controller.js`
- [Quiz management](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/quiz/quiz.controller.js): `backend/src/quiz/quiz.controller.js`
- [Question and scoring](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/questions/questions.controller.js): `backend/src/questions/questions.controller.js`
- [PostgreSQL via Prisma](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/lib/db.js): `backend/src/lib/db.js`

### Live battles

- [Battle event handler](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/socket/socketHandler.js): `backend/src/socket/socketHandler.js`
- [Redis room state](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/lib/redis.js): `backend/src/lib/redis.js`

### Other components

- **User**
- [HTTP and socket server](https://github.com/syedwasif1234/quizmaster/blob/main/backend/src/index.js): `backend/src/index.js`

## Connections

- User → App routing: uses
- App routing → Login and signup: routes to
- App routing → Quiz pages: routes to
- App routing → Battle pages: routes to
- App routing → Auth state: checks session
- Login and signup → Auth state: updates auth
- Auth state → HTTP client: sends requests
- HTTP client → HTTP and socket server: HTTP requests
- HTTP and socket server → Auth routes: mounts routes
- Auth routes → Session guard: guards routes
- Auth routes → Auth operations: dispatches
- Auth operations → PostgreSQL via Prisma: reads and writes
- HTTP and socket server → Category management: mounts category API
- HTTP and socket server → Quiz management: mounts quiz API
- HTTP and socket server → Question and scoring: mounts question API
- Category management → PostgreSQL via Prisma: reads and writes
- Quiz management → PostgreSQL via Prisma: reads and writes
- Question and scoring → PostgreSQL via Prisma: reads and writes
- Quiz management → Question and scoring: loads quiz data
- HTTP and socket server → Battle event handler: initializes sockets
- Battle event handler → Quiz management: fetches quiz
- Battle event handler → Redis room state: stores room state
- Battle state → Battle event handler: socket events
- Battle pages → Battle state: uses battle state
- Quiz pages → Category state: browses categories
- Quiz pages → Quiz state: uses quiz state
- Role checks → Category management: restricts actions
- Role checks → Quiz management: restricts actions