# kb-dhanush/inkgrader architecture

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

- Interactive diagram: https://gitdiagram.com/kb-dhanush/inkgrader
- Repository: https://github.com/kb-dhanush/inkgrader

## Overview

InkGrader accepts exam questions, reference material, and student-answer scans, extracts structured content, then grades answers and streams score updates. Its primary authenticated web workflow is served by the React frontend and FastAPI backend; a separate demo frontend submits a single answer for evaluation. The README describes OCR, agent grading, and JWT authentication, while sampled source confirms route orchestration, MongoDB access, OCR.Space integration, and Redis-backed updates. FileProcessor internals and several agent integrations were not sampled, so their detailed wiring is omitted.

Main entry points: [`backend/routes.py`](https://github.com/kb-dhanush/inkgrader/blob/main/backend/routes.py) (Exam and grading routes), [`backend/app.py`](https://github.com/kb-dhanush/inkgrader/blob/main/backend/app.py) (FastAPI application), [`backend/FileProcessor/utils.py`](https://github.com/kb-dhanush/inkgrader/blob/main/backend/FileProcessor/utils.py) (Document processing), [`backend/Auth/routes.py`](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Auth/routes.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interfaces"]
  node_frontend["Main web app<br/>[App.jsx]"]
  node_landing["Landing page<br/>[LandingPage.jsx]"]
  node_loginpage["Login and signup<br/>[LoginSignUp.jsx]"]
  node_demo["Single-answer demo<br/>[App.jsx]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[app.py]"]
  node_examroutes["Exam and grading routes<br/>[routes.py]"]
  node_authroutes["Authentication routes<br/>[routes.py]"]
  node_authutils["JWT and password utilities<br/>[utils.py]"]
end

subgraph group_processing["Document processing"]
  node_fileproc["Document processing<br/>[utils.py]"]
  node_ocr["OCR.Space client<br/>[__init__.py]"]
  node_extractagent["Extraction agent"]
end

subgraph group_grading["Evaluation"]
  node_gradingagent["Grading agent<br/>[grading_agent.py]"]
  node_agenttools["Retrieval and search tools<br/>[tools.py]"]
  node_rag["Text chunking and embeddings<br/>[rag_pipeline.py]"]
end

subgraph group_state["State and messaging"]
  node_mongo[("MongoDB")]
  node_redis["Redis pub/sub<br/>[redis_pubsub.py]"]
end

node_user(("Teacher or user"))
node_ocrservice["OCR.Space API"]
node_reference["Reference search services"]

node_user -->|"browses"| node_landing
node_landing -->|"opens login"| node_loginpage
node_user -->|"authenticates"| node_loginpage
node_loginpage -->|"calls auth API"| node_app
node_app -->|"dispatches auth"| node_authroutes
node_authroutes -->|"uses tokens"| node_authutils
node_authroutes -->|"reads/writes users"| node_mongo
node_user -->|"submits exam"| node_frontend
node_frontend -->|"calls exam API"| node_app
node_app -->|"dispatches exams"| node_examroutes
node_examroutes -->|"processes uploads"| node_fileproc
node_fileproc -->|"requests OCR"| node_ocr
node_ocr -->|"sends images"| node_ocrservice
node_fileproc -->|"extracts content"| node_extractagent
node_fileproc -->|"stores extracted data"| node_mongo
node_examroutes -->|"reads exam data"| node_mongo
node_examroutes -->|"grades answers"| node_gradingagent
node_gradingagent -->|"retrieves context"| node_agenttools
node_agenttools -->|"embeds text"| node_rag
node_agenttools -.->|"searches references"| node_reference
node_gradingagent -->|"updates marks"| node_mongo
node_examroutes -->|"publishes progress"| node_redis
node_redis -->|"delivers events"| node_examroutes
node_examroutes -->|"loads graded totals"| node_mongo
node_user -->|"uploads answer"| node_demo
node_demo -->|"posts demo request"| node_app
node_app -->|"dispatches demo"| node_examroutes

click node_frontend "https://github.com/kb-dhanush/inkgrader/blob/main/frontend/src/App.jsx"
click node_landing "https://github.com/kb-dhanush/inkgrader/blob/main/frontend/src/pages/LandingPage.jsx"
click node_loginpage "https://github.com/kb-dhanush/inkgrader/blob/main/frontend/src/pages/LoginSignUp.jsx"
click node_demo "https://github.com/kb-dhanush/inkgrader/blob/main/demo-frontend/src/App.jsx"
click node_app "https://github.com/kb-dhanush/inkgrader/blob/main/backend/app.py"
click node_examroutes "https://github.com/kb-dhanush/inkgrader/blob/main/backend/routes.py"
click node_authroutes "https://github.com/kb-dhanush/inkgrader/blob/main/backend/Auth/routes.py"
click node_authutils "https://github.com/kb-dhanush/inkgrader/blob/main/backend/Auth/utils.py"
click node_fileproc "https://github.com/kb-dhanush/inkgrader/blob/main/backend/FileProcessor/utils.py"
click node_ocr "https://github.com/kb-dhanush/inkgrader/blob/main/backend/FileProcessor/__init__.py"
click node_extractagent "https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/extraction_agent.py"
click node_gradingagent "https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/grading_agent.py"
click node_agenttools "https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/tools.py"
click node_rag "https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/rag_pipeline.py"
click node_redis "https://github.com/kb-dhanush/inkgrader/blob/main/backend/redis_pubsub.py"

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_frontend,node_landing,node_loginpage,node_demo,node_user toneBlue
class node_app,node_examroutes,node_authroutes,node_authutils toneAmber
class node_fileproc,node_ocr,node_extractagent,node_ocrservice toneMint
class node_gradingagent,node_agenttools,node_rag toneRose
class node_mongo,node_redis,node_reference toneIndigo
```

## Components

### Web interfaces

- [Main web app](https://github.com/kb-dhanush/inkgrader/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Landing page](https://github.com/kb-dhanush/inkgrader/blob/main/frontend/src/pages/LandingPage.jsx): `frontend/src/pages/LandingPage.jsx`
- [Login and signup](https://github.com/kb-dhanush/inkgrader/blob/main/frontend/src/pages/LoginSignUp.jsx): `frontend/src/pages/LoginSignUp.jsx`
- [Single-answer demo](https://github.com/kb-dhanush/inkgrader/blob/main/demo-frontend/src/App.jsx): `demo-frontend/src/App.jsx`

### API and identity

- [FastAPI application](https://github.com/kb-dhanush/inkgrader/blob/main/backend/app.py): `backend/app.py`
- [Exam and grading routes](https://github.com/kb-dhanush/inkgrader/blob/main/backend/routes.py): `backend/routes.py`
- [Authentication routes](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Auth/routes.py): `backend/Auth/routes.py`
- [JWT and password utilities](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Auth/utils.py): `backend/Auth/utils.py`

### Document processing

- [Document processing](https://github.com/kb-dhanush/inkgrader/blob/main/backend/FileProcessor/utils.py): `backend/FileProcessor/utils.py`
- [OCR.Space client](https://github.com/kb-dhanush/inkgrader/blob/main/backend/FileProcessor/__init__.py): `backend/FileProcessor/__init__.py`
- [Extraction agent](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/extraction_agent.py): `backend/Agents/extraction_agent.py`

### Evaluation

- [Grading agent](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/grading_agent.py): `backend/Agents/grading_agent.py`
- [Retrieval and search tools](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/tools.py): `backend/Agents/tools.py`
- [Text chunking and embeddings](https://github.com/kb-dhanush/inkgrader/blob/main/backend/Agents/rag_pipeline.py): `backend/Agents/rag_pipeline.py`

### State and messaging

- **MongoDB**
- [Redis pub/sub](https://github.com/kb-dhanush/inkgrader/blob/main/backend/redis_pubsub.py): `backend/redis_pubsub.py`

### Other components

- **Teacher or user**
- **OCR.Space API**
- **Reference search services**

## Connections

- Teacher or user → Landing page: browses
- Landing page → Login and signup: opens login
- Teacher or user → Login and signup: authenticates
- Login and signup → FastAPI application: calls auth API
- FastAPI application → Authentication routes: dispatches auth
- Authentication routes → JWT and password utilities: uses tokens
- Authentication routes → MongoDB: reads/writes users
- Teacher or user → Main web app: submits exam
- Main web app → FastAPI application: calls exam API
- FastAPI application → Exam and grading routes: dispatches exams
- Exam and grading routes → Document processing: processes uploads
- Document processing → OCR.Space client: requests OCR
- OCR.Space client → OCR.Space API: sends images
- Document processing → Extraction agent: extracts content
- Document processing → MongoDB: stores extracted data
- Exam and grading routes → MongoDB: reads exam data
- Exam and grading routes → Grading agent: grades answers
- Grading agent → Retrieval and search tools: retrieves context
- Retrieval and search tools → Text chunking and embeddings: embeds text
- Retrieval and search tools → Reference search services: searches references
- Grading agent → MongoDB: updates marks
- Exam and grading routes → Redis pub/sub: publishes progress
- Redis pub/sub → Exam and grading routes: delivers events
- Exam and grading routes → MongoDB: loads graded totals
- Teacher or user → Single-answer demo: uploads answer
- Single-answer demo → FastAPI application: posts demo request
- FastAPI application → Exam and grading routes: dispatches demo