# ayhanarashtasin/cuet-sciblitz-ai-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon
- Repository: https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon

## Overview

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: [`server/controllers`](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/controllers) (Controllers), [`server/services`](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/services) (Domain services), [`server/routes`](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/routes) (Route mounts), [`client/src/App.jsx`](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/client/src/App.jsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_client_app["App routes<br/>spa shell<br/>[App.jsx]"]
  node_client_areas["Product areas<br/>feature pages"]
  node_client_shared["Shared UI<br/>components"]
  node_client_state["Client state<br/>hooks/context/utils"]
  node_client_api["API clients<br/>service wrappers"]
  node_client_admin["Admin console<br/>admin UI"]
end

subgraph group_server["Server API"]
  node_server_routes["Route mounts<br/>express routes"]
  node_server_auth["Auth stack<br/>passport+jwt<br/>[passport.js]"]
  node_server_middleware["Policy layer<br/>middleware"]
  node_server_controllers["Controllers<br/>request handlers"]
  node_server_services["Domain services<br/>business logic"]
  node_server_models[("Data models<br/>mongoose models")]
  node_server_socket(("Realtime socket<br/>socket.io<br/>[index.js]"))
  node_server_admin["Admin services<br/>admin domain"]
  node_server_ai{{"AI services<br/>llm integration<br/>[groqService.js]"}}
  node_server_book_rag["Book RAG<br/>retrieval pipeline<br/>[bookRagService.js]"]
  node_server_live["Live classes<br/>live video"]
  node_server_battle["Battle arena<br/>realtime game"]
  node_server_forum["Forum core<br/>community domain<br/>[postController.js]"]
  node_server_content["Learning content<br/>academic domain"]
end

node_server_persistence{{"External systems<br/>integrations"}}

node_client_app -->|"renders"| node_client_areas
node_client_app -->|"uses"| node_client_shared
node_client_areas -->|"calls"| node_client_api
node_client_shared -->|"depends on"| node_client_state
node_client_api -->|"requests"| node_server_routes
node_client_admin -->|"manages"| node_server_admin
node_server_routes -->|"guards with"| node_server_middleware
node_server_routes -->|"dispatches to"| node_server_controllers
node_server_controllers -->|"delegates to"| node_server_services
node_server_services -->|"persists via"| node_server_models
node_server_controllers -->|"emits / joins"| node_server_socket
node_server_services -->|"wraps"| node_server_ai
node_server_services -->|"retrieves"| node_server_book_rag
node_server_controllers -->|"orchestrates"| node_server_live
node_server_controllers -->|"coordinates"| node_server_battle
node_server_controllers -->|"serves"| node_server_forum
node_server_controllers -->|"serves"| node_server_content
node_server_admin -->|"administers"| node_server_models
node_server_services -->|"integrates with"| node_server_persistence

click node_client_app "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/client/src/App.jsx"
click node_client_areas "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/pages"
click node_client_shared "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/components"
click node_client_state "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/hooks"
click node_client_api "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/services"
click node_client_admin "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/admin"
click node_server_routes "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/routes"
click node_server_auth "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/config/passport.js"
click node_server_middleware "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/middleware"
click node_server_controllers "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/controllers"
click node_server_services "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/services"
click node_server_models "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/models"
click node_server_socket "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/socket/index.js"
click node_server_admin "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/services/admin"
click node_server_ai "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/services/groqService.js"
click node_server_book_rag "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/services/bookRagService.js"
click node_server_live "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/liveClassController.js"
click node_server_battle "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/battleController.js"
click node_server_forum "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/postController.js"
click node_server_content "https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/questionController.js"

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_client_app,node_client_areas,node_client_shared,node_client_state,node_client_api,node_client_admin toneBlue
class node_server_routes,node_server_auth,node_server_middleware,node_server_controllers,node_server_services,node_server_models,node_server_socket,node_server_admin,node_server_ai,node_server_book_rag,node_server_live,node_server_battle,node_server_forum,node_server_content toneAmber
class node_server_persistence toneNeutral
```

## Components

### Client app

React/Vite SPA organized by product area and shared UX concerns.

- [App routes](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/client/src/App.jsx): spa shell · Top-level React composition and route wiring for the SPA and admin surface. · `client/src/App.jsx`
- [Product areas](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/pages): feature pages · Student-facing and teacher-facing page modules for dashboard, learning, forum, reading, live class, and settings. · `client/src/pages`
- [Shared UI](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/components): components · Reusable UI for landing, layout, forum, reader, live class, study, and settings experiences. · `client/src/components`
- [Client state](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/hooks): hooks/context/utils · Auth storage, language selection, paywall logic, socket hooks, and other shared client behavior. · `client/src/hooks`
- [API clients](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/services): service wrappers · HTTP clients for AI, forum, books, practice, contests, payments, live classes, and study routines. · `client/src/services`
- [Admin console](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/client/src/admin): admin UI · 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](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/routes): express routes · Feature route files that mount the public API and admin API under /api. · `server/routes`
- [Auth stack](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/config/passport.js): passport+jwt · Google OAuth and JWT session/API access with role-aware authorization. · `server/config/passport.js`
- [Policy layer](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/middleware): middleware · Auth, admin gating, plan/quota enforcement, uploads, rate limiting, and error normalization. · `server/middleware`
- [Controllers](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/controllers): request handlers · Request/response shaping for learning, community, AI, payments, admin, and live-class flows. · `server/controllers`
- [Domain services](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/services): business logic · Core domain logic, integrations, RAG, AI wrappers, settlement, notifications, and moderation services. · `server/services`
- [Data models](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/models): mongoose models · MongoDB persistence for users, content, attempts, sessions, payments, moderation, and audit data. · `server/models`
- [Realtime socket](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/socket/index.js): socket.io · Socket layer for battles, forum notifications, and synchronized realtime updates. · `server/socket/index.js`
- [Admin services](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/tree/main/server/services/admin): admin domain · Management services for users, teachers, questions, books, IELTS, moderation, payments, and settings. · `server/services/admin`
- [AI services](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/services/groqService.js): llm integration · Centralized Groq/OpenAI-compatible services for chat, evaluation, coaching, and book intelligence. · `server/services/groqService.js`
- [Book RAG](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/services/bookRagService.js): retrieval pipeline · PDF extraction, chunking, embeddings, derived knowledge, and contextual reader chat. · `server/services/bookRagService.js`
- [Live classes](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/liveClassController.js): live video · LiveKit-backed session lifecycle, token issuance, and attendance management. · `server/controllers/liveClassController.js`
- [Battle arena](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/battleController.js): realtime game · Socket-synchronized battle rooms, timers, answers, and scoring. · `server/controllers/battleController.js`
- [Forum core](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/postController.js): community domain · Posts, comments, reactions, bookmarks, search, reports, moderation, and sanitization. · `server/controllers/postController.js`
- [Learning content](https://github.com/ayhanarashtasin/cuet-sciblitz-ai-hackathon/blob/main/server/controllers/questionController.js): academic domain · Question bank, mock tests, contests, practice attempts, IELTS, study routines, and teacher-authored content. · `server/controllers/questionController.js`

### Other components

- **External systems**: integrations · MongoDB, Google OAuth, Firebase Storage, Cloudinary, LiveKit, Groq/LLMs, and payment providers.

## Connections

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