# abhijith2005binu/spandan architecture

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

- Interactive diagram: https://gitdiagram.com/abhijith2005binu/spandan
- Repository: https://github.com/abhijith2005binu/spandan

## Overview

1. **Overall shape**
   - Spandan is a monorepo with three main runtime surfaces: a React/Vite frontend, an Express/Mongoose backend API, and a transcription subsystem powered by Whisper/Xenova Transformers.
   - The core product flow is classroom polling: teachers create rooms and questions, students join and respond, and both sides see live updates.

2. **Frontend application**
   - The `frontend/` package is the user-facing SPA built with React, Vite, TailwindCSS, React Router, Zustand, and Socket.IO client.
   - `src/pages/` holds the main route-level screens: auth, dashboards, room creation/joining, room detail/history/results, profile, and password reset.
   - `src/components/` contains reusable UI and workflow dialogs such as question approval popups, room settings, sidebar/navigation, and theme toggle.

3. **Frontend state and API boundary**
   - Zustand stores in `src/stores/` separate UI/session concerns: `authStore`, `roomStore`, `socketStore`, and `themeStore`.
   - `src/lib/api.js` and the service modules in `src/services/` act as the boundary to backend REST endpoints and transcription/question flows.
   - This is where the SPA exchanges JWT-authenticated requests, subscribes to live socket events, and renders live polling results.

4. **Backend application**
   - The `backend/` package is an Express API organized around routes, services, models, and middleware.
   - `src/index.js` is the API entry point; `src/config.js` centralizes environment-driven configuration.
   - `src/middleware/` includes authentication and validation, indicating that request authorization and payload checking are enforced at the API boundary.

5. **Domain model and persistence**
   - MongoDB via Mongoose is the persistence layer.
   - The main schema set shows the domain boundaries clearly: `User`, `Room`, `RoomMember`, `Question`, `Response`, `Transcript`, and `PasswordResetToken`.
   - These models support identity, room membership, question lifecycle, student responses, transcript storage, and password recovery.

6. **Backend route groups**
   - Routes are split by concern: `auth`, `rooms`, `questions`, `responses`, `transcripts`, and `transcription`.
   - This suggests a service-oriented API shape where each route module exposes a focused domain surface rather than a single large controller.
   - The `auth` routes handle login/reset flows, while room/question/response routes support the live polling session lifecycle.

7. **Business logic services**
   - The `services/` directory contains the main orchestration layer: `authService`, `emailService`, `passwordService`, `questionService`, and `roomService`.
   - This is the layer where API requests are translated into domain operations such as user authentication, room creation/membership, question generation/approval, and password reset workflows.
   - `emailService` implies asynchronous user notifications for auth or reset-related events.

8. **Real-time interaction**
   - Socket.IO is a major architectural boundary in the product, used to keep room participants synchronized in real time.
   - Live data likely flows from the backend to teacher and student clients for response counts, room activity, and question state transitions.
   - The presence of both room and response routes alongside Socket.IO implies a hybrid model: REST for state changes and sockets for live updates.

9. **Transcription pipeline**
   - `backend/src/transcriptionServer.js` and `backend/src/routes/transcription.js` indicate a dedicated transcription path separate from normal CRUD routes.
   - The README identifies Whisper-powered transcription via Xenova Transformers, so audio input is converted into text for question generation.
   - This subsystem feeds into question creation workflows, especially for teacher-facing “generate questions from text/transcript” interactions.

10. **Security and auth flow**
    - Authentication is JWT-based with bcryptjs for password handling, enforced by `backend/src/middleware/auth.js`.
    - The frontend includes protected routing and auth loading components, so unauthenticated users are blocked before entering teacher/student dashboards.
    - Role separation is important: teachers manage rooms and approvals; students join rooms and submit answers.

11. **Deployment and edge/runtime**
    - The repo includes GitHub Actions workflows for CI and deployment, plus an `nginx/spandan.fun.conf` config, which suggests production deployment behind Nginx.
    - A root-level `server.js` likely coordinates runtime startup or hosting behavior outside the backend package.
    - The `html/` and `nginx/` folders indicate there is also static hosting or reverse-proxy configuration in the delivery path.

12. **Quality and verification**
    - Both frontend and backend have Jest test suites, covering auth middleware/routes, room routes, password service, question correctness, and UI/store behavior.
    - This suggests the system is tested at both domain-service level and component/store level, with a focus on auth and room workflow correctness.

