GradeSense.

Product Overview

GradeSense is an exam and regrade-request feature inside LearnWithAI. It connects the original grading context—exam PDFs, question rubrics, maximum scores, and recorded marks—to a student’s appeal and the teaching team’s final decision.

The application has two complete experiences: students inspect their graded work and request reconsideration; instructors and teaching assistants create exams, upload submissions, record scores, review reasoning, and resolve requests. AI provides preview feedback and a recommendation state, while staff make the final grading decision.

Problem and Solution

A grade appeal is difficult to assess when the exam, rubric, awarded score, requested score, and student’s explanation live in separate places. A single changed grade also needs to be reflected in what the student sees afterward.

GradeSense organizes the process around a specific exam question. The student starts with the actual question context, submits a structured request, and can return to a status view containing the decision, available feedback, and final score. Staff review that same request in the exam context.

Student Experience

The exam list exposes the exams available in a course and a route to the student’s request history. An exam detail page combines a graded PDF with question-level scores and expandable rubric information, making the original assessment available before an appeal is written.

Selecting a question opens a prefilled regrade dialog. The question number and original score can be locked from the selected question; the student supplies a requested score and written reasoning. A separate preview action returns AI feedback without requiring immediate submission.

1. 01

   View course exams and open the relevant graded exam.

2. 02

   Read the graded PDF alongside individual question marks, maximum scores, and rubrics.

3. 03

   Select a question and enter a requested score with supporting reasoning.

4. 04

   Request AI preview feedback; continue to submission even if the preview is unavailable.

5. 05

   Submit the appeal and return to the request-status view.

6. 06

   Track the request state, instructor decision, final score, and available AI or instructor feedback.

Instructor Experience

Instructors and TAs create an exam with a title and a dynamic list of questions. Each question has a maximum score and an optional rubric. They can then upload a student’s graded PDF and record the scores for that student’s questions.

The exam request-review page shows the submitted reasoning, original and requested scores, recommendation state, and decision controls. Accepting opens a final-score dialog; rejecting opens a feedback dialog. The updated request is reflected in the review list and the student’s status view.

1. 01

   Create an exam and define each question’s number, maximum score, and rubric.

2. 02

   Select a student submission, upload the graded PDF, and record per-question marks.

3. 03

   Open the exam’s review list and inspect student reasoning and recommendation states.

4. 04

   Accept with a final score, or reject with written feedback.

5. 05

   Return the decision and associated grade or feedback to the student-facing workflow.

System Architecture

Angular components coordinate screens and forms through a feature-specific frontend service. Most structured operations use generated API functions; PDF upload and preview feedback also use HttpClient. FastAPI request and response models define the HTTP contracts.

Routes handle authentication, course-role checks on the relevant operations, HTTP errors, file delivery, and AI orchestration. RegradeRequestService coordinates application rules through repositories. SQLModel maps the records to PostgreSQL; graded PDF bytes are stored on the server with a path in the submission record.

Frontend Engineering

The feature uses focused Angular components for exam lists, exam detail, exam creation, PDF upload, request dialogs, staff review, and student status. Signals represent loading, errors, current records, and submission or preview progress; the inspected components use OnPush change detection.

Reactive forms validate required fields, positive question numbers, non-negative scores, and minimum reasoning length in the appeal dialog. Staff exam creation uses a FormArray for question definitions. The upload workflow sends multipart PDF data and then records question scores through a separate typed operation.

The frontend service keeps endpoint details out of the view components. Generated API methods handle structured requests and responses; PDF retrieval uses an authenticated blob request and an object URL for the embedded viewer. Success snackbars, disabled in-flight actions, and visible failure messages give the user feedback at each boundary.

Backend Engineering

The HTTP layer exposes exam creation and retrieval, submission upload, score updates, question retrieval, preview feedback, appeal submission, staff review lists, acceptance, rejection, and the student’s request history. Typed models describe nested exam questions, score lists, preview context, and decision payloads.

