# izanamikiyoko/lumiquiz-website-project architecture

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

- Interactive diagram: https://gitdiagram.com/izanamikiyoko/lumiquiz-website-project
- Repository: https://github.com/izanamikiyoko/lumiquiz-website-project

## Overview

1. **Repository shape**
   - This is a full-stack quiz/game platform called **LumiQuiz**.
   - The main production-style stack is split into:
     - `frontend/`: React SPA
     - `backend/`: Node.js API server
   - There is also a separate `backend-elysia/` service, which looks like an alternate or experimental backend built with **Bun + Elysia**.

2. **Frontend boundary**
   - The frontend is a single-page React app with page-level routing in `frontend/src/pages/App.jsx`.
   - It is organized by feature area rather than by framework layer: home, auth, quiz authoring, flashcards, profile, history, and live gameplay.
   - Shared UI lives in `frontend/src/components/`, including reusable controls, modals, popups, audio/sound helpers, and quiz/game display widgets.

3. **Client-to-server communication**
   - Server access is centralized in `frontend/src/services/`:
     - `api.js` for general HTTP requests
     - `flashcardApi.js` for flashcard-specific calls
     - `websocket.js` for real-time connections
   - Gameplay-specific socket logic is also separated into hooks like `useLobby.js` and `useGameplaySocket.js`, indicating the app mixes REST for CRUD flows and sockets for live game state.

4. **Quiz authoring subsystem**
   - `frontend/src/pages/quiz/` contains the quiz editor and all question-type editors.
   - The presence of separate editors for multiple choice, fill-in-the-blank, reorder, slider, true/false, type-answer, and pin questions implies a polymorphic quiz model on the backend.
   - This area likely sends structured quiz definitions to the API, which persists them and later reuses them in live sessions.

5. **Live gameplay subsystem**
   - `frontend/src/pages/gameplay/` is the most stateful part of the UI and is split into lobby, quizing, leaderboard, host dashboard, statistic, and endgame views.
   - This strongly suggests a real-time multiplayer flow:
     - host creates or opens a room
     - players join lobby
     - live questions are pushed during the game
     - scores and leaderboards update continuously
   - The dedicated socket hooks and `backend/src/config/socket.js` indicate WebSocket-style coordination is a core boundary of the system.

6. **Flashcard subsystem**
   - Flashcards are handled as a separate product area from quizzes.
   - Frontend pages cover flashcard browsing and study mode, with reusable card components and skeleton/loading states.
   - On the server side there are dedicated flashcard routes, controllers, and a `flashcardSet` model, so flashcards are persisted and managed independently of quiz sessions.

7. **Backend API architecture**
   - The primary backend follows a standard layered Express-style structure:
     - `routes/` define endpoints
     - `controllers/` implement request handling
     - `middleware/` handles cross-cutting concerns
     - `models/` define persistent entities
   - Main functional domains are auth, quizzes, flashcards, AI, history, profile, and user management.
   - `backend/src/server.js` is the API entry point, while `backend/src/config/` wires infrastructure dependencies.

8. **Data model and persistence**
   - The backend uses multiple Mongo-style model definitions, including:
     - `User`
     - `Quiz` / `quizzes`
     - `flashcardSet`
     - `history`
     - `player`
     - `verify`
   - The model names suggest three major persisted domains:
     - account and verification data
     - authored content such as quizzes and flashcards
     - gameplay/session history and player participation
   - The duplication of some model names across files suggests the repo contains evolving or parallel schema versions.

9. **Infrastructure and external services**
   - The backend configuration files indicate several external integrations that materially shape the architecture:
     - **Redis** for shared transient state, likely sessions, sockets, or room/game coordination
     - **Firebase** for authentication or identity-related workflows
     - **Cloudinary** for media storage, likely avatars or uploaded assets
     - **Mail** for email-based flows such as verification or password reset
   - `authMiddleware` and `rateLimiter` show that security and abuse control are part of the server boundary.

