How izanamikiyoko/lumiquiz-website-project works
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: App.jsx App shell · server.js API server · db.js Infra config · create_quiz.cy.js Cypress specs
Components 23
Frontend
React SPA and client-side feature areas
- App shell · Top-level SPA routing and page composition
frontend/src/pages/App.jsx - Home · Public entry and feature discovery
frontend/src/pages/home/home.jsx - Auth pages · Login, register, and password recovery flows
frontend/src/pages/login/Login.jsx - Quiz builder · Quiz creation and edit workspace with question editors
frontend/src/pages/quiz/CreateQuiz.jsx - Flashcards · Flashcard browsing and study experience
frontend/src/pages/flashcard/flashcard.jsx - Gameplay · Live game, lobby, leaderboard, and endgame views
frontend/src/pages/gameplay/Game.jsx - Profile · User profile and settings screens
frontend/src/pages/profile/Profile.jsx - History · Past gameplay and study history views
frontend/src/pages/History/history.jsx - AI quiz · AI-assisted quiz creation flow
frontend/src/pages/create_ai_quiz/CreateAiQuiz.jsx - Client services · Centralized REST and websocket access layer
frontend/src/services/api.js - Gameplay hooks · Lobby and gameplay socket lifecycle hooks
frontend/src/pages/gameplay/useGameplaySocket.js - Shared UI · Reusable controls, modals, popups, audio, and widgets
frontend/src/components/Header.jsx
Main Backend
Express-style API, data models, and integrations
- API server · Main Node backend entry and route wiring
backend/src/server.js - Auth domain · Authentication, verification, and user account flows
backend/src/controllers/authController.js - Quiz domain · Quiz persistence, editing, and retrieval
backend/src/controllers/quizController.js - Flashcard domain · Flashcard set storage and study APIs
backend/src/controllers/flashcardController.js - Gameplay state · Player participation and game history records
backend/src/models/player.js - AI service · Server-side AI-assisted quiz creation endpoints
backend/src/controllers/aiController.js - Infra config · 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 · Alternate backend entrypoint for the Bun/Elysia stack
backend-elysia/src/index.ts - Elysia realtime · Redis and socket configuration for the alternate service
backend-elysia/src/config/socket.ts - Elysia 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 · End-to-end coverage for auth, flashcards, quiz creation, and lobby gameplay
cypress/e2e/quiz/create_quiz.cy.js
Connections 35
- 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