# sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms architecture

> Architecture diagram of the GitHub repository sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms
- Repository: https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms

## Overview

1. **Overall shape**
   - This repo is an OBE-focused LMS split into four deployable pieces: `client/` React SPA, `server/` Node/Express API, `ml_server/` FastAPI OCR service, and `ml_server_huggingface/` a deployment variant of the OCR service.
   - The main boundary is between the browser UI, the core API, and the asynchronous OCR subsystem.

2. **Frontend boundary: `client/`**
   - The React app serves three roles: admin, teacher, and student.
   - It contains public auth pages, protected profile access, and role-based dashboards.
   - Most UI features are domain-driven screens for courses, marks, attainment, course profiles, and OCR job status. It talks to the backend through service modules in `client/src/services`.

3. **Backend entrypoint and shared middleware: `server/server.js`**
   - The Express server is the central application coordinator.
   - It initializes security and request handling concerns such as CORS, payload limits, auth/role middleware, MongoDB connection, route registration, and startup of the OCR worker/queue infrastructure.
   - This server is both the main API and the orchestrator for background processing.

4. **Identity and access management**
   - Authentication is JWT-based with login, registration, OTP/email verification, forgot/reset password, and profile endpoints under `authRoutes`.
   - Authorization is role-based, with separate controls for admin, teacher, and student via middleware.
   - User approval/state management is part of the admin workflow, not just authentication.

5. **Core academic domain**
   - Courses, course outcomes, program outcomes, course proposals, and course profiles are separate but connected backend modules.
   - The curriculum side of the system centers on validating OBE structure, assigning teachers/batches, defining CO/PO metadata, and maintaining course profile data.
   - This is the “master data” layer that other workflows depend on.

6. **Assessment and attainment workflows**
   - The attainment subsystem covers CTs, assignments, lab activities, section-based workflows, term exam marks, and result computation.
   - The backend has dedicated models for each attainment type and routes for capturing, calculating, and viewing attainment outputs.
   - Results are a downstream product of the assessment data and can be published or unpublished.

7. **Asynchronous OCR pipeline**
   - OCR is not handled synchronously in the request thread; it is a queued background workflow.
   - `ocrRoutes` accept jobs, Redis + Bull hold the queue, and `server/workers/ocrWorker.js` performs processing.
   - The worker submits images to an ML service, then stores job state, extracted marks, and confidence for later polling by the client.

8. **ML service boundary**
   - `ml_server/` and `ml_server_huggingface/` are separate FastAPI microservices exposing health and extraction endpoints.
   - They are protected by an API key and are treated as replaceable inference backends.
   - The OCR stack uses layout/table detection, cell detection, and text recognition to extract marks from uploaded sheet images.

9. **Persistence model**
   - MongoDB is the system of record, accessed through Mongoose models in `server/models`.
   - The schema set is organized around users, curriculum entities, attainment records, term marks, term results, and OCR-related job metadata.
   - Redis is not a primary store; it is the job-queue and coordination layer for OCR.

10. **Supporting services and imports/exports**
   - The system uses email for verification and password reset flows.
   - Excel/CSV import-export is part of admin onboarding and bulk data operations, especially teacher/student credential workflows.
   - There are utility modules for curriculum validation, course profile initialization, password reset, seeds, and worker registry/health management, which support the main subsystems rather than forming separate domains.

11. **How data flows end to end**
   - Typical academic flow: user logs in → role-gated dashboard → edits curriculum/marks/attainment → backend persists to MongoDB → results are computed and viewed.
   - OCR flow: teacher/admin uploads an image → API enqueues a job → worker calls the ML service → extracted marks return to the API layer → client polls status and consumes the result.

12. **Operational separation**
   - The repo is designed to run with MongoDB, Redis, the API server, the React client, and one of the FastAPI OCR services as distinct processes/containers.
   - That separation is important for the architecture diagram: UI, transactional API, queue/worker, and ML inference are separate trust and scaling boundaries.

Main entry points: [`server/server.js`](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/server.js) (Express Server), [`server/models/User.js`](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/models/User.js) (MongoDB), [`client/src/components`](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/components) (Domain UI), [`server/controllers/ocrController.js`](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/ocrController.js) (OCR API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["React App<br/>spa shell<br/>[App.js]"]
  node_client_pages["Dashboards<br/>role pages"]
  node_client_domain_ui["Domain UI<br/>feature screens"]
  node_client_attainment_ui["Attainment UI<br/>attainment views"]
  node_client_services["API Services<br/>http client"]
end

subgraph group_server["API & Worker"]
  node_api_server["Express Server<br/>api host<br/>[server.js]"]
  node_auth_ctrl["Auth<br/>identity controller<br/>[authController.js]"]
  node_admin_ctrl["Admin<br/>[adminController.js]"]
  node_course_ctrl["Curriculum<br/>course controller"]
  node_outcome_ctrl["Outcomes<br/>outcome controller"]
  node_attainment_ctrl["Attainment<br/>assessment controller"]
  node_marks_ctrl["Term Marks<br/>marks controller"]
  node_result_ctrl["Results<br/>result controller"]
  node_ocr_ctrl["OCR API<br/>ocr controller<br/>[ocrController.js]"]
  node_worker["OCR Worker<br/>background worker<br/>[ocrWorker.js]"]
  node_queue["Redis Queue<br/>job queue<br/>[queue.js]"]
  node_mongo[("MongoDB<br/>persistence<br/>[User.js]")]
  node_redis[("Redis<br/>coordination cache<br/>[redisClient.js]")]
end

subgraph group_ml["ML OCR"]
  node_ml_api["OCR Service<br/>fastapi inference<br/>[app.py]"]
  node_ml_hf_api["HF OCR<br/>fastapi variant<br/>[app.py]"]
end

node_client_app -->|"routes to"| node_client_pages
node_client_app -->|"composes"| node_client_domain_ui
node_client_domain_ui -->|"includes"| node_client_attainment_ui
node_client_pages -->|"calls"| node_client_services
node_client_domain_ui -->|"calls"| node_client_services
node_client_services -->|"HTTP API"| node_api_server
node_api_server -->|"registers"| node_auth_ctrl
node_api_server -->|"registers"| node_admin_ctrl
node_api_server -->|"registers"| node_course_ctrl
node_api_server -->|"registers"| node_outcome_ctrl
node_api_server -->|"registers"| node_attainment_ctrl
node_api_server -->|"registers"| node_marks_ctrl
node_api_server -->|"registers"| node_result_ctrl
node_api_server -->|"registers"| node_ocr_ctrl
node_ocr_ctrl -->|"enqueues"| node_queue
node_queue -->|"dispatches"| node_worker
node_worker -->|"extracts via"| node_ml_api
node_worker -.->|"fallback/variant"| node_ml_hf_api
node_api_server -->|"persists to"| node_mongo
node_api_server -->|"uses"| node_redis
node_auth_ctrl -->|"stores users"| node_mongo
node_attainment_ctrl -->|"stores records"| node_mongo
node_ocr_ctrl -->|"stores jobs"| node_mongo

click node_client_app "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/client/src/App.js"
click node_client_pages "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/pages"
click node_client_domain_ui "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/components"
click node_client_attainment_ui "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/components/attainment"
click node_client_services "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/services"
click node_api_server "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/server.js"
click node_auth_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/authController.js"
click node_admin_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/adminController.js"
click node_course_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/courseController.js"
click node_outcome_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/courseOutcomeController.js"
click node_attainment_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/attainmentController.js"
click node_marks_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/termExamMarksController.js"
click node_result_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/resultController.js"
click node_ocr_ctrl "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/ocrController.js"
click node_worker "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/workers/ocrWorker.js"
click node_queue "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/config/queue.js"
click node_mongo "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/models/User.js"
click node_redis "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/config/redisClient.js"
click node_ml_api "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/ml_server/app.py"
click node_ml_hf_api "https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/ml_server_huggingface/app.py"

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_pages,node_client_domain_ui,node_client_attainment_ui,node_client_services toneBlue
class node_api_server,node_auth_ctrl,node_admin_ctrl,node_course_ctrl,node_outcome_ctrl,node_attainment_ctrl,node_marks_ctrl,node_result_ctrl,node_ocr_ctrl,node_worker,node_queue,node_mongo,node_redis toneAmber
class node_ml_api,node_ml_hf_api toneMint
```

## Components

### Client

React SPA for admin, teacher, and student workflows

- [React App](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/client/src/App.js): spa shell · Top-level client routing and app composition · `client/src/App.js`
- [Dashboards](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/pages): role pages · Login, profile, and role-based dashboard pages · `client/src/pages`
- [Domain UI](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/components): feature screens · Course, outcome, mark entry, attainment, and result screens · `client/src/components`
- [Attainment UI](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/components/attainment): attainment views · CO/PO calculation and sectional attainment workflows · `client/src/components/attainment`
- [API Services](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/tree/main/client/src/services): http client · Frontend service modules used to call backend APIs · `client/src/services`

### API & Worker

Express API, domain controllers, persistence, and background processing

- [Express Server](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/server.js): api host · Main API entrypoint, middleware setup, route registration, and worker startup · `server/server.js`
- [Auth](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/authController.js): identity controller · Login, registration, password reset, and email verification flows · `server/controllers/authController.js`
- [Admin](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/adminController.js): admin controller · User approval and bulk import/export administration · `server/controllers/adminController.js`
- [Curriculum](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/courseController.js): course controller · Courses, outcomes, proposals, profiles, and curriculum structure · `server/controllers/courseController.js`
- [Outcomes](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/courseOutcomeController.js): outcome controller · Course outcomes, program outcomes, and CO/PO mapping · `server/controllers/courseOutcomeController.js`
- [Attainment](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/attainmentController.js): assessment controller · CTs, assignments, labs, attainment calculation, and result generation · `server/controllers/attainmentController.js`
- [Term Marks](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/termExamMarksController.js): marks controller · Term exam marks capture and retrieval · `server/controllers/termExamMarksController.js`
- [Results](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/resultController.js): result controller · Publish and view computed term results · `server/controllers/resultController.js`
- [OCR API](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/controllers/ocrController.js): ocr controller · Queue OCR jobs and expose job status/result endpoints · `server/controllers/ocrController.js`
- [OCR Worker](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/workers/ocrWorker.js): background worker · Consumes queued OCR jobs and coordinates extraction · `server/workers/ocrWorker.js`
- [Redis Queue](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/config/queue.js): job queue · Bull/Redis job coordination for OCR processing · `server/config/queue.js`
- [MongoDB](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/models/User.js): persistence · System of record via Mongoose models and stored academic/ocr state · `server/models/User.js`
- [Redis](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/server/config/redisClient.js): coordination cache · Queue backend and transient worker coordination · `server/config/redisClient.js`

### ML OCR

FastAPI OCR inference services

- [OCR Service](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/ml_server/app.py): fastapi inference · Primary OCR microservice for layout, table, cell, and text extraction · `ml_server/app.py`
- [HF OCR](https://github.com/sifatul-islam-onik/cse-3200-system-development-project-ml-integrated-lms/blob/main/ml_server_huggingface/app.py): fastapi variant · Alternative deployment of the OCR inference service · `ml_server_huggingface/app.py`

## Connections

- React App → Dashboards: routes to · App renders login, profile, and dashboard pages
- React App → Domain UI: composes · App hosts domain-driven feature screens
- Domain UI → Attainment UI: includes · Attainment screens are a major UI subset
- Dashboards → API Services: calls · Pages use service modules for backend requests
- Domain UI → API Services: calls · Domain screens fetch and mutate data through services
- API Services → Express Server: HTTP API · Frontend talks to the Express backend
- Express Server → Auth: registers · Server mounts auth routes and middleware
- Express Server → Admin: registers · Server mounts admin workflows
- Express Server → Curriculum: registers · Server exposes curriculum endpoints
- Express Server → Outcomes: registers · Server exposes CO/PO and outcome endpoints
- Express Server → Attainment: registers · Server exposes attainment endpoints
- Express Server → Term Marks: registers · Server exposes term marks endpoints
- Express Server → Results: registers · Server exposes result endpoints
- Express Server → OCR API: registers · Server exposes OCR job endpoints
- OCR API → Redis Queue: enqueues · OCR requests become queued jobs
- Redis Queue → OCR Worker: dispatches · Redis/Bull delivers jobs to the worker
- OCR Worker → OCR Service: extracts via · Worker calls the primary OCR inference backend
- OCR Worker → HF OCR: fallback/variant · Deployable alternate OCR backend
- Express Server → MongoDB: persists to · Controllers read and write academic and identity state
- Express Server → Redis: uses · Server uses Redis for queueing and coordination
- Auth → MongoDB: stores users · Authentication and approval state live in MongoDB
- Attainment → MongoDB: stores records · Attainment data and computed outputs are persisted
- OCR API → MongoDB: stores jobs · OCR job metadata and extracted marks are saved