# shubhamsharmayo/onscreen-marking-software architecture

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

- Interactive diagram: https://gitdiagram.com/shubhamsharmayo/onscreen-marking-software
- Repository: https://github.com/shubhamsharmayo/onscreen-marking-software

## Overview

1. **High-level shape**
   - This is a two-app repository: a **Node.js/Express backend** and a **React frontend**.
   - The backend is the system of record and orchestration layer; the frontend is a role-specific UI for admin, scanner, evaluator, reviewer, and head/equality-control workflows.

2. **Backend layering**
   - The backend is organized into clear boundaries: **routes → controllers → services/middlewares → models**, with **workers**, **socket handlers**, and **utils** supporting cross-cutting concerns.
   - MongoDB is the primary persistence layer via Mongoose models; Redis and Bull are used for asynchronous processing and transient queue/state management.

3. **Identity and access control**
   - Authentication is handled by `authControllers`, `authMiddleware`, and user-related models (`User`, `UserLoginLog`, `otp`).
   - The system uses role-based access across multiple user types, with protected routes for admin, evaluator, reviewer, head, scanner, and quality-control flows.
   - OTP/email support and login logs indicate both account verification and auditability are part of the auth boundary.

4. **Core academic domain management**
   - The admin domain includes **classes**, **subjects**, **schemas**, and **question definitions**.
   - `classControllers`, `schemeControllers`, and `subjectSchemaRelation` implement the configuration layer that defines how a subject is evaluated and how its schema maps to booklet structure.
   - `coordinateAllocation` suggests the system stores page-region coordinates for annotation or question targeting, tying schema definitions to actual PDF positions.

5. **Booklet ingestion and document preparation**
   - PDF upload and extraction are first-class concerns: middlewares for uploading answer/supplementary PDFs feed booklet-processing controllers and services like `extractImagesFromPdf`.
   - The booklet-processing flow converts uploaded PDFs into page images and creates the data needed for evaluation screens and task assignment.
   - File management is separated into its own controller/route area, indicating document storage and retrieval are treated as a dedicated subsystem.

6. **Evaluation engine**
   - The evaluation domain is centered on `answerPdfImage`, `marks`, `icon`, and related models for booklet/head marks.
   - Controllers in `evaluationControllers` manage the actual marking workflow: displaying answer-page images, applying annotation icons, and persisting question-wise and total marks.
   - This subsystem is the core business engine for check/review/finalization across evaluator, reviewer, and head roles.

7. **Workflow and task orchestration**
   - Task-related models (`taskModel`, `bookletTaskModel`, `reviewerTaskModel`, `scannerTaskModel`, `bookletReassignmentModel`) show that work is explicitly assigned and tracked.
   - `taskControllers` and `bookletProcessing` coordinate transitions such as upload → extraction → assignment → evaluation → review → reassignment.
   - The presence of separate task types implies workflow state is modeled explicitly rather than inferred from UI state.

8. **Background processing and queueing**
   - Long-running operations are offloaded to `Workers/annotationWorker.js` and services like `annotationQueue` and `bullRedis`.
   - Redis-backed Bull queues handle asynchronous jobs such as annotation-related processing and likely image extraction or post-processing.
   - This is the main scalability boundary: synchronous API requests handle orchestration, while heavy document work happens in background workers.

9. **Real-time collaboration and monitoring**
   - Socket.IO is used through `socketService` and socket modules such as `annotationSocket`, `analyticSocket`, and `evaluatorAnalyticSocket`.
   - Real-time channels support live evaluation updates, progress monitoring, and timer handling (`handleTimer`), which matters for session-based marking workflows.
   - Analytics and annotation events are likely pushed to dashboards so supervisors can observe active work without polling.

10. **Analytics and result generation**
   - `analyticControllers` and `resultGenerationControllers` represent the reporting layer over evaluation data.
   - CSV conversion services (`csvToJson`, `jsonToCsv`) and result generation routes suggest the backend exports finalized marks for institutional reporting.
   - This is downstream from evaluation data and depends on completed booklet/task state in MongoDB.

11. **Frontend structure**
   - The frontend is organized around **role-based layouts** and route groups: admin, evaluator, reviewer, head, quality control, scanner, and auth.
   - It uses React state management with Redux slices for auth, annotation, and evaluator state, plus a custom sync middleware.
   - UI is split between dashboard-style management screens and dedicated booklet/checking screens, which mirrors the backend workflow separation.