10. **AI-assisted quiz creation**
   - `backend/src/controllers/aiController.js` and `backend/src/routes/aiRoutes.js` indicate an AI-assisted feature surface.
   - In the frontend this is reflected by `create_ai_quiz/`, which likely lets users generate quiz content via server-side AI calls.
   - This is a separate domain from normal CRUD quiz editing and should be drawn as a distinct service path in an architecture diagram.

11. **History and profile flows**
   - `historyController` / `historyRoutes` and the `history` model indicate that gameplay or study activity is recorded and later surfaced in the UI.
   - `profileRoute` and `userController` suggest user-facing account/profile management separate from authentication.
   - These flows probably depend on authenticated requests and read from the same persistent store as quizzes and flashcards.

12. **Secondary backend-elysia service**
   - `backend-elysia/` mirrors some of the same domains but is structured differently and uses Bun/Elysia rather than the main Node backend.
   - It contains its own `db`, `redis`, `socket` config and models for `User`, `history`, `player`, `quizzes`, and `rooms`.
   - Architecturally, this looks like either:
     - a newer real-time backend implementation
     - a lightweight socket/game server
     - or a migration path away from the main Express server
   - For a diagram, it should be shown as a separate backend boundary, not merged with the main API unless the deployment context confirms that.

13. **Testing and quality gates**
   - The repo includes extensive **Cypress** end-to-end tests.
   - Tests cover auth, flashcards, quiz creation, lobby behavior, and bot-driven gameplay scenarios.
   - There are also separate bot-focused specs under `test/`, which reinforces that multiplayer/game-lobby behavior is an important system invariant worth diagramming as a tested workflow.

14. **Overall interaction model**
   - The clearest system diagram is:
     - browser SPA in `frontend/`
     - REST API + auth/content services in `backend/`
     - WebSocket layer for lobby/gameplay synchronization
     - persistent MongoDB-style models for users, quizzes, flashcards, history, and players
     - Redis and external services supporting real-time and auxiliary features
   - The main architectural distinction is between **content CRUD** and **live multiplayer gameplay**, with AI and flashcards as adjacent but separate product flows.

