# saagarrk/intelligrade architecture

> Architecture diagram of the GitHub repository saagarrk/intelligrade, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saagarrk/intelligrade
- Repository: https://github.com/saagarrk/intelligrade

## Overview

IntelliGrade automates handwritten exam evaluation: a student uploads an answer sheet, the system preprocesses and digitizes it, scores extracted answers against exam rubrics, and presents results for teacher review and student feedback. The README describes a React/Express gateway, Spring Boot institutional backend, and FastAPI vision service; sampled code also shows a TypeScript handwritten-processing engine calling Gemini OCR. The README documents the five evaluation stages and MySQL, while the excerpts do not establish every runtime connection or storage implementation, so those relationships are cited to the README.

Main entry points: [`backend/src/main/java/com/intelligrade/service/impl/GradingPipelineServiceImpl.java`](https://github.com/saagarrk/intelligrade/blob/main/backend/src/main/java/com/intelligrade/service/impl/GradingPipelineServiceImpl.java) (Institutional Backend), [`server.ts`](https://github.com/saagarrk/intelligrade/blob/main/server.ts) (REST Gateway), [`src/components/TeacherEvaluationReviewWorkspace.jsx`](https://github.com/saagarrk/intelligrade/blob/main/src/components/TeacherEvaluationReviewWorkspace.jsx) (Teacher Review), [`src/App.jsx`](https://github.com/saagarrk/intelligrade/blob/main/src/App.jsx) (Role Workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Workspaces"]
  node_react["Role Workspaces<br/>[App.jsx]"]
  node_upload["Answer Upload"]
  node_pipelineui["Pipeline View"]
end

subgraph group_gateway["API Gateway"]
  node_gatewayapi["REST Gateway<br/>[server.ts]"]
  node_handwritten["Document Workflow"]
  node_resultapi["Results API<br/>[result.routes.ts]"]
end

subgraph group_core["Institutional Core"]
  node_spring["Institutional Backend"]
  node_records[("Submission Records")]
end

subgraph group_vision["Vision And Scoring"]
  node_preprocess["Image Preprocessing"]
  node_ocr["Handwriting OCR<br/>[ocr_service.py]"]
  node_rubric["Rubric Evaluation"]
  node_feedback["Formative Feedback"]
end

subgraph group_review["Review And Insights"]
  node_teacherreview["Teacher Review"]
  node_results["Student Results"]
  node_analytics["Academic Analytics"]
  node_pdf["Evaluation Reports<br/>[pdfExport.js]"]
end

node_student(("Student / Teacher"))
node_gemini{{"Gemini Vision"}}
node_mysql[("MySQL Database")]

node_student -->|"uses"| node_react
node_react -->|"submits scans"| node_upload
node_upload -->|"uploads to"| node_gatewayapi
node_gatewayapi -->|"routes requests"| node_spring
node_spring -->|"requests vision work"| node_preprocess
node_preprocess -.->|"prepares scans"| node_ocr
node_ocr -->|"recognizes handwriting"| node_gemini
node_handwritten -->|"invokes OCR"| node_gemini
node_spring -->|"requests scoring"| node_rubric
node_rubric -->|"generates guidance"| node_feedback
node_spring -.->|"persists evaluations"| node_records
node_spring -->|"stores institutional data"| node_mysql
node_spring -->|"returns evaluations"| node_teacherreview
node_teacherreview -->|"finalizes marks"| node_results
node_gatewayapi -.->|"serves results"| node_resultapi
node_resultapi -->|"reads submissions"| node_records
node_results -->|"displays performance"| node_analytics
node_teacherreview -->|"exports reports"| node_pdf
node_pipelineui -.->|"shows pipeline status"| node_handwritten

click node_react "https://github.com/saagarrk/intelligrade/blob/main/src/App.jsx"
click node_upload "https://github.com/saagarrk/intelligrade/blob/main/src/components/HandwrittenUploadWorkflow.jsx"
click node_pipelineui "https://github.com/saagarrk/intelligrade/blob/main/src/components/HandwrittenPipelineView.jsx"
click node_gatewayapi "https://github.com/saagarrk/intelligrade/blob/main/server.ts"
click node_handwritten "https://github.com/saagarrk/intelligrade/blob/main/src/backend/handwrittenPipelineEngine.ts"
click node_spring "https://github.com/saagarrk/intelligrade/blob/main/backend/src/main/java/com/intelligrade/service/impl/GradingPipelineServiceImpl.java"
click node_records "https://github.com/saagarrk/intelligrade/blob/main/backend/src/main/java/com/intelligrade/entity/SubmissionEntity.java"
click node_resultapi "https://github.com/saagarrk/intelligrade/blob/main/src/server/routes/result.routes.ts"
click node_preprocess "https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/preprocessing_service.py"
click node_ocr "https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/ocr_service.py"
click node_rubric "https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/evaluation_service.py"
click node_feedback "https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/feedback_service.py"
click node_teacherreview "https://github.com/saagarrk/intelligrade/blob/main/src/components/TeacherEvaluationReviewWorkspace.jsx"
click node_results "https://github.com/saagarrk/intelligrade/blob/main/src/components/student/StudentResultsAndFeedback.jsx"
click node_analytics "https://github.com/saagarrk/intelligrade/blob/main/src/components/analytics/AcademicAnalyticsModule.jsx"
click node_pdf "https://github.com/saagarrk/intelligrade/blob/main/src/utils/pdfExport.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_react,node_upload,node_pipelineui toneBlue
class node_gatewayapi,node_handwritten,node_resultapi,node_mysql toneAmber
class node_spring,node_records toneMint
class node_preprocess,node_ocr,node_rubric,node_feedback toneRose
class node_teacherreview,node_results,node_analytics,node_pdf,node_student,node_gemini toneIndigo
```

## Components

### Web Workspaces

- [Role Workspaces](https://github.com/saagarrk/intelligrade/blob/main/src/App.jsx): `src/App.jsx`
- [Answer Upload](https://github.com/saagarrk/intelligrade/blob/main/src/components/HandwrittenUploadWorkflow.jsx): `src/components/HandwrittenUploadWorkflow.jsx`
- [Pipeline View](https://github.com/saagarrk/intelligrade/blob/main/src/components/HandwrittenPipelineView.jsx): `src/components/HandwrittenPipelineView.jsx`

### API Gateway

- [REST Gateway](https://github.com/saagarrk/intelligrade/blob/main/server.ts): `server.ts`
- [Document Workflow](https://github.com/saagarrk/intelligrade/blob/main/src/backend/handwrittenPipelineEngine.ts): `src/backend/handwrittenPipelineEngine.ts`
- [Results API](https://github.com/saagarrk/intelligrade/blob/main/src/server/routes/result.routes.ts): `src/server/routes/result.routes.ts`

### Institutional Core

- [Institutional Backend](https://github.com/saagarrk/intelligrade/blob/main/backend/src/main/java/com/intelligrade/service/impl/GradingPipelineServiceImpl.java): `backend/src/main/java/com/intelligrade/service/impl/GradingPipelineServiceImpl.java`
- [Submission Records](https://github.com/saagarrk/intelligrade/blob/main/backend/src/main/java/com/intelligrade/entity/SubmissionEntity.java): `backend/src/main/java/com/intelligrade/entity/SubmissionEntity.java`

### Vision And Scoring

- [Image Preprocessing](https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/preprocessing_service.py): `ai-service/app/services/preprocessing_service.py`
- [Handwriting OCR](https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/ocr_service.py): `ai-service/app/services/ocr_service.py`
- [Rubric Evaluation](https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/evaluation_service.py): `ai-service/app/services/evaluation_service.py`
- [Formative Feedback](https://github.com/saagarrk/intelligrade/blob/main/ai-service/app/services/feedback_service.py): `ai-service/app/services/feedback_service.py`

### Review And Insights

- [Teacher Review](https://github.com/saagarrk/intelligrade/blob/main/src/components/TeacherEvaluationReviewWorkspace.jsx): `src/components/TeacherEvaluationReviewWorkspace.jsx`
- [Student Results](https://github.com/saagarrk/intelligrade/blob/main/src/components/student/StudentResultsAndFeedback.jsx): `src/components/student/StudentResultsAndFeedback.jsx`
- [Academic Analytics](https://github.com/saagarrk/intelligrade/blob/main/src/components/analytics/AcademicAnalyticsModule.jsx): `src/components/analytics/AcademicAnalyticsModule.jsx`
- [Evaluation Reports](https://github.com/saagarrk/intelligrade/blob/main/src/utils/pdfExport.js): `src/utils/pdfExport.js`

### Other components

- **Student / Teacher**
- **Gemini Vision**
- **MySQL Database**

## Connections

- Student / Teacher → Role Workspaces: uses
- Role Workspaces → Answer Upload: submits scans (evidence: `src/App.jsx`)
- Answer Upload → REST Gateway: uploads to
- REST Gateway → Institutional Backend: routes requests
- Institutional Backend → Image Preprocessing: requests vision work
- Image Preprocessing → Handwriting OCR: prepares scans
- Handwriting OCR → Gemini Vision: recognizes handwriting
- Document Workflow → Gemini Vision: invokes OCR (evidence: `src/backend/handwrittenPipelineEngine.ts`)
- Institutional Backend → Rubric Evaluation: requests scoring
- Rubric Evaluation → Formative Feedback: generates guidance
- Institutional Backend → Submission Records: persists evaluations (evidence: `backend/src/main/java/com/intelligrade/service/impl/GradingPipelineServiceImpl.java`)
- Institutional Backend → MySQL Database: stores institutional data
- Institutional Backend → Teacher Review: returns evaluations
- Teacher Review → Student Results: finalizes marks
- REST Gateway → Results API: serves results
- Results API → Submission Records: reads submissions (evidence: `src/server/routes/result.routes.ts`)
- Student Results → Academic Analytics: displays performance
- Teacher Review → Evaluation Reports: exports reports
- Pipeline View → Document Workflow: shows pipeline status