CompuGrade User Flows

This document details the step-by-step, micro-level interactions between the user, the client applications, and the backend services.

System Actors & Communications Roster

Before diving into the flows, here is the complete list of all users (personas) and system-based communication nodes (services) involved in the platform.

User Personas

  • Student: End-user consuming lessons via the Office/Google add-ins.
  • Teacher: Instructor monitoring grades via the Admin Dashboard and authorizing content.
  • Course Builder: Curriculum designer creating content in Open edX Studio using the Writer Engine.
  • School Admin: Principal/IT staff monitoring a single school's seat usage and teacher rosters.
  • District Admin: IT Director managing SSO, provisioning schools, and allocating district-wide seat budgets.
  • Super Admin: Internal CompuGrade staff managing tenant onboarding, global roles, and system health.

System-Based Communications (Service Nodes)

  • Client Add-ins (MS/Google): Extracts base64 document state and renders the React taskpane UI.
  • Auto-Router Edge Service: Resolves student emails to specific tenant backend_url clusters.
  • Computency (Learning API): The central BFF (Backend-for-Frontend) handling auth, S3 uploads, and DB syncing.
  • DocDiff (.NET XML Engine): Stateless grading service that diffs OpenXML structures.
  • Interop (.NET COM Engine): Fallback grading service that uses Windows Office COM for rendering/PDF conversions.
  • Celery/Redis Workers: Background task queues for async grading evaluation.
  • Open edX Studio & LMS: The source of truth for course structures, enrollments, and final gradebooks.
  • Open edX CMS Plugin (tutor-myplugin): Bridges Open edX with CompuGrade classes and webhook orchestration.
  • Admin Dashboard FE: The React SPA used by all Admin/Teacher personas.
  • Admin Dashboard BE: The FastAPI orchestration layer for SSO keys, seat licensing, and Open edX server-to-server syncs.

1. Student Authentication & Session Initialization

Persona: Student
Context: Opening the CompuGrade add-in within Microsoft Word for the first time.

  1. Action: Student opens the CompuGrade taskpane in MS Word.
  2. System: The React app (staging-MS-addin) loads Home.jsx.
  3. Action: Student enters their email address and password and clicks "Log In".
  4. System (Edge): The add-in fires a GET request to auto-router at /route?email=student@example.com.
  5. System (Auto-Router): Looks up the email against known Open edX Studio clusters (/myplugin/students/by-email/).
  6. System (Auto-Router): Returns the specific backend_url (tenant URL) for that student's district.
  7. System (Auth): The add-in sends a POST /api/openedx/user/login_edx_user to the computency learning API.
  8. System (computency): Proxies the credentials to Open edX (LOGIN_BASE_URL) using a password grant.
  9. System (Open edX): Validates credentials and returns a JWT access and refresh token.
  10. System (Client): The add-in stores the JWTs in localStorage and configures the axios interceptor to attach Authorization: Bearer <token> to all future requests.
  11. System (Client): The add-in requests the student's lessons via POST /api/openedx/get_all_rubrics_for_course.
  12. UI Update: Taskpane renders the Course Dashboard with the student's Grade Avg and Course Progress.

2. Document Autograding Pipeline (The Core Loop)

Persona: Student
Context: The student has started an assessment (e.g., "Unit 1.1 Word L1"), the 10:00 timer is ticking, and they want to check their work on the formatting instructions.

  1. Action: Student clicks "Check Work" in the taskpane.
  2. System (Client): Office.js extracts the current document state and converts it to a base64 string.
  3. System (Client): Fires POST /api/openedx/compare_images_and_highlight_fast to computency.
  4. System (computency): Validates the JWT (without signature verification for speed) and identifies the user via get_current_user.
  5. System (Interop - Optional): If configured, computency sends the base64 string to the Windows COM service (POST /api/DocumentConversion/convert-to-pdf) to generate a PDF snapshot.
  6. System (Storage): computency uploads the raw student artifact to AWS S3.
  7. System (Client): The add-in establishes a Server-Sent Events (SSE) connection (compare_images_and_highlight_sse) to listen for real-time grading updates.
  8. System (computency): Routes the document to the .NET 8 XML Grading Engine (DocDiff) via POST /api/DocumentComparison/compare-word.
  9. System (DocDiff): Uses OpenXml/DiffPlex to structurally compare the student's XML against the teacher's answer key XML.
  10. System (DocDiff): Returns highlighted document images (as base64), specific error codes, and an overallInstructionScore.
  11. System (computency): Saves the generated comparison images to AWS S3.
  12. System (computency): Updates the MySQL database, upserting a RubricItemStatus record with the new score and S3 paths.
  13. System (computency): Pushes the final score, error codes, and S3 presigned URLs back down the SSE stream to the client.
  14. UI Update: The Document Comparison full-page view opens, allowing the student to toggle between "Side-by-Side", "Drag & Drop", and "More Details" (Error Analysis table).

3. Lesson Submission & Gradebook Sync