The business service validates exam titles and question lists, confirms referenced exams exist, rejects invalid or decreasing requested scores, and rejects blank reasoning. It combines question definitions with the current student’s submission scores for exam detail. Repositories encapsulate course, exam, student, and submission queries.

The shared session dependency owns transaction commit, rollback, and closure. This keeps transaction lifecycle out of route handlers and gives repositories a consistent request-scoped session. Constructor-injected repositories make service behavior testable without requiring a browser or the entire HTTP application.

Database Architecture

The GradeSense schema separates exams, exam questions, student submissions, submission question scores, and regrade requests. Exams reference a course and creator. A submission connects a student to an exam and a stored PDF path. Scores reference the submission and carry a question number.

A regrade request references the exam and student, identifies the question number, and stores original and requested marks, reasoning, workflow state, and optional AI feedback, instructor feedback, and final-score fields. This preserves the distinction between the original assessment, the request, and its disposition.

The inspected application initializes SQLModel metadata through the shared database layer. No feature-specific versioned migration sequence was found in the reviewed tree, so this case study does not claim one.

AI Integration

For a preview, the frontend sends the question number, maximum and current scores, rubric, and student reasoning to an authenticated endpoint. A shared Azure OpenAI-compatible completion service generates a brief assessment, which is returned in a typed HTTP response containing a summary string.

Submission uses a separate classification call with question context loaded from the backend. The response is interpreted by an APPROVED prefix; other responses map to an AI-denied recommendation. Missing configuration or a classification error falls back to staff review. Neither recommendation directly performs a final grade update.

The HTTP response has a defined shape, but the underlying model completion is prose rather than a guaranteed JSON-schema output. Preview feedback is displayed in the dialog; the inspected submission path primarily persists the recommendation state. Optional AI-score and feedback columns do not mean every submission populates them.

Authentication and Permissions

GradeSense reuses LearnWithAI’s authenticated user dependency and JWT-backed identity. Course membership and instructor/TA role checks guard the inspected exam-creation, upload, score-setting, staff-list, and decision routes. Student PDF and question retrieval use the authenticated subject and course context.

The student-history endpoint queries requests by the authenticated student identifier. The Angular UI also changes navigation and available actions for students and staff, while backend checks remain the authority for protected operations.

Permission coverage should be assessed endpoint by endpoint. The project demonstrates role-aware behavior, but this portfolio does not claim a complete security audit or uniform authorization hardening across every mutation.

Testing and Reliability

The inspected API tests cover successful submission, invalid score input, missing exams, authentication requirements, staff-only operations, course membership checks, PDF delivery failures, AI-preview availability, and classification fallback. Service tests isolate business validation and decision behavior; repository tests exercise the data-access operations.

Angular tests cover service calls and dialog behavior, including prefilled values, invalid forms, duplicate in-flight actions, successful previews, unavailable previews, and submission errors. Associated exam-list, exam-detail, creation, upload, and status tests are also present.

These are observations from the checked-in suites, not a newly measured coverage report. No coverage percentage or passing test count for the private application is claimed. Existing tests cover state-dependent UI behavior, while stronger server-side transition guards remain a future hardening task.

Engineering Challenges

The central challenge is keeping question context, student input, AI guidance, staff decisions, and stored grades consistent across several screens and API operations. Separate models, services, repositories, and a frontend service make those boundaries explicit and easier to test.

Outcomes and Lessons

The collaborative implementation connects exam setup and grading to question-specific appeals, optional AI preview, teaching-team review, and student-visible decisions. The documentation and reviewed screenshots demonstrate both sides of that workflow.

The strongest engineering lesson is that AI belongs inside an explicit application process: typed context in, assistance out, and accountable human decisions at the grade-change boundary. The other lesson is that schema precision, authorization consistency, and partial-update regression tests deserve dedicated attention before wider deployment.

This case study describes the complete team application. The repository and screenshots remain private, and no adoption figures or deployment claims are invented.