Main entry points: [`backend/src/index.js`](https://github.com/abhijith2005binu/spandan/blob/main/backend/src/index.js) (API server), [`backend/src/routes`](https://github.com/abhijith2005binu/spandan/tree/main/backend/src/routes) (Routes), [`frontend/src/App.jsx`](https://github.com/abhijith2005binu/spandan/blob/main/frontend/src/App.jsx) (SPA shell), [`backend/src/services`](https://github.com/abhijith2005binu/spandan/tree/main/backend/src/services) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>React app<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>route screens"]
  node_frontend_components["Components<br/>ui widgets"]
  node_frontend_state["Stores<br/>client state"]
  node_frontend_api["API layer<br/>client boundary<br/>[api.js]"]
  node_frontend_transcript_services["Client services<br/>frontend services"]
end

subgraph group_backend["Backend"]
  node_backend_entry["API server<br/>Express entry<br/>[index.js]"]
  node_backend_config["Config<br/>[config.js]"]
  node_backend_routes["Routes"]
  node_backend_services["Services<br/>domain orchestration"]
  node_backend_models[("Models<br/>mongoose schemas")]
  node_backend_middleware["Middleware<br/>request guards"]
  node_backend_transcription["Transcription runtime<br/>whisper service"]
end

subgraph group_infra["Infra"]
  node_server_js["server.js<br/>runtime entry<br/>[server.js]"]
  node_ci_cd["CI/CD<br/>automation<br/>[workflows]"]
  node_nginx_conf["Nginx config<br/>reverse proxy<br/>[spandan.fun.conf]"]
end

node_server_js -->|"starts"| node_backend_entry
node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_app -->|"uses"| node_frontend_state
node_frontend_state -->|"calls"| node_frontend_api
node_frontend_pages -->|"fetches"| node_frontend_api
node_frontend_pages -->|"invokes"| node_frontend_transcript_services
node_frontend_api -->|"requests"| node_backend_routes
node_frontend_transcript_services -->|"uploads"| node_backend_transcription
node_backend_entry -->|"loads"| node_backend_config
node_backend_entry -->|"mounts"| node_backend_middleware
node_backend_entry -->|"serves"| node_backend_routes
node_backend_entry -->|"orchestrates"| node_backend_services
node_backend_entry -->|"persists"| node_backend_models
node_backend_routes -->|"delegates"| node_backend_services
node_backend_services -->|"reads/writes"| node_backend_models
node_backend_routes -->|"exposes"| node_backend_transcription
node_backend_transcription -->|"feeds"| node_backend_services
node_backend_middleware -->|"protects"| node_backend_routes
node_ci_cd -.->|"tests/deploys"| node_backend_entry
node_ci_cd -.->|"tests/deploys"| node_frontend_app
node_nginx_conf -.->|"proxies"| node_server_js

click node_server_js "https://github.com/abhijith2005binu/spandan/blob/main/server.js"
click node_frontend_app "https://github.com/abhijith2005binu/spandan/blob/main/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/pages"
click node_frontend_components "https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/components"
click node_frontend_state "https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/stores"
click node_frontend_api "https://github.com/abhijith2005binu/spandan/blob/main/frontend/src/lib/api.js"
click node_frontend_transcript_services "https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/services"
click node_backend_entry "https://github.com/abhijith2005binu/spandan/blob/main/backend/src/index.js"
click node_backend_config "https://github.com/abhijith2005binu/spandan/blob/main/backend/src/config.js"
click node_backend_routes "https://github.com/abhijith2005binu/spandan/tree/main/backend/src/routes"
click node_backend_services "https://github.com/abhijith2005binu/spandan/tree/main/backend/src/services"
click node_backend_models "https://github.com/abhijith2005binu/spandan/tree/main/backend/src/models"
click node_backend_middleware "https://github.com/abhijith2005binu/spandan/tree/main/backend/src/middleware"
click node_backend_transcription "https://github.com/abhijith2005binu/spandan/blob/main/backend/src/transcriptionServer.js"
click node_ci_cd "https://github.com/abhijith2005binu/spandan/blob/main/.github/workflows"
click node_nginx_conf "https://github.com/abhijith2005binu/spandan/blob/main/nginx/spandan.fun.conf"

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_frontend_app,node_frontend_pages,node_frontend_components,node_frontend_state,node_frontend_api,node_frontend_transcript_services toneBlue
class node_backend_entry,node_backend_config,node_backend_routes,node_backend_services,node_backend_models,node_backend_middleware,node_backend_transcription toneAmber
class node_server_js,node_ci_cd,node_nginx_conf toneMint
```

## Components

### Frontend

React/Vite SPA for teachers and students

- [SPA shell](https://github.com/abhijith2005binu/spandan/blob/main/frontend/src/App.jsx): React app · Main client application composition and routing · `frontend/src/App.jsx`
- [Pages](https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/pages): route screens · Auth, dashboards, room, profile, and reset screens · `frontend/src/pages`
- [Components](https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/components): ui widgets · Reusable dialogs, navigation, and approval overlays · `frontend/src/components`
- [Stores](https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/stores): client state · Zustand auth, room, socket, and theme state · `frontend/src/stores`
- [API layer](https://github.com/abhijith2005binu/spandan/blob/main/frontend/src/lib/api.js): client boundary · REST and transcription service clients · `frontend/src/lib/api.js`
- [Client services](https://github.com/abhijith2005binu/spandan/tree/main/frontend/src/services): frontend services · Question and transcript flow helpers · `frontend/src/services`

### Backend

Express API, persistence, and transcription runtime

- [API server](https://github.com/abhijith2005binu/spandan/blob/main/backend/src/index.js): Express entry · Backend bootstrap and server wiring · `backend/src/index.js`
- [Config](https://github.com/abhijith2005binu/spandan/blob/main/backend/src/config.js): runtime config · Environment-driven backend configuration · `backend/src/config.js`
- [Routes](https://github.com/abhijith2005binu/spandan/tree/main/backend/src/routes): HTTP routes · Auth, rooms, questions, responses, transcripts, and transcription endpoints · `backend/src/routes`
- [Services](https://github.com/abhijith2005binu/spandan/tree/main/backend/src/services): domain orchestration · Auth, room, question, email, and password workflows · `backend/src/services`
- [Models](https://github.com/abhijith2005binu/spandan/tree/main/backend/src/models): mongoose schemas · User, room, membership, question, response, transcript, and reset token data · `backend/src/models`
- [Middleware](https://github.com/abhijith2005binu/spandan/tree/main/backend/src/middleware): request guards · Authentication and validation at the API boundary · `backend/src/middleware`
- [Transcription runtime](https://github.com/abhijith2005binu/spandan/blob/main/backend/src/transcriptionServer.js): whisper service · Dedicated server and route path for audio-to-text processing · `backend/src/transcriptionServer.js`

### Infra

Deployment and startup surface

- [server.js](https://github.com/abhijith2005binu/spandan/blob/main/server.js): runtime entry · Root startup/hosting entrypoint · `server.js`
- [CI/CD](https://github.com/abhijith2005binu/spandan/blob/main/.github/workflows): automation · GitHub Actions for testing and deployment · `.github/workflows`
- [Nginx config](https://github.com/abhijith2005binu/spandan/blob/main/nginx/spandan.fun.conf): reverse proxy · Production delivery and proxy configuration · `nginx/spandan.fun.conf`

## Connections

- server.js → API server: starts · Root runtime launches the backend application
- SPA shell → Pages: renders · SPA routes into screen-level pages
- SPA shell → Components: composes · Pages share reusable UI and dialogs
- SPA shell → Stores: uses · Client state drives auth, room, socket, and theme behavior
- Stores → API layer: calls · Stores coordinate authenticated API interactions
- Pages → API layer: fetches · Screens read and mutate server state
- Pages → Client services: invokes · Question generation and transcript workflows
- API layer → Routes: requests · SPA talks to REST endpoints and live session routes
- Client services → Transcription runtime: uploads · Client transcription flow reaches dedicated text/audio processing
- API server → Config: loads · Server bootstraps from environment config
- API server → Middleware: mounts · API requests are guarded by middleware
- API server → Routes: serves · Main HTTP surface is composed from route modules
- API server → Services: orchestrates · Route handlers delegate to domain services
- API server → Models: persists · Services and routes operate through Mongoose models
- Routes → Services: delegates · Route handlers call into business logic
- Services → Models: reads/writes · Domain workflows persist users, rooms, questions, and responses
- Routes → Transcription runtime: exposes · Dedicated transcription route is part of the API surface
- Transcription runtime → Services: feeds · Transcription output supports question and room workflows
- Middleware → Routes: protects · Auth and validation gate API access
- CI/CD → API server: tests/deploys · Workflow coverage includes backend verification and delivery
- CI/CD → SPA shell: tests/deploys · Workflow coverage includes frontend verification and delivery
- Nginx config → server.js: proxies · Production traffic is routed through Nginx to the app runtime