How abhijith2005binu/spandan works
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: index.js API server · routes Routes · App.jsx SPA shell · services Services
Components 16
Frontend
React/Vite SPA for teachers and students
- SPA shell · Main client application composition and routing
frontend/src/App.jsx - Pages · Auth, dashboards, room, profile, and reset screens
frontend/src/pages - Components · Reusable dialogs, navigation, and approval overlays
frontend/src/components - Stores · Zustand auth, room, socket, and theme state
frontend/src/stores - API layer · REST and transcription service clients
frontend/src/lib/api.js - Client services · Question and transcript flow helpers
frontend/src/services
Backend
Express API, persistence, and transcription runtime
- API server · Backend bootstrap and server wiring
backend/src/index.js - Config · Environment-driven backend configuration
backend/src/config.js - Routes · Auth, rooms, questions, responses, transcripts, and transcription endpoints
backend/src/routes - Services · Auth, room, question, email, and password workflows
backend/src/services - Models · User, room, membership, question, response, transcript, and reset token data
backend/src/models - Middleware · Authentication and validation at the API boundary
backend/src/middleware - Transcription runtime · Dedicated server and route path for audio-to-text processing
backend/src/transcriptionServer.js
Infra
Deployment and startup surface
- server.js · Root startup/hosting entrypoint
server.js - CI/CD · GitHub Actions for testing and deployment
.github/workflows - Nginx config · Production delivery and proxy configuration
nginx/spandan.fun.conf
Connections 22
- 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