How shubhamsharmayo/onscreen-marking-software works
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: server.js API server · database.js MongoDB · BackendApi.js Backend API · routes.js Role routes
Components 20
Backend
Node/Express API, persistence, queues, sockets, and domain orchestration.
- API server · Bootstraps the backend app and wires routes, sockets, storage, and database.
On-Screen-Marking-Backend/server.js - Auth · Login, OTP, WebAuthn, session tracking, and role-based access control.
On-Screen-Marking-Backend/controllers/authControllers/authControllers.js - Academics · Class, subject, schema, and question-definition configuration.
On-Screen-Marking-Backend/controllers/classControllers/classController.js - Schema map · Connects subjects to schemas and stores coordinate allocation for booklet page regions.
On-Screen-Marking-Backend/controllers/subjectSchemaRelation/subjectSchemaRelation.js - Booklets · Uploads, extracts, and prepares booklet PDFs into page images for downstream workflows.
On-Screen-Marking-Backend/controllers/bookletsProcessing/bookletsProcessing.js - Tasks · Creates and tracks booklet, scanner, reviewer, and reassignment tasks.
On-Screen-Marking-Backend/controllers/taskControllers/taskControllers.js - Evaluation · Answer page images, icons, and marks used for evaluator, reviewer, head, and quality-control flows.
On-Screen-Marking-Backend/controllers/evaluationControllers/marksController.js - Reports · Generates final results and converts data for institutional reporting.
On-Screen-Marking-Backend/controllers/resultGenerationContollers/resultGeneration.js - Analytics · Summaries and progress views over evaluation and workflow activity.
On-Screen-Marking-Backend/controllers/analyticControllers/analyticControllers.js - Files · Dedicated file manager and upload/download handling for document assets.
On-Screen-Marking-Backend/controllers/filemanagerController.js/filemanagerController.js - Worker · Runs long-running annotation and document-processing jobs off the request path.
On-Screen-Marking-Backend/Workers/annotationWorker.js - Queues · Redis-backed queueing and ephemeral coordination for asynchronous processing.
On-Screen-Marking-Backend/services/annotationQueue.js - Sockets · Socket channels for annotation, analytics, and timer-driven collaboration.
On-Screen-Marking-Backend/services/socketService.js - MongoDB · 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 · Global state for auth, annotation, and evaluator workflows with sync middleware.
Onscreen Marking Frontend/src/store/store.js - Role routes · Top-level layout and route structure for admin, evaluator, reviewer, head, scanner, and auth.
Onscreen Marking Frontend/src/routes.js - Dashboards · Role-specific management views for admin, scanner, evaluator, reviewer, quality control, and head.
Onscreen Marking Frontend/src/views/admin/default/index.jsx - Annotation UI · PDF viewing, booklet panels, tools, and annotation synchronization in the marking surface.
Onscreen Marking Frontend/src/components/PdfViewerComponent.jsx - Scanner UI · Folder selection, scan jobs, and booklet processing screens for intake roles.
Onscreen Marking Frontend/src/views/Scanner/Scanner/ScanJob.js - Backend API · Front-end service layer for REST calls and socket communication with the backend.
Onscreen Marking Frontend/src/services/BackendApi.js
Connections 28
- 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.