# codie-ds/gradeflow-ai architecture

> Architecture diagram of the GitHub repository codie-ds/gradeflow-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codie-ds/gradeflow-ai
- Repository: https://github.com/codie-ds/gradeflow-ai

## Overview

GradeFlow-AI lets educators define assignments, generate or edit rubric criteria, upload handwritten PDF submissions, and receive OCR-backed rubric scores with evidence and confidence indicators for human review. The main runtime path runs from the assignment/upload interface through FastAPI routes and a background grading pipeline to persisted results, which the interface retrieves for inspection. The graph preserves the documented multimodal OCR and audit capabilities; their implementation details are not fully shown in the sampled source, so those links are documented rather than asserted from code.

Main entry points: [`frontend/src/api.js`](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/api.js) (HTTP API client), [`frontend/src/App.jsx`](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/App.jsx) (Page routing), [`backend/app/routes/assignments.py`](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/routes/assignments.py) (Assignment endpoints), [`backend/app/services/pipeline.py`](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/pipeline.py) (Submission pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Educator interface"]
  node_app["Page routing<br/>[App.jsx]"]
  node_dashboard["Assignment dashboard<br/>[Dashboard.jsx]"]
  node_create["Assignment setup"]
  node_assignment["Assignment workspace<br/>[AssignmentPage.jsx]"]
  node_result["Results review<br/>[ResultPage.jsx]"]
  node_api_client["HTTP API client<br/>[api.js]"]
  node_shared_ui["Status and score UI<br/>[ui.jsx]"]
end

subgraph group_api["Application API"]
  node_assignment_routes["Assignment endpoints<br/>[assignments.py]"]
  node_submission_routes["Submission endpoints<br/>[submissions.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

subgraph group_grading["Grading services"]
  node_pipeline["Submission pipeline<br/>[pipeline.py]"]
  node_ocr["PDF OCR extraction<br/>[ocr.py]"]
  node_grader["Rubric-based grading<br/>[grader.py]"]
  node_rubric["Rubric generation<br/>[rubric.py]"]
  node_gemma_client["Gemma JSON client<br/>[gemma_client.py]"]
end

subgraph group_state["Persistence"]
  node_database[("Assignment and result data<br/>[db.py]")]
end

node_faculty(("Educator"))
node_supabase[("Supabase storage and database")]
node_qwen{{"Qwen vision model"}}

node_faculty -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_create
node_app -->|"routes to"| node_assignment
node_app -->|"routes to"| node_result
node_create -->|"calls"| node_api_client
node_dashboard -->|"calls"| node_api_client
node_assignment -->|"calls"| node_api_client
node_result -->|"calls"| node_api_client
node_assignment -->|"renders"| node_shared_ui
node_result -->|"renders"| node_shared_ui
node_api_client -->|"HTTP requests"| node_assignment_routes
node_api_client -->|"HTTP requests"| node_submission_routes
node_assignment_routes -->|"validates with"| node_schemas
node_submission_routes -->|"serializes with"| node_schemas
node_assignment_routes -->|"reads and writes"| node_database
node_assignment_routes -->|"generates criteria"| node_rubric
node_assignment_routes -->|"schedules"| node_pipeline
node_submission_routes -->|"reads"| node_database
node_pipeline -->|"loads and saves"| node_database
node_pipeline -->|"extracts pages"| node_ocr
node_pipeline -->|"grades extraction"| node_grader
node_grader -->|"requests evaluation"| node_gemma_client
node_rubric -->|"requests criteria"| node_gemma_client
node_database -->|"queries and stores files"| node_supabase
node_ocr -.->|"extracts multimodal content"| node_qwen
node_faculty -.->|"audits scores"| node_result

click node_app "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/Dashboard.jsx"
click node_create "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/CreateAssignment.jsx"
click node_assignment "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/AssignmentPage.jsx"
click node_result "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/ResultPage.jsx"
click node_api_client "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/api.js"
click node_shared_ui "https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/components/ui.jsx"
click node_assignment_routes "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/routes/assignments.py"
click node_submission_routes "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/routes/submissions.py"
click node_schemas "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/schemas.py"
click node_pipeline "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/pipeline.py"
click node_ocr "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/ocr.py"
click node_grader "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/grader.py"
click node_rubric "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/rubric.py"
click node_gemma_client "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/gemma_client.py"
click node_database "https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/db.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_app,node_dashboard,node_create,node_assignment,node_result,node_api_client,node_shared_ui toneBlue
class node_assignment_routes,node_submission_routes,node_schemas,node_supabase toneAmber
class node_pipeline,node_ocr,node_grader,node_rubric,node_gemma_client toneMint
class node_database toneRose
class node_faculty,node_qwen toneIndigo
```

## Components

### Educator interface

- [Page routing](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Assignment dashboard](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Assignment setup](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/CreateAssignment.jsx): `frontend/src/pages/CreateAssignment.jsx`
- [Assignment workspace](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/AssignmentPage.jsx): `frontend/src/pages/AssignmentPage.jsx`
- [Results review](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/pages/ResultPage.jsx): `frontend/src/pages/ResultPage.jsx`
- [HTTP API client](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Status and score UI](https://github.com/codie-ds/gradeflow-ai/blob/main/frontend/src/components/ui.jsx): `frontend/src/components/ui.jsx`

### Application API

- [Assignment endpoints](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/routes/assignments.py): `backend/app/routes/assignments.py`
- [Submission endpoints](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/routes/submissions.py): `backend/app/routes/submissions.py`
- [Request and response schemas](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Grading services

- [Submission pipeline](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [PDF OCR extraction](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/ocr.py): `backend/app/services/ocr.py`
- [Rubric-based grading](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/grader.py): `backend/app/services/grader.py`
- [Rubric generation](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/rubric.py): `backend/app/services/rubric.py`
- [Gemma JSON client](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/services/gemma_client.py): `backend/app/services/gemma_client.py`

### Persistence

- [Assignment and result data](https://github.com/codie-ds/gradeflow-ai/blob/main/backend/app/db.py): `backend/app/db.py`

### Other components

- **Educator**
- **Supabase storage and database**
- **Qwen vision model**

## Connections

- Educator → Page routing: uses (evidence: `README.md`)
- Page routing → Assignment dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Assignment setup: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Assignment workspace: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Results review: routes to (evidence: `frontend/src/App.jsx`)
- Assignment setup → HTTP API client: calls (evidence: `frontend/src/pages/CreateAssignment.jsx`)
- Assignment dashboard → HTTP API client: calls (evidence: `frontend/src/pages/Dashboard.jsx`)
- Assignment workspace → HTTP API client: calls (evidence: `frontend/src/pages/AssignmentPage.jsx`)
- Results review → HTTP API client: calls (evidence: `frontend/src/pages/ResultPage.jsx`)
- Assignment workspace → Status and score UI: renders (evidence: `frontend/src/pages/AssignmentPage.jsx`)
- Results review → Status and score UI: renders (evidence: `frontend/src/pages/ResultPage.jsx`)
- HTTP API client → Assignment endpoints: HTTP requests (evidence: `frontend/src/api.js`)
- HTTP API client → Submission endpoints: HTTP requests (evidence: `frontend/src/api.js`)
- Assignment endpoints → Request and response schemas: validates with (evidence: `backend/app/routes/assignments.py`)
- Submission endpoints → Request and response schemas: serializes with (evidence: `backend/app/routes/submissions.py`)
- Assignment endpoints → Assignment and result data: reads and writes (evidence: `backend/app/routes/assignments.py`)
- Assignment endpoints → Rubric generation: generates criteria (evidence: `backend/app/routes/assignments.py`)
- Assignment endpoints → Submission pipeline: schedules (evidence: `backend/app/routes/assignments.py`)
- Submission endpoints → Assignment and result data: reads (evidence: `backend/app/routes/submissions.py`)
- Submission pipeline → Assignment and result data: loads and saves (evidence: `backend/app/services/pipeline.py`)
- Submission pipeline → PDF OCR extraction: extracts pages (evidence: `backend/app/services/pipeline.py`)
- Submission pipeline → Rubric-based grading: grades extraction (evidence: `backend/app/services/pipeline.py`)
- Rubric-based grading → Gemma JSON client: requests evaluation (evidence: `backend/app/services/grader.py`)
- Rubric generation → Gemma JSON client: requests criteria (evidence: `backend/app/services/rubric.py`)
- Assignment and result data → Supabase storage and database: queries and stores files (evidence: `backend/app/db.py`)
- PDF OCR extraction → Qwen vision model: extracts multimodal content (evidence: `README.md`)
- Educator → Results review: audits scores (evidence: `README.md`)