Main entry points: [`frontend/src/pages/App.jsx`](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/App.jsx) (App shell), [`backend/src/server.js`](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/server.js) (API server), [`backend/src/config/db.js`](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/config/db.js) (Infra config), [`cypress/e2e/quiz/create_quiz.cy.js`](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/cypress/e2e/quiz/create_quiz.cy.js) (Cypress specs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["App shell<br/>React router<br/>[App.jsx]"]
  node_fe_home["Home<br/>landing page<br/>[home.jsx]"]
  node_fe_auth["Auth pages<br/>auth screens<br/>[Login.jsx]"]
  node_fe_quiz["Quiz builder<br/>authoring UI<br/>[CreateQuiz.jsx]"]
  node_fe_flashcard["Flashcards<br/>study UI<br/>[flashcard.jsx]"]
  node_fe_gameplay["Gameplay<br/>multiplayer UI<br/>[Game.jsx]"]
  node_fe_profile["Profile<br/>account UI<br/>[Profile.jsx]"]
  node_fe_history["History<br/>activity UI<br/>[history.jsx]"]
  node_fe_ai["AI quiz<br/>generated content UI<br/>[CreateAiQuiz.jsx]"]
  node_fe_services["Client services<br/>api + socket clients<br/>[api.js]"]
  node_fe_socket_hooks["Gameplay hooks<br/>realtime hooks"]
  node_fe_shared_ui["Shared UI<br/>component library<br/>[Header.jsx]"]
end

subgraph group_backend["Main Backend"]
  node_be_server["API server<br/>Express entrypoint<br/>[server.js]"]
  node_be_auth["Auth domain<br/>auth + identity<br/>[authController.js]"]
  node_be_quiz["Quiz domain<br/>quiz CRUD<br/>[quizController.js]"]
  node_be_flashcard["Flashcard domain<br/>flashcard CRUD"]
  node_be_gameplay[("Gameplay state<br/>history + player data<br/>[player.js]")]
  node_be_ai["AI service<br/>quiz generation<br/>[aiController.js]"]
  node_be_infra["Infra config<br/>integrations<br/>[db.js]"]
end

subgraph group_elysia["Alt Backend"]
  node_ey_entry["Elysia app<br/>Bun service<br/>[index.ts]"]
  node_ey_realtime["Elysia realtime<br/>socket + cache<br/>[socket.ts]"]
  node_ey_models[("Elysia models<br/>domain models<br/>[rooms.js]")]
end

subgraph group_quality["Testing"]
  node_qa_cypress["Cypress specs<br/>e2e tests<br/>[create_quiz.cy.js]"]
end

node_fe_app -->|"routes to"| node_fe_home
node_fe_app -->|"routes to"| node_fe_auth
node_fe_app -->|"routes to"| node_fe_quiz
node_fe_app -->|"routes to"| node_fe_flashcard
node_fe_app -->|"routes to"| node_fe_gameplay
node_fe_app -->|"routes to"| node_fe_profile
node_fe_app -->|"routes to"| node_fe_history
node_fe_app -->|"routes to"| node_fe_ai
node_fe_quiz -->|"CRUD calls"| node_fe_services
node_fe_flashcard -->|"CRUD calls"| node_fe_services
node_fe_gameplay -->|"live state"| node_fe_socket_hooks
node_fe_socket_hooks -->|"socket + api"| node_fe_services
node_fe_shared_ui -->|"renders"| node_fe_quiz
node_fe_shared_ui -->|"renders"| node_fe_flashcard
node_fe_shared_ui -->|"renders"| node_fe_gameplay
node_fe_services -->|"HTTP"| node_be_server
node_fe_socket_hooks -->|"websocket"| node_be_server
node_be_server -->|"exposes"| node_be_auth
node_be_server -->|"exposes"| node_be_quiz
node_be_server -->|"exposes"| node_be_flashcard
node_be_server -->|"persists"| node_be_gameplay
node_be_server -->|"exposes"| node_be_ai
node_be_server -->|"uses"| node_be_infra
node_be_auth -->|"auth deps"| node_be_infra
node_be_quiz -->|"stores"| node_be_infra
node_be_flashcard -->|"stores"| node_be_infra
node_be_ai -->|"external calls"| node_be_infra
node_be_gameplay -->|"shared state"| node_be_infra
node_ey_entry -->|"wires"| node_ey_realtime
node_ey_entry -->|"loads"| node_ey_models
node_ey_realtime -->|"supports"| node_ey_models
node_qa_cypress -->|"tests"| node_fe_auth
node_qa_cypress -->|"tests"| node_fe_flashcard
node_qa_cypress -->|"tests"| node_fe_quiz
node_qa_cypress -->|"tests"| node_fe_gameplay

click node_fe_app "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/App.jsx"
click node_fe_home "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/home/home.jsx"
click node_fe_auth "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/login/Login.jsx"
click node_fe_quiz "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/quiz/CreateQuiz.jsx"
click node_fe_flashcard "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/flashcard/flashcard.jsx"
click node_fe_gameplay "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/gameplay/Game.jsx"
click node_fe_profile "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/profile/Profile.jsx"
click node_fe_history "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/History/history.jsx"
click node_fe_ai "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/create_ai_quiz/CreateAiQuiz.jsx"
click node_fe_services "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/services/api.js"
click node_fe_socket_hooks "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/gameplay/useGameplaySocket.js"
click node_fe_shared_ui "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/components/Header.jsx"
click node_be_server "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/server.js"
click node_be_auth "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/authController.js"
click node_be_quiz "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/quizController.js"
click node_be_flashcard "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/flashcardController.js"
click node_be_gameplay "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/models/player.js"
click node_be_ai "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/aiController.js"
click node_be_infra "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/config/db.js"
click node_ey_entry "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend-elysia/src/index.ts"
click node_ey_realtime "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend-elysia/src/config/socket.ts"
click node_ey_models "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend-elysia/src/models/rooms.js"
click node_qa_cypress "https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/cypress/e2e/quiz/create_quiz.cy.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_fe_app,node_fe_home,node_fe_auth,node_fe_quiz,node_fe_flashcard,node_fe_gameplay,node_fe_profile,node_fe_history,node_fe_ai,node_fe_services,node_fe_socket_hooks,node_fe_shared_ui toneBlue
class node_be_server,node_be_auth,node_be_quiz,node_be_flashcard,node_be_gameplay,node_be_ai,node_be_infra toneAmber
class node_ey_entry,node_ey_realtime,node_ey_models toneMint
class node_qa_cypress toneRose
```

## Components

### Frontend

React SPA and client-side feature areas

- [App shell](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/App.jsx): React router · Top-level SPA routing and page composition · `frontend/src/pages/App.jsx`
- [Home](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/home/home.jsx): landing page · Public entry and feature discovery · `frontend/src/pages/home/home.jsx`
- [Auth pages](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/login/Login.jsx): auth screens · Login, register, and password recovery flows · `frontend/src/pages/login/Login.jsx`
- [Quiz builder](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/quiz/CreateQuiz.jsx): authoring UI · Quiz creation and edit workspace with question editors · `frontend/src/pages/quiz/CreateQuiz.jsx`
- [Flashcards](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/flashcard/flashcard.jsx): study UI · Flashcard browsing and study experience · `frontend/src/pages/flashcard/flashcard.jsx`
- [Gameplay](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/gameplay/Game.jsx): multiplayer UI · Live game, lobby, leaderboard, and endgame views · `frontend/src/pages/gameplay/Game.jsx`
- [Profile](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/profile/Profile.jsx): account UI · User profile and settings screens · `frontend/src/pages/profile/Profile.jsx`
- [History](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/History/history.jsx): activity UI · Past gameplay and study history views · `frontend/src/pages/History/history.jsx`
- [AI quiz](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/create_ai_quiz/CreateAiQuiz.jsx): generated content UI · AI-assisted quiz creation flow · `frontend/src/pages/create_ai_quiz/CreateAiQuiz.jsx`
- [Client services](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/services/api.js): api + socket clients · Centralized REST and websocket access layer · `frontend/src/services/api.js`
- [Gameplay hooks](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/pages/gameplay/useGameplaySocket.js): realtime hooks · Lobby and gameplay socket lifecycle hooks · `frontend/src/pages/gameplay/useGameplaySocket.js`
- [Shared UI](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/frontend/src/components/Header.jsx): component library · Reusable controls, modals, popups, audio, and widgets · `frontend/src/components/Header.jsx`

### Main Backend

Express-style API, data models, and integrations

- [API server](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/server.js): Express entrypoint · Main Node backend entry and route wiring · `backend/src/server.js`
- [Auth domain](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/authController.js): auth + identity · Authentication, verification, and user account flows · `backend/src/controllers/authController.js`
- [Quiz domain](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/quizController.js): quiz CRUD · Quiz persistence, editing, and retrieval · `backend/src/controllers/quizController.js`
- [Flashcard domain](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/flashcardController.js): flashcard CRUD · Flashcard set storage and study APIs · `backend/src/controllers/flashcardController.js`
- [Gameplay state](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/models/player.js): history + player data · Player participation and game history records · `backend/src/models/player.js`
- [AI service](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/controllers/aiController.js): quiz generation · Server-side AI-assisted quiz creation endpoints · `backend/src/controllers/aiController.js`
- [Infra config](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend/src/config/db.js): integrations · Database, Redis, Firebase, mail, and Cloudinary wiring · `backend/src/config/db.js`

### Alt Backend

Bun/Elysia service for real-time or migration path

- [Elysia app](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend-elysia/src/index.ts): Bun service · Alternate backend entrypoint for the Bun/Elysia stack · `backend-elysia/src/index.ts`
- [Elysia realtime](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend-elysia/src/config/socket.ts): socket + cache · Redis and socket configuration for the alternate service · `backend-elysia/src/config/socket.ts`
- [Elysia models](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/backend-elysia/src/models/rooms.js): domain models · Alternate user, room, quiz, history, and player schemas · `backend-elysia/src/models/rooms.js`

### Testing

End-to-end coverage for core user journeys

- [Cypress specs](https://github.com/izanamikiyoko/lumiquiz-website-project/blob/deployment/cypress/e2e/quiz/create_quiz.cy.js): e2e tests · End-to-end coverage for auth, flashcards, quiz creation, and lobby gameplay · `cypress/e2e/quiz/create_quiz.cy.js`

## Connections

- App shell → Home: routes to · SPA navigation exposes the home page
- App shell → Auth pages: routes to · Authentication screens are mounted from the app shell
- App shell → Quiz builder: routes to · Quiz editor pages are part of the main SPA flow
- App shell → Flashcards: routes to · Flashcard study pages are part of the main SPA flow
- App shell → Gameplay: routes to · Live game views are mounted from the app shell
- App shell → Profile: routes to · Profile pages are exposed through the SPA router
- App shell → History: routes to · History views are exposed through the SPA router
- App shell → AI quiz: routes to · AI quiz creation is a separate user flow
- Quiz builder → Client services: CRUD calls · Authoring screens persist quiz data through the API client
- Flashcards → Client services: CRUD calls · Flashcard screens read and write through the API client
- Gameplay → Gameplay hooks: live state · Gameplay UI coordinates lobby and match state through sockets
- Gameplay hooks → Client services: socket + api · Gameplay hooks bridge real-time and HTTP service layers
- Shared UI → Quiz builder: renders · Reusable editors and controls are used by authoring screens
- Shared UI → Flashcards: renders · Shared card and skeleton components support flashcard study
- Shared UI → Gameplay: renders · Shared widgets support live gameplay presentation
- Client services → API server: HTTP · Client services talk to the main backend API
- Gameplay hooks → API server: websocket · Gameplay sockets connect the client to the backend realtime layer
- API server → Auth domain: exposes · Server mounts authentication and identity routes
- API server → Quiz domain: exposes · Server mounts quiz CRUD routes
- API server → Flashcard domain: exposes · Server mounts flashcard routes
- API server → Gameplay state: persists · Gameplay data is stored in shared player and history models
- API server → AI service: exposes · Server mounts AI-assisted quiz endpoints
- API server → Infra config: uses · API depends on shared infrastructure wiring
- Auth domain → Infra config: auth deps · Identity flows depend on database, Firebase, mail, and rate limiting
- Quiz domain → Infra config: stores · Quiz persistence uses the configured backend services
- Flashcard domain → Infra config: stores · Flashcard persistence uses the configured backend services
- AI service → Infra config: external calls · AI generation is mediated through backend integrations
- Gameplay state → Infra config: shared state · Gameplay history and player records use the shared data layer
- Elysia app → Elysia realtime: wires · Alternate backend bootstraps socket and cache config
- Elysia app → Elysia models: loads · Alternate backend serves its own domain models
- Elysia realtime → Elysia models: supports · Realtime coordination uses room and player data
- Cypress specs → Auth pages: tests · Cypress covers registration and password recovery
- Cypress specs → Flashcards: tests · Cypress covers flashcard study flows
- Cypress specs → Quiz builder: tests · Cypress covers quiz creation flows
- Cypress specs → Gameplay: tests · Cypress covers lobby and bot-driven gameplay flows
