saidurrahmanmisket/ai-powered-quiz-battle-frontend

1. Overall shape

This repository is a client-only React SPA for a live multiplayer trivia game. It does not contain the game server; instead, it acts as the browser-facing presentation and interaction layer for a separate backend that exposes REST APIs and STOMP/WebSocket channels.

2. App bootstrap

src/main.jsx is the entry point that mounts the app into index.html. src/App.jsx is the top-level composition layer: it likely defines the route map, common layout, and which pages are public vs protected.

3. Page-level boundaries

The app is split into feature pages under src/pages/:

• LoginPage.jsx / RegisterPage.jsx handle authentication entry.

• DashboardPage.jsx is the authenticated landing area.

• LobbyPage.jsx covers room discovery, joining, and matchmaking.

• GamePage.jsx is the live trivia runtime.

• LeaderboardPage.jsx and ClansPage.jsx are social/competitive views.

This separation is useful for diagramming distinct user journeys.

4. Authentication subsystem

src/context/AuthContext.jsx is the main state boundary for user identity and session state. It centralizes login/logout/guest handling and exposes auth state to the rest of the app. src/components/ProtectedRoute.jsx enforces access control around authenticated routes, keeping unauthenticated users out of game and dashboard flows.

5. REST API boundary

src/api/client.js is the HTTP integration layer. It wraps Axios and is the place where token-aware request configuration and backend endpoint calls are concentrated. In the architecture diagram, this is the synchronous request path between UI actions and backend persistence/state retrieval.

6. Realtime game boundary

src/hooks/useGameSocket.js encapsulates the live connection to the game backend via SockJS + STOMP. This is the critical low-latency subsystem used for lobby updates, question state, timers, reactions/emotes, and in-game events. It separates connection lifecycle from page components so the live transport can be reused across screens.

7. Game data flow

The main live flow is: user enters lobby → socket subscribes/updates room state → game starts → GamePage consumes streamed events for timer, answers, score changes, and recovery state. The README indicates state recovery after refresh/disconnect, so the socket layer likely rehydrates from server state instead of relying only on in-memory React state.

8. Shared UI layer

src/components/Navbar.jsx and src/components/AnimatedBackground.jsx are cross-page shell components. The navbar provides global navigation and status display, while the animated background is a decorative layer used to keep the app visually consistent across screens.

9. Rendering and interaction model

The UI is mostly driven by page-local React state plus context/hook-based shared state. The design emphasizes smooth transitions and live feedback: timers, lobby polling, reactions, and power-ups are all interactive, stateful UI behaviors rather than static screens.

10. Styling and presentation

src/index.css and src/App.css provide the app’s global styling and visual system. The README describes a dark, glassmorphism-style interface with animation effects, and the repo structure suggests styling is handled through a mix of global CSS and utility-driven classes rather than a complex component library.

11. External dependencies that matter architecturally

The key external runtime dependencies are React/Vite for the SPA shell, Axios for REST calls, and SockJS/STOMP for realtime transport. The app also depends on browser storage for persisted auth/session tokens, which means session continuity is client-managed between page loads.

12. Important diagram boundaries

For an architecture diagram, the main boundaries are:

• Browser SPA shell

• Auth/session context

• REST API client

• Realtime WebSocket/STOMP channel

• Feature pages for lobby/game/social views

• Shared layout/visual components

That set captures the main control flow without over-modeling the UI details.