# sahishy/studium-app architecture

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

- Interactive diagram: https://gitdiagram.com/sahishy/studium-app
- Repository: https://github.com/sahishy/studium-app

## Overview

#### 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`.

Main entry points: [`frontend/src/App.jsx`](https://github.com/sahishy/studium-app/blob/main/frontend/src/App.jsx) (App shell & routes), [`frontend/src/lib/firebase.jsx`](https://github.com/sahishy/studium-app/blob/main/frontend/src/lib/firebase.jsx) (Firebase client), [`firebase.json`](https://github.com/sahishy/studium-app/blob/main/firebase.json) (Auth, Firestore & Storage), [`backend/src/index.js`](https://github.com/sahishy/studium-app/blob/main/backend/src/index.js) (Backend entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_web_entry["Browser entry<br/>Vite bootstrap<br/>[main.jsx]"]
  node_app_shell["App shell &amp; routes<br/>React composition<br/>[App.jsx]"]
  node_route_guards["Route guards<br/>navigation boundary<br/>[PrivateRoute.jsx]"]
  node_firebase_client{{"Firebase client<br/>client SDK<br/>[firebase.jsx]"}}
  node_agenda["Agenda domain<br/>tasks context &amp; service<br/>[TasksContext.jsx]"]
  node_auth["Auth &amp; provisioning<br/>auth context &amp; service<br/>[AuthContext.jsx]"]
  node_courses["Courses domain<br/>courses context &amp; service<br/>[CoursesContext.jsx]"]
  node_profile["Profile &amp; XP<br/>stats and avatars"]
  node_socials["Friends &amp; circles<br/>circles context &amp; service<br/>[CirclesContext.jsx]"]
  node_shared_ui["Shared UI contexts<br/>modal, toast &amp; sidebar<br/>[ModalContext.jsx]"]
  node_client_services["Shared client services<br/>API, AI &amp; storage<br/>[apiService.jsx]"]
  node_multiplayer_client["Multiplayer session<br/>session context &amp; matchmaking"]
  node_game_dispatcher["Game dispatcher<br/>game renderer router<br/>[GameHandler.jsx]"]
  node_sat_client["SAT Classic client<br/>gameplay UI &amp; actions<br/>[SatClassicGame.jsx]"]
end

subgraph group_backend["Node backend"]
  node_backend_entry["Backend entry<br/>Node API &amp; triggers<br/>[index.js]"]
  node_admin_sdk{{"Firebase Admin<br/>trusted SDK<br/>[firebaseAdmin.js]"}}
  node_room_service["Room control plane<br/>routes, service &amp; repository<br/>[roomService.js]"]
  node_sat_server["SAT Classic authority<br/>game routes &amp; service"]
  node_questions["DSAT questions<br/>bundled game data"]
  node_room_triggers["Room event triggers<br/>backend triggers<br/>[roomTriggers.js]"]
end

subgraph group_firebase["Firebase platform"]
  node_firebase_data[("Auth, Firestore &amp; Storage<br/>managed data platform<br/>[firebase.json]")]
  node_emulator_data[("Emulator exports<br/>local development data")]
end

node_web_entry -->|"mounts"| node_app_shell
node_app_shell -->|"applies"| node_route_guards
node_app_shell -->|"provides session"| node_auth
node_app_shell -->|"renders feature"| node_agenda
node_app_shell -->|"renders feature"| node_courses
node_app_shell -->|"renders feature"| node_profile
node_app_shell -->|"renders feature"| node_socials
node_app_shell -->|"renders feature"| node_multiplayer_client
node_app_shell -->|"uses"| node_shared_ui
node_auth -->|"authenticates via"| node_firebase_client
node_agenda -->|"persists tasks via"| node_firebase_client
node_courses -->|"reads and writes via"| node_firebase_client
node_profile -->|"loads stats and avatars via"| node_firebase_client
node_socials -->|"manages circles via"| node_firebase_client
node_firebase_client -->|"client access"| node_firebase_data
node_multiplayer_client -->|"uses API"| node_client_services
node_multiplayer_client -->|"dispatches"| node_game_dispatcher
node_game_dispatcher -->|"renders"| node_sat_client
node_sat_client -->|"submits actions"| node_client_services
node_client_services -->|"HTTP requests"| node_backend_entry
node_backend_entry -->|"initializes"| node_admin_sdk
node_backend_entry -->|"routes multiplayer"| node_room_service
node_backend_entry -->|"routes SAT game"| node_sat_server
node_room_service -->|"persists rooms"| node_firebase_data
node_sat_server -->|"loads questions"| node_questions
node_sat_server -->|"updates match state"| node_firebase_data
node_room_triggers -.->|"reacts to room events"| node_firebase_data
node_admin_sdk -->|"trusted access"| node_firebase_data
node_emulator_data -.->|"local emulator state"| node_firebase_data

click node_web_entry "https://github.com/sahishy/studium-app/blob/main/frontend/src/main.jsx"
click node_app_shell "https://github.com/sahishy/studium-app/blob/main/frontend/src/App.jsx"
click node_route_guards "https://github.com/sahishy/studium-app/blob/main/frontend/src/routes/PrivateRoute.jsx"
click node_firebase_client "https://github.com/sahishy/studium-app/blob/main/frontend/src/lib/firebase.jsx"
click node_agenda "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/agenda/contexts/TasksContext.jsx"
click node_auth "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/auth/contexts/AuthContext.jsx"
click node_courses "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/courses/contexts/CoursesContext.jsx"
click node_profile "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/profile/contexts/UserStatsContext.jsx"
click node_socials "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/socials/contexts/CirclesContext.jsx"
click node_shared_ui "https://github.com/sahishy/studium-app/blob/main/frontend/src/shared/contexts/ModalContext.jsx"
click node_client_services "https://github.com/sahishy/studium-app/blob/main/frontend/src/shared/services/apiService.jsx"
click node_multiplayer_client "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/multiplayer/contexts/MultiplayerContext.jsx"
click node_game_dispatcher "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/multiplayer/games/GameHandler.jsx"
click node_sat_client "https://github.com/sahishy/studium-app/blob/main/frontend/src/features/multiplayer/games/sat-classic/SatClassicGame.jsx"
click node_backend_entry "https://github.com/sahishy/studium-app/blob/main/backend/src/index.js"
click node_admin_sdk "https://github.com/sahishy/studium-app/blob/main/backend/src/lib/firebaseAdmin.js"
click node_room_service "https://github.com/sahishy/studium-app/blob/main/backend/src/features/multiplayer/services/roomService.js"
click node_sat_server "https://github.com/sahishy/studium-app/blob/main/backend/src/features/multiplayer/games/sat-classic/services/satClassicService.js"
click node_questions "https://github.com/sahishy/studium-app/blob/main/backend/src/data/dsat_questions.json"
click node_room_triggers "https://github.com/sahishy/studium-app/blob/main/backend/src/features/multiplayer/triggers/roomTriggers.js"
click node_firebase_data "https://github.com/sahishy/studium-app/blob/main/firebase.json"

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_web_entry,node_app_shell,node_route_guards,node_firebase_client,node_agenda,node_auth,node_courses,node_profile,node_socials,node_shared_ui,node_client_services,node_multiplayer_client,node_game_dispatcher,node_sat_client toneBlue
class node_backend_entry,node_admin_sdk,node_room_service,node_sat_server,node_questions,node_room_triggers toneAmber
class node_firebase_data,node_emulator_data toneMint
```

## Components

### React frontend

- [Browser entry](https://github.com/sahishy/studium-app/blob/main/frontend/src/main.jsx): Vite bootstrap · `frontend/src/main.jsx`
- [App shell & routes](https://github.com/sahishy/studium-app/blob/main/frontend/src/App.jsx): React composition · `frontend/src/App.jsx`
- [Route guards](https://github.com/sahishy/studium-app/blob/main/frontend/src/routes/PrivateRoute.jsx): navigation boundary · Protects authenticated, maintenance, and multiplayer-session routes. · `frontend/src/routes/PrivateRoute.jsx`
- [Firebase client](https://github.com/sahishy/studium-app/blob/main/frontend/src/lib/firebase.jsx): client SDK · `frontend/src/lib/firebase.jsx`
- [Agenda domain](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/agenda/contexts/TasksContext.jsx): tasks context & service · Supports personal and circle task lifecycle and agenda views. · `frontend/src/features/agenda/contexts/TasksContext.jsx`
- [Auth & provisioning](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/auth/contexts/AuthContext.jsx): auth context & service · `frontend/src/features/auth/contexts/AuthContext.jsx`
- [Courses domain](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/courses/contexts/CoursesContext.jsx): courses context & service · Catalog, enrollment, teachers, and reviews. · `frontend/src/features/courses/contexts/CoursesContext.jsx`
- [Profile & XP](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/profile/contexts/UserStatsContext.jsx): stats and avatars · `frontend/src/features/profile/contexts/UserStatsContext.jsx`
- [Friends & circles](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/socials/contexts/CirclesContext.jsx): circles context & service · Includes shared circle agendas. · `frontend/src/features/socials/contexts/CirclesContext.jsx`
- [Shared UI contexts](https://github.com/sahishy/studium-app/blob/main/frontend/src/shared/contexts/ModalContext.jsx): modal, toast & sidebar · `frontend/src/shared/contexts/ModalContext.jsx`
- [Shared client services](https://github.com/sahishy/studium-app/blob/main/frontend/src/shared/services/apiService.jsx): API, AI & storage · `frontend/src/shared/services/apiService.jsx`
- [Multiplayer session](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/multiplayer/contexts/MultiplayerContext.jsx): session context & matchmaking · Starts matchmaking and observes room and chat state. · `frontend/src/features/multiplayer/contexts/MultiplayerContext.jsx`
- [Game dispatcher](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/multiplayer/games/GameHandler.jsx): game renderer router · `frontend/src/features/multiplayer/games/GameHandler.jsx`
- [SAT Classic client](https://github.com/sahishy/studium-app/blob/main/frontend/src/features/multiplayer/games/sat-classic/SatClassicGame.jsx): gameplay UI & actions · `frontend/src/features/multiplayer/games/sat-classic/SatClassicGame.jsx`

### Node backend

- [Backend entry](https://github.com/sahishy/studium-app/blob/main/backend/src/index.js): Node API & triggers · `backend/src/index.js`
- [Firebase Admin](https://github.com/sahishy/studium-app/blob/main/backend/src/lib/firebaseAdmin.js): trusted SDK · `backend/src/lib/firebaseAdmin.js`
- [Room control plane](https://github.com/sahishy/studium-app/blob/main/backend/src/features/multiplayer/services/roomService.js): routes, service & repository · Authoritative room lifecycle and persistence operations. · `backend/src/features/multiplayer/services/roomService.js`
- [SAT Classic authority](https://github.com/sahishy/studium-app/blob/main/backend/src/features/multiplayer/games/sat-classic/services/satClassicService.js): game routes & service · Validates game actions and drives match state. · `backend/src/features/multiplayer/games/sat-classic/services/satClassicService.js`
- [DSAT questions](https://github.com/sahishy/studium-app/blob/main/backend/src/data/dsat_questions.json): bundled game data · `backend/src/data/dsat_questions.json`
- [Room event triggers](https://github.com/sahishy/studium-app/blob/main/backend/src/features/multiplayer/triggers/roomTriggers.js): backend triggers · `backend/src/features/multiplayer/triggers/roomTriggers.js`

### Firebase platform

- [Auth, Firestore & Storage](https://github.com/sahishy/studium-app/blob/main/firebase.json): managed data platform · Security boundaries are defined by Firebase and Firestore/Storage rules. · `firebase.json`
- **Emulator exports**: local development data

## Connections

- Browser entry → App shell & routes: mounts
- App shell & routes → Route guards: applies
- App shell & routes → Auth & provisioning: provides session
- App shell & routes → Agenda domain: renders feature
- App shell & routes → Courses domain: renders feature
- App shell & routes → Profile & XP: renders feature
- App shell & routes → Friends & circles: renders feature
- App shell & routes → Multiplayer session: renders feature
- App shell & routes → Shared UI contexts: uses
- Auth & provisioning → Firebase client: authenticates via
- Agenda domain → Firebase client: persists tasks via
- Courses domain → Firebase client: reads and writes via
- Profile & XP → Firebase client: loads stats and avatars via
- Friends & circles → Firebase client: manages circles via
- Firebase client → Auth, Firestore & Storage: client access
- Multiplayer session → Shared client services: uses API
- Multiplayer session → Game dispatcher: dispatches
- Game dispatcher → SAT Classic client: renders
- SAT Classic client → Shared client services: submits actions
- Shared client services → Backend entry: HTTP requests
- Backend entry → Firebase Admin: initializes
- Backend entry → Room control plane: routes multiplayer
- Backend entry → SAT Classic authority: routes SAT game
- Room control plane → Auth, Firestore & Storage: persists rooms
- SAT Classic authority → DSAT questions: loads questions
- SAT Classic authority → Auth, Firestore & Storage: updates match state
- Room event triggers → Auth, Firestore & Storage: reacts to room events
- Firebase Admin → Auth, Firestore & Storage: trusted access
- Emulator exports → Auth, Firestore & Storage: local emulator state