sahishy/studium-app

Purpose and Topology

This is a Firebase-backed student platform with a React/Vite frontend and Node backend. It combines personal/circle agendas, courses and reviews, profiles/social graphs, and real-time multiplayer SAT-style games. Firebase configuration and security boundaries are defined in firebase.json, firestore.rules, and storage.rules.

Application Entry Points

The browser application starts at frontend/src/main.jsx, composes routing and application UI in frontend/src/App.jsx, and initializes Firebase client access in frontend/src/lib/firebase.jsx. The backend entry is backend/src/index.js; it uses Admin SDK initialization from backend/src/lib/firebaseAdmin.js, exposing server-side multiplayer/game endpoints and triggers.

Frontend Feature Architecture

Feature folders own pages, state contexts, UI, and client Firebase/service adapters. Core user-facing domains include:

• Agenda task lifecycle and board/calendar/list views: frontend/src/features/agenda/contexts/TasksContext.jsx, frontend/src/features/agenda/services/taskService.jsx, frontend/src/features/agenda/pages/Agenda.jsx.

• Authentication and user provisioning: frontend/src/features/auth/contexts/AuthContext.jsx, frontend/src/features/auth/services/userService.jsx.

• Course catalog, enrollment, teachers, and reviews: frontend/src/features/courses/contexts/CoursesContext.jsx, frontend/src/features/courses/services/courseService.jsx, frontend/src/features/courses/pages/Courses.jsx.

• Profiles, stats/XP, and avatars: frontend/src/features/profile/contexts/UserStatsContext.jsx, frontend/src/features/profile/services/statsService.jsx, frontend/src/features/profile/services/avatarService.jsx.

• Friends and circles, including shared circle agendas: frontend/src/features/socials/contexts/CirclesContext.jsx, frontend/src/features/socials/services/circleService.jsx, frontend/src/features/socials/pages/CircleAgenda.jsx.

Route, Session, and UI Boundaries

Route guards and index redirects centralize navigation constraints, notably authenticated access and multiplayer-session routing: frontend/src/routes/PrivateRoute.jsx, frontend/src/routes/MultiplayerSessionRedirect.jsx, frontend/src/routes/MaintenanceRoute.jsx. Shared modal/toast contexts and reusable components provide cross-feature interaction primitives: frontend/src/shared/contexts/ModalContext.jsx, frontend/src/shared/contexts/ToastContext.jsx, frontend/src/shared/components/ui/Sidebar.jsx.

Multiplayer Control Plane

Multiplayer is split between a frontend session context/game renderer and authoritative backend services. The client starts matchmaking, joins rooms, observes chat/session state, and dispatches games through frontend/src/features/multiplayer/contexts/MultiplayerContext.jsx, frontend/src/features/multiplayer/services/matchmakingService.jsx, and frontend/src/features/multiplayer/games/GameHandler.jsx. The backend routes requests through controllers/services into persistence repositories: backend/src/features/multiplayer/routes/multiplayerRoutes.js, backend/src/features/multiplayer/services/roomService.js, backend/src/features/multiplayer/repositories/roomRepository.js.

SAT Classic Game Flow

SAT Classic is a paired client/server game module. Client gameplay renders questions, answers, health, and match end state in frontend/src/features/multiplayer/games/sat-classic/SatClassicGame.jsx, submitting actions through frontend/src/features/multiplayer/games/sat-classic/services/satClassicGameService.jsx. Backend game routes invoke controller/service logic, using the bundled question source backend/src/data/dsat_questions.json: backend/src/features/multiplayer/games/sat-classic/routes/satClassicRoutes.js, backend/src/features/multiplayer/games/sat-classic/services/satClassicService.js.

Data, Infrastructure, and External Boundaries

Firebase is the primary platform: client-side Auth/Firestore/Storage access is mediated by feature services; backend Admin SDK code performs trusted mutations and room-event triggers (backend/src/features/multiplayer/triggers/roomTriggers.js). Local Firebase Emulator exports exist under emulator-data/, supporting development through the root emulator command. The frontend also has shared API, AI, storage, cache, and content-censor service boundaries: frontend/src/shared/services/apiService.jsx, frontend/src/shared/services/aiService.jsx, frontend/src/shared/services/storageService.jsx.