12. **Document viewing and annotation UI**
   - The frontend contains a substantial PDF viewing/annotation surface, including `PdfViewerComponent`, `Pdftron`, `WebViewer` assets, and annotation-related hooks.
   - This is the user-facing counterpart to the backend’s image/mark/coordinate models: the UI renders booklet pages, overlays tools, and syncs annotation state back to the API/socket layer.
   - Components like question sections, image containers, and tool panels indicate the app is designed for structured marking rather than generic PDF viewing.

13. **Frontend-to-backend data flow**
   - The frontend talks to the backend through `src/services/BackendApi.js` and socket client code, with helper modules abstracting specific domain operations.
   - Typical flow is: load role dashboard → fetch assigned tasks/booklets → open booklet pages → annotate/mark → submit via API/socket → review/finalize → generate reports.
   - The frontend also includes scanner and folder-management views, so it is not just a marking client; it participates in booklet intake and processing workflows too.

14. **Infrastructure and operational notes**
   - MongoDB stores all durable domain objects; Redis provides queueing and likely ephemeral coordination; Node/Express runs the API and websocket server.
   - `cleanupSessions.js` and session/login logs imply operational hygiene and inactivity handling are important.
   - For an architecture diagram, the important boundary is: **interactive UI and API calls on one side, asynchronous document processing and real-time event delivery on the other**.

