How ayhanarashtasin/cuet-sciblitz-ai-hackathon works
1. Top-level shape
- This is a two-package monorepo: client/ is a React/Vite single-page app, and server/ is an Express/MongoDB API.
- The frontend talks to the backend through /api/* JSON endpoints, plus Socket.io for realtime features.
- In production, the backend can also serve the built SPA from client/dist, with SPA fallback for browser refreshes.
2. Frontend boundary
- The client is organized by product area rather than by technical layer: landing, dashboard, question bank, practice, battle, books/reader, IELTS, forum, live classes, mentorship, settings, and admin.
- App.jsx and route modules handle page-level composition; most pages are thin orchestrators over reusable UI components and service wrappers.
- Shared concerns like auth token storage, language selection, paywall handling, and socket hooks live in src/hooks, src/context, and src/utils.
3. Backend boundary
- The server uses a conventional controller → service → model structure.
- Route files mount feature APIs under /api; controllers handle request/response shaping, services contain domain logic and third-party integrations, and Mongoose models define persistence.
- Cross-cutting middleware handles auth, admin access, plan/quota enforcement, uploads, rate limiting, and error normalization.
4. Authentication and role model
- Authentication is centered on Google OAuth via Passport and JWT-based session/API access.
- The user record carries two important role dimensions: academic role (student, tutor, teacher) and platform role (user, moderator, admin).
- Admin access is separately gated in both the frontend /admin route tree and backend /api/admin routes, with audit logging for privileged actions.
5. Subscription and quota system
- Plans are defined server-side as the source of truth, including free, Pro, Pro+, and trial behavior.
- Usage limits are enforced on the backend, not trusted from the client; plan resolution is done dynamically so expired plans degrade to free without a migration job.
- This affects multiple flows: question-bank exams, mock tests, battle rooms, AI actions, and reading-library access.
6. Core learning flows
- Question bank, mock tests, contests, and practice history form one academic testing subsystem.
- Questions are teacher-authored, then reused across browsing, contest building, mock-test generation, and practice attempts.
- Practice and mock-test results are persisted as attempts/snapshots so later edits to source questions do not change old results.
7. Realtime battle and live learning
- The battle arena uses Socket.io to keep room state synchronized across players, timers, answers, and scoring.
- Live classes use a separate LiveKit integration for audio/video sessions, while the backend manages session lifecycle, attendance, and token issuance.
- Both subsystems depend on backend validation and role checks before a room/session can be created or joined.
8. AI and evaluation subsystem
- AI features are centralized behind dedicated service modules wrapping Groq/OpenAI-compatible APIs.
- The backend exposes chat, written evaluation, question help, study-routine generation, battle coaching, and book chat endpoints.
- AI usage is metered by quota and rate limit middleware, making AI a controlled backend capability rather than a client-side feature.
9. Reading library and RAG pipeline
- The reading system is a distinct content pipeline: teachers upload PDFs, the backend extracts and chunks content, and the reader fetches chapter PDFs and derived knowledge.
- Book intelligence features—summaries, mind maps, topic trees, and contextual chat—are powered by a retrieval layer (bookRagService, embeddings, chunk/page records).
- Storage is split between MongoDB for metadata/derived content and Firebase Storage for the actual PDF assets.
10. Forum and community layer
- The forum is a separate realtime community subsystem with posts, nested comments, reactions, bookmarks, search, notifications, and moderation reports.
- Rich text is sanitized server-side, and forum images use Cloudinary when configured with a local upload fallback otherwise.
- Socket.io is also used here for community/notification-style realtime updates.
11. Teaching and content approval
- Teacher-facing authoring exists for questions, books, IELTS sets, contests, and live classes.
- Reviewable content follows a pending → approved/rejected workflow, with admin review state stored in the database.
- Students only see approved content, while teachers can see their own pending submissions; this creates a clear publish/review boundary.
12. Admin console as a separate operational surface
- The admin UI mirrors backend modules for users, teachers, questions, academic taxonomy, books, IELTS content, notices, waitlist, audit logs, and moderation.
- Admin pages are largely management views over the same domain models used by the student/teacher experience.
- This keeps operational tooling inside the same monorepo, but clearly separated by route tree, middleware, and service layer.
13. Persistence and external services
- MongoDB is the main system of record for users, content, attempts, routines, sessions, notifications, payments, reports, and audit data.
- External services are used where they materially shape architecture: Google OAuth for login, SSLCommerz for payments, Firebase Storage for book PDFs, Cloudinary for forum media, LiveKit for live classes, and Groq/LLM APIs for AI.
- Local disk is only a fallback path for uploads and temporary files.
14. Operational safeguards
- The backend applies request throttling, AI-specific limits, payment protection, and webhook-style raw-body handling where required.
- SPA fallback is intentionally placed after /api and /uploads routes so frontend refreshes work without breaking API resolution.
- The overall architecture is therefore a modular monolith: one frontend app, one Node API, multiple feature domains, and several external integrations connected through clear server-side boundaries.
Main entry points: controllers Controllers · services Domain services · routes Route mounts · App.jsx App routes
Components 21
Client app
React/Vite SPA organized by product area and shared UX concerns.
- App routes · Top-level React composition and route wiring for the SPA and admin surface.
client/src/App.jsx - Product areas · Student-facing and teacher-facing page modules for dashboard, learning, forum, reading, live class, and settings.
client/src/pages - Shared UI · Reusable UI for landing, layout, forum, reader, live class, study, and settings experiences.
client/src/components - Client state · Auth storage, language selection, paywall logic, socket hooks, and other shared client behavior.
client/src/hooks - API clients · HTTP clients for AI, forum, books, practice, contests, payments, live classes, and study routines.
client/src/services - Admin console · Separate admin route tree, layout, pages, and API wrapper for operational management.
client/src/admin
Server API
Express/MongoDB backend with controllers, services, models, middleware, and sockets.
- Route mounts · Feature route files that mount the public API and admin API under /api.
server/routes - Auth stack · Google OAuth and JWT session/API access with role-aware authorization.
server/config/passport.js - Policy layer · Auth, admin gating, plan/quota enforcement, uploads, rate limiting, and error normalization.
server/middleware - Controllers · Request/response shaping for learning, community, AI, payments, admin, and live-class flows.
server/controllers - Domain services · Core domain logic, integrations, RAG, AI wrappers, settlement, notifications, and moderation services.
server/services - Data models · MongoDB persistence for users, content, attempts, sessions, payments, moderation, and audit data.
server/models - Realtime socket · Socket layer for battles, forum notifications, and synchronized realtime updates.
server/socket/index.js - Admin services · Management services for users, teachers, questions, books, IELTS, moderation, payments, and settings.
server/services/admin - AI services · Centralized Groq/OpenAI-compatible services for chat, evaluation, coaching, and book intelligence.
server/services/groqService.js - Book RAG · PDF extraction, chunking, embeddings, derived knowledge, and contextual reader chat.
server/services/bookRagService.js - Live classes · LiveKit-backed session lifecycle, token issuance, and attendance management.
server/controllers/liveClassController.js - Battle arena · Socket-synchronized battle rooms, timers, answers, and scoring.
server/controllers/battleController.js - Forum core · Posts, comments, reactions, bookmarks, search, reports, moderation, and sanitization.
server/controllers/postController.js - Learning content · Question bank, mock tests, contests, practice attempts, IELTS, study routines, and teacher-authored content.
server/controllers/questionController.js
Other components
- External systems · MongoDB, Google OAuth, Firebase Storage, Cloudinary, LiveKit, Groq/LLMs, and payment providers.
Connections 19
- App routes → Product areas: renders · Route composition assembles product-area pages and admin entry points.
- App routes → Shared UI: uses · Pages reuse shared layout, forum, reader, and landing components.
- Product areas → API clients: calls · Feature pages fetch and mutate data through typed service wrappers.
- Shared UI → Client state: depends on · Shared UI reads auth, language, paywall, and socket state.
- API clients → Route mounts: requests · Browser and admin API clients hit the backend JSON endpoints.
- Admin console → Admin services: manages · Admin UI mirrors backend management domains.
- Route mounts → Policy layer: guards with · Routes are protected by auth, plan, upload, rate-limit, and admin middleware.
- Route mounts → Controllers: dispatches to · Mounted routes hand off HTTP handling to controllers.
- Controllers → Domain services: delegates to · Controllers keep orchestration thin and push logic into services.
- Domain services → Data models: persists via · Services read and write MongoDB documents through Mongoose models.
- Controllers → Realtime socket: emits / joins · Realtime features coordinate battle and community updates over sockets.
- Domain services → AI services: wraps · AI endpoints are centralized behind reusable model-integration services.
- Domain services → Book RAG: retrieves · Reading features use embeddings, chunks, and derived book knowledge.
- Controllers → Live classes: orchestrates · Live class endpoints manage sessions, attendance, and token flow.
- Controllers → Battle arena: coordinates · Battle controllers manage room creation and game flow.
- Controllers → Forum core: serves · Forum endpoints support posts, comments, reactions, search, and moderation.
- Controllers → Learning content: serves · Academic feature controllers cover question bank, contests, practice, IELTS, and study routines.
- Admin services → Data models: administers · Operational modules act on the same underlying domain records.
- Domain services → External systems: integrates with · The backend depends on MongoDB and external providers for auth, storage, video, payments, and AI.