Persona: Student
Context: The student is ready to submit the final assessment. They have answered the multiple-choice questions in the Active Assessment View.

  1. Action: Student clicks "Submit" at the bottom of the active assessment panel.
  2. UI Update: A confirmation modal warns the student they cannot change answers after submitting. Student clicks to confirm.
  3. System (Client): Sends POST /api/openedx/save_edx_rubric_score.
  4. System (computency): Evaluates any remaining objective-based (OB) items (e.g., Multiple Choice).
  5. System (computency): Averages the scores from all image comparisons and objective questions.
  6. System (computency): Applies the weightage defined in the SubRubric table.
  7. System (computency): Updates the user's overall RubricStatus in the database.
  8. System (computency): Fires decrease_edx_rubric_attempts to log the attempt.
  9. System (computency): Emits an http.request_completed telemetry event via OpenTelemetry/SigNoz.
  10. UI Update: Student sees the Grade Summary table showing their Final Grade percentage, with green checks/red X's next to each weighted rubric item.

4. Admin Provisioning a New Classroom

Persona: District Admin
Context: A district admin needs to roll out CompuGrade to a new school.

  1. Action: Admin logs into staging-api.dashboard.compugrade.com using Avatari SSO.
  2. UI Update: The React frontend checks the UserRole and renders the District Admin ProtectedRoute layout.
  3. Action: Admin navigates to Classes -> Create New Class and clicks Submit.
  4. System (Dashboard FE): Sends POST /api/districts/openedx/classes.
  5. System (Dashboard BE): Verifies the Admin's Avatari JWT.
  6. System (Dashboard BE): Retrieves standard client credentials to authenticate directly with Open edX Studio.
  7. System (Dashboard BE): Sends a server-to-server request to the CMS Plugin (POST {STUDIO}/myplugin/classrooms/).
  8. System (CMS Plugin): Creates the Django Classroom model inside the Open edX database.
  9. System (CMS Plugin): Fires a webhook back to the Dashboard BE (POST /api/districts/openedx/seats/consume) to deduct from the district's purchased seat inventory.
  10. UI Update: The dashboard refreshes the class list, showing the newly provisioned Open edX classroom.

5. Super Admin District Onboarding

Persona: Super Admin
Context: A Super Admin is setting up a brand-new school district and configuring its Clever/ClassLink SSO integration.

  1. Action: Super Admin clicks "+ Add New District" and enters name, state, and seat capacity.
  2. System (Dashboard BE): Creates a new District record in the master SQL database.
  3. Action: Super Admin configures SSO (e.g., Clever) by pasting the Client ID and Secret.
  4. System (Dashboard BE): Encrypts the Client Secret and stores the OAuth configuration for this tenant.
  5. Action: Super Admin assigns the first District Admin user via email.
  6. System (Dashboard BE): Provisions the user account, assigns the DISTRICT_ADMIN role, and dispatches an invitation email via the email provider.

6. Teacher Course Authoring (AI Writer Engine)

Persona: Teacher / Course Builder
Context: A teacher is creating a new autograded Word assignment in Open edX Studio using the CompuGrade AI Writer Engine.

  1. Action: Teacher opens an Open edX Studio course unit and clicks "Add Advanced Component -> CompuGrade".
  2. Action: Teacher clicks "Edit" on the block, launching the Writer Engine React UI.
  3. Action: Teacher uploads a completed .docx "Answer Key".
  4. System (CMS Plugin): The backend saves the document to S3.
  5. System (CMS Plugin): Parses the XML of the document to extract bolding, tables, and colors.
  6. System (CMS Plugin): Feeds the document structure to the LLM (OpenRouter) to generate human-readable instructions and map them to strict grading rubrics.
  7. System (CMS Plugin): Returns the generated JSON rubric to the Studio UI.
  8. Action: Teacher reviews the instructions, tweaks point values, and clicks "Save".
  9. System (CMS Plugin): Saves the Rubric and SubRubric definitions to the Open edX Django database, making the lesson ready for students.

7. School Admin Reporting & Rostering

Persona: School Admin
Context: A principal or school-level administrator is checking student performance and ensuring teachers are correctly assigned to classes.

  1. Action: School Admin logs into staging-api.dashboard.compugrade.com using SSO.
  2. System (Dashboard FE): Parses the UserRole and scopes all API requests exclusively to their assigned schoolId.
  3. UI Update: Dashboard loads showing School-specific KPI cards (Purchased Seats vs Used Seats).
  4. Action: Admin clicks "Reports" -> "Grade Report" and clicks "Generate".
  5. System (Dashboard BE): Runs an aggregated query against the synced Open edX analytics database, restricted to the school's classes.
  6. UI Update: A table populates with the final scores of all students in that school.
  7. Action: Admin clicks "Users" -> "Teachers" -> "+ Invite Teacher" to add a new staff member.
  8. System (Dashboard BE): Registers the teacher in the database, associates them with the schoolId, and triggers an automated welcome email.