Main entry points: [`On-Screen-Marking-Backend/server.js`](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/server.js) (API server), [`On-Screen-Marking-Backend/utils/database.js`](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/utils/database.js) (MongoDB), [`Onscreen Marking Frontend/src/services/BackendApi.js`](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/services/BackendApi.js) (Backend API), [`Onscreen Marking Frontend/src/routes.js`](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/routes.js) (Role routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_server["API server<br/>express entrypoint<br/>[server.js]"]
  node_auth["Auth<br/>identity boundary<br/>[authControllers.js]"]
  node_academic["Academics<br/>admin config<br/>[classController.js]"]
  node_relations["Schema map<br/>schema linkage"]
  node_booklets["Booklets<br/>pdf ingestion"]
  node_tasks["Tasks<br/>work assignment<br/>[taskControllers.js]"]
  node_evaluation["Evaluation<br/>marking engine<br/>[marksController.js]"]
  node_reports["Reports<br/>result export"]
  node_analytics["Analytics<br/>monitoring api"]
  node_files["Files<br/>document storage"]
  node_worker["Worker<br/>background job"]
  node_queues["Queues<br/>redis/bull<br/>[annotationQueue.js]"]
  node_realtime(("Sockets<br/>live updates<br/>[socketService.js]"))
  node_db[("MongoDB<br/>mongoose models<br/>[database.js]")]
end

subgraph group_frontend["Frontend"]
  node_store["Client store<br/>redux state<br/>[store.js]"]
  node_routesui["Role routes<br/>react routing<br/>[routes.js]"]
  node_dashboards["Dashboards<br/>role pages<br/>[index.jsx]"]
  node_annotationui["Annotation UI<br/>pdf markup"]
  node_scanui["Scanner UI<br/>intake workflow<br/>[ScanJob.js]"]
  node_api["Backend API<br/>http/socket client<br/>[BackendApi.js]"]
end

node_server -->|"uses"| node_auth
node_server -->|"uses"| node_academic
node_server -->|"uses"| node_relations
node_server -->|"uses"| node_booklets
node_server -->|"uses"| node_tasks
node_server -->|"uses"| node_evaluation
node_server -->|"uses"| node_reports
node_server -->|"uses"| node_analytics
node_server -->|"uses"| node_files
node_server -->|"attaches"| node_realtime
node_auth -->|"persists"| node_db
node_academic -->|"persists"| node_db
node_relations -->|"persists"| node_db
node_booklets -->|"offloads"| node_queues
node_booklets -->|"persists"| node_db
node_tasks -->|"persists"| node_db
node_evaluation -->|"persists"| node_db
node_reports -->|"reads"| node_db
node_analytics -->|"reads"| node_db
node_worker -->|"consumes"| node_queues
node_realtime -.->|"reports"| node_worker
node_routesui -->|"navigates"| node_dashboards
node_routesui -->|"navigates"| node_annotationui
node_routesui -->|"navigates"| node_scanui
node_store -->|"drives"| node_api
node_annotationui -->|"syncs"| node_api
node_scanui -->|"syncs"| node_api
node_api -->|"calls"| node_server

click node_server "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/server.js"
click node_auth "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/authControllers/authControllers.js"
click node_academic "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/classControllers/classController.js"
click node_relations "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/subjectSchemaRelation/subjectSchemaRelation.js"
click node_booklets "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/bookletsProcessing/bookletsProcessing.js"
click node_tasks "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/taskControllers/taskControllers.js"
click node_evaluation "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/evaluationControllers/marksController.js"
click node_reports "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/resultGenerationContollers/resultGeneration.js"
click node_analytics "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/analyticControllers/analyticControllers.js"
click node_files "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/filemanagerController.js/filemanagerController.js"
click node_worker "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/Workers/annotationWorker.js"
click node_queues "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/services/annotationQueue.js"
click node_realtime "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/services/socketService.js"
click node_db "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/utils/database.js"
click node_store "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/Onscreen Marking Frontend/src/store/store.js"
click node_routesui "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/Onscreen Marking Frontend/src/routes.js"
click node_dashboards "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/Onscreen Marking Frontend/src/views/admin/default/index.jsx"
click node_annotationui "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/Onscreen Marking Frontend/src/components/PdfViewerComponent.jsx"
click node_scanui "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/Onscreen Marking Frontend/src/views/Scanner/Scanner/ScanJob.js"
click node_api "https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/Onscreen Marking Frontend/src/services/BackendApi.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_server,node_auth,node_academic,node_relations,node_booklets,node_tasks,node_evaluation,node_reports,node_analytics,node_files,node_worker,node_queues,node_realtime,node_db toneBlue
class node_store,node_routesui,node_dashboards,node_annotationui,node_scanui,node_api toneAmber
```

## Components

### Backend

Node/Express API, persistence, queues, sockets, and domain orchestration.

- [API server](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/server.js): express entrypoint · Bootstraps the backend app and wires routes, sockets, storage, and database. · `On-Screen-Marking-Backend/server.js`
- [Auth](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/authControllers/authControllers.js): identity boundary · Login, OTP, WebAuthn, session tracking, and role-based access control. · `On-Screen-Marking-Backend/controllers/authControllers/authControllers.js`
- [Academics](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/classControllers/classController.js): admin config · Class, subject, schema, and question-definition configuration. · `On-Screen-Marking-Backend/controllers/classControllers/classController.js`
- [Schema map](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/subjectSchemaRelation/subjectSchemaRelation.js): schema linkage · Connects subjects to schemas and stores coordinate allocation for booklet page regions. · `On-Screen-Marking-Backend/controllers/subjectSchemaRelation/subjectSchemaRelation.js`
- [Booklets](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/bookletsProcessing/bookletsProcessing.js): pdf ingestion · Uploads, extracts, and prepares booklet PDFs into page images for downstream workflows. · `On-Screen-Marking-Backend/controllers/bookletsProcessing/bookletsProcessing.js`
- [Tasks](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/taskControllers/taskControllers.js): work assignment · Creates and tracks booklet, scanner, reviewer, and reassignment tasks. · `On-Screen-Marking-Backend/controllers/taskControllers/taskControllers.js`
- [Evaluation](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/evaluationControllers/marksController.js): marking engine · Answer page images, icons, and marks used for evaluator, reviewer, head, and quality-control flows. · `On-Screen-Marking-Backend/controllers/evaluationControllers/marksController.js`
- [Reports](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/resultGenerationContollers/resultGeneration.js): result export · Generates final results and converts data for institutional reporting. · `On-Screen-Marking-Backend/controllers/resultGenerationContollers/resultGeneration.js`
- [Analytics](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/analyticControllers/analyticControllers.js): monitoring api · Summaries and progress views over evaluation and workflow activity. · `On-Screen-Marking-Backend/controllers/analyticControllers/analyticControllers.js`
- [Files](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/controllers/filemanagerController.js/filemanagerController.js): document storage · Dedicated file manager and upload/download handling for document assets. · `On-Screen-Marking-Backend/controllers/filemanagerController.js/filemanagerController.js`
- [Worker](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/Workers/annotationWorker.js): background job · Runs long-running annotation and document-processing jobs off the request path. · `On-Screen-Marking-Backend/Workers/annotationWorker.js`
- [Queues](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/services/annotationQueue.js): redis/bull · Redis-backed queueing and ephemeral coordination for asynchronous processing. · `On-Screen-Marking-Backend/services/annotationQueue.js`
- [Sockets](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/services/socketService.js): live updates · Socket channels for annotation, analytics, and timer-driven collaboration. · `On-Screen-Marking-Backend/services/socketService.js`
- [MongoDB](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/main/On-Screen-Marking-Backend/utils/database.js): mongoose models · Durable persistence for users, tasks, booklets, schemas, and evaluation state. · `On-Screen-Marking-Backend/utils/database.js`

### Frontend

React UI for role-based workflows, PDF viewing, annotation, and dashboards.

- [Client store](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/store/store.js): redux state · Global state for auth, annotation, and evaluator workflows with sync middleware. · `Onscreen Marking Frontend/src/store/store.js`
- [Role routes](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/routes.js): react routing · Top-level layout and route structure for admin, evaluator, reviewer, head, scanner, and auth. · `Onscreen Marking Frontend/src/routes.js`
- [Dashboards](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/views/admin/default/index.jsx): role pages · Role-specific management views for admin, scanner, evaluator, reviewer, quality control, and head. · `Onscreen Marking Frontend/src/views/admin/default/index.jsx`
- [Annotation UI](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/components/PdfViewerComponent.jsx): pdf markup · PDF viewing, booklet panels, tools, and annotation synchronization in the marking surface. · `Onscreen Marking Frontend/src/components/PdfViewerComponent.jsx`
- [Scanner UI](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/views/Scanner/Scanner/ScanJob.js): intake workflow · Folder selection, scan jobs, and booklet processing screens for intake roles. · `Onscreen Marking Frontend/src/views/Scanner/Scanner/ScanJob.js`
- [Backend API](https://github.com/shubhamsharmayo/onscreen-marking-software/blob/HEAD/Onscreen%20Marking%20Frontend/src/services/BackendApi.js): http/socket client · Front-end service layer for REST calls and socket communication with the backend. · `Onscreen Marking Frontend/src/services/BackendApi.js`

## Connections

- API server → Auth: uses · Exposes protected auth and session routes.
- API server → Academics: uses · Mounts admin configuration routes.
- API server → Schema map: uses · Mounts schema-to-booklet mapping routes.
- API server → Booklets: uses · Handles PDF uploads and extraction orchestration.
- API server → Tasks: uses · Exposes task assignment and reassignment flows.
- API server → Evaluation: uses · Serves marking and review APIs.
- API server → Reports: uses · Serves result generation endpoints.
- API server → Analytics: uses · Serves analytics endpoints.
- API server → Files: uses · Exposes file management endpoints.
- API server → Sockets: attaches · Starts socket channels alongside the API.
- Auth → MongoDB: persists · Stores users, OTP records, and login logs.
- Academics → MongoDB: persists · Stores classes, subjects, schemas, and definitions.
- Schema map → MongoDB: persists · Stores subject-schema links and coordinate allocations.
- Booklets → Queues: offloads · Pushes heavy PDF/image work to background jobs.
- Booklets → MongoDB: persists · Stores booklet intake and extraction state.
- Tasks → MongoDB: persists · Tracks assignment state across task types.
- Evaluation → MongoDB: persists · Stores marks, icons, and answer-image state.
- Reports → MongoDB: reads · Builds exports from finalized evaluation data.
- Analytics → MongoDB: reads · Aggregates workflow and marking progress.
- Worker → Queues: consumes · Processes queued annotation and document jobs.
- Sockets → Worker: reports · Broadcasts processing and marking updates.
- Role routes → Dashboards: navigates · Routes users into role-specific pages.
- Role routes → Annotation UI: navigates · Opens the main marking surface.
- Role routes → Scanner UI: navigates · Opens scanner and intake pages.
- Client store → Backend API: drives · Centralizes client-side data access and socket sync.
- Annotation UI → Backend API: syncs · Loads pages, submits marks, and receives live updates.
- Scanner UI → Backend API: syncs · Uploads and processes intake documents.
- Backend API → API server: calls · Consumes REST endpoints and websocket events.