TheoGrader

Grading theoretical examination scripts is a demanding process for university lecturers. Answers are handwritten, students express the same concepts in different ways, and large batches of scripts must be assessed against a consistent marking scheme. The process becomes more complicated when examination instructions specify which questions students must answer and which optional answers should contribute to their final scores. Building an automated solution introduces additional challenges. Handwriting recognition can make mistakes, answer boundaries may be ambiguous, and semantic similarity alone cannot establish that an answer deserves full marks. A system that produces scores without explaining how they were derived would leave lecturers with little basis for reviewing questionable results. My goal was to build a complete assessment workflow that could process scanned scripts, associate answers with the correct rubric questions, calculate rubric-based scores, and make the reasoning behind those scores inspectable. Human oversight was a core requirement: lecturers needed to review flagged results, adjust marks when necessary, and retain responsibility for the final assessment.

I built the application as two cooperating services with clearly defined responsibilities. The Next.js application handles authentication, exam and rubric management, file uploads, grading orchestration, persistence, result review, and reporting. A separate Python FastAPI service handles the AI operations, including rubric extraction, vision-based OCR, answer segmentation, and embedding-based scoring. This separation keeps application state and database writes under the control of the web application while allowing the AI pipeline to evolve independently. For document handling, I implemented signed, direct-to-Supabase Storage uploads. The browser uploads scanned PDFs or images directly to storage instead of sending the entire file through a Vercel serverless function. The application then coordinates file confirmation, processing, and result persistence. This approach accommodates larger documents while avoiding unnecessary transfer through the web application's request handlers. The grading pipeline uses GPT-4o-mini Vision to transcribe scanned examination pages and text-embedding-3-small to generate embeddings for student answers and individual rubric points. Cosine similarity provides a scoring signal, with configured similarity bands and interpolation used to calculate partial credit. The resulting breakdown records matched, partially matched, and missing rubric concepts so lecturers can inspect how each question was scored. Similarity is an approximation of semantic alignment, not a guarantee of correctness, which is why review and score overrides remain part of the workflow. I also implemented rubric-aware answer segmentation using canonical question labels, rather than relying entirely on the model to infer answer boundaries. Exam instructions are converted into explicit selection rules, supporting scenarios such as answering any three questions out of five. The application applies the configured selection strategy when calculating totals and preserves excluded questions in the results for traceability. Finally, I addressed consistency and failure handling. Previously extracted OCR text is reused during re-grading unless it is unavailable or marked for reprocessing. Low-confidence results can be flagged for review, and grading writes replace previous results within a database transaction. If embedding generation fails, processing aborts before a new result is written, preventing a provider failure from being recorded as a genuine zero score.

The completed application supports the assessment workflow from exam setup to report generation. Lecturers can create exams, define rubrics manually or extract them from marking scheme documents, upload scanned scripts, run the grading pipeline, inspect question-level results, override marks, review flagged scripts, and export PDF reports. Exam-specific selection logic handles compulsory and optional questions so that only the answers permitted by the configured examination rules contribute to the total. Individual question results remain available for inspection, including answers excluded from the final score. The application also provides authentication, exam and script status tracking, dashboard statistics, notifications, and activity logging around the grading workflow. I deployed the Next.js application on Vercel, the FastAPI AI service as a Docker-based deployment on Render, and the PostgreSQL database and file storage on Supabase. The live application demonstrates the integration of a web platform, document-processing pipeline, external AI services, and persistent assessment data in one working system. The project demonstrates a complete implementation rather than an isolated AI experiment. Its evaluation still needs to be distinguished from deployment completeness: the fact that the workflow runs end to end does not, by itself, establish grading accuracy across a broad range of handwriting styles, subjects, or examination conditions.