# wongcyrus/ai-handwrite-grader architecture

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

- Interactive diagram: https://gitdiagram.com/wongcyrus/ai-handwrite-grader
- Repository: https://github.com/wongcyrus/ai-handwrite-grader

## Overview

AI-Handwriting-Grader is an educator-led workflow for preparing scanned assignments, grading question by question in a local web interface, and producing and returning scored work. The README documents the notebook stages; sampled source confirms the Flask marking server and browser-side mark/control persistence. Notebook implementation was not sampled, so those links reflect the documented workflow rather than inspected calls.

Main entry points: [`server.py`](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/server.py) (Flask marking server), [`notebbooks/email_score.ipynb`](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/email_score.ipynb) (Email delivery), [`notebbooks/scoring_preprocessing.ipynb`](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_preprocessing.ipynb) (Scoring preparation), [`templates`](https://github.com/wongcyrus/ai-handwrite-grader/tree/main/templates) (Marking website)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Assignment preparation"]
  node_scans["Scanned scripts"]
  node_class_template["Class and answers"]
  node_annotations["Question annotations"]
  node_preprocessing["Scoring preparation"]
end

subgraph group_grading["Marking workflow"]
  node_marking_ui["Marking website"]
  node_question_view["Question view<br/>[question.js]"]
  node_browser_state["Mark and controls<br/>[common.js]"]
  node_server["Flask marking server<br/>[server.py]"]
  node_mark_files[("Saved marks")]
end

subgraph group_results["Reporting and return"]
  node_postvalidation["Post-validation"]
  node_reports["Score reports"]
  node_annotated_scripts["Annotated scripts"]
  node_email["Email delivery<br/>[email_score.ipynb]"]
end

node_educator(("Educator"))
node_students(("Students"))
node_smtp["Gmail SMTP"]

node_educator -->|"uploads scans"| node_scans
node_educator -->|"prepares roster"| node_class_template
node_scans -->|"annotates questions"| node_annotations
node_class_template -->|"provides answers"| node_preprocessing
node_annotations -->|"prepares scoring"| node_preprocessing
node_preprocessing -->|"generates website"| node_marking_ui
node_educator -->|"starts server"| node_server
node_server -->|"serves pages"| node_marking_ui
node_marking_ui -.->|"renders questions"| node_question_view
node_educator -->|"enters marks"| node_browser_state
node_browser_state -->|"posts mark data"| node_server
node_server -->|"writes JSON"| node_mark_files
node_educator -->|"checks missing answers"| node_postvalidation
node_mark_files -.->|"validates saved marks"| node_postvalidation
node_educator -->|"generates results"| node_reports
node_reports -->|"creates annotated work"| node_annotated_scripts
node_educator -->|"sends scripts"| node_email
node_email -->|"returns scripts"| node_students
node_email -.->|"uses mail service"| node_smtp

click node_scans "https://github.com/wongcyrus/ai-handwrite-grader/tree/main/data"
click node_class_template "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/NamelistAndAnswerTemplate.xlsx"
click node_annotations "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/question_annotations.ipynb"
click node_preprocessing "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_preprocessing.ipynb"
click node_marking_ui "https://github.com/wongcyrus/ai-handwrite-grader/tree/main/templates"
click node_question_view "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/templates/questions/question.js"
click node_browser_state "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/templates/javascript/common.js"
click node_server "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/server.py"
click node_mark_files "https://github.com/wongcyrus/ai-handwrite-grader/tree/main/data"
click node_postvalidation "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_preprocessing.ipynb"
click node_reports "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_postporcessing.ipynb"
click node_annotated_scripts "https://github.com/wongcyrus/ai-handwrite-grader/tree/main/data"
click node_email "https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/email_score.ipynb"

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_scans,node_class_template,node_annotations,node_preprocessing toneBlue
class node_marking_ui,node_question_view,node_browser_state,node_server,node_mark_files toneAmber
class node_postvalidation,node_reports,node_annotated_scripts,node_email toneMint
class node_educator,node_students,node_smtp toneIndigo
```

## Components

### Assignment preparation

- [Scanned scripts](https://github.com/wongcyrus/ai-handwrite-grader/tree/main/data): `data`
- [Class and answers](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/NamelistAndAnswerTemplate.xlsx): `NamelistAndAnswerTemplate.xlsx`
- [Question annotations](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/question_annotations.ipynb): `notebbooks/question_annotations.ipynb`
- [Scoring preparation](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_preprocessing.ipynb): `notebbooks/scoring_preprocessing.ipynb`

### Marking workflow

- [Marking website](https://github.com/wongcyrus/ai-handwrite-grader/tree/main/templates): `templates`
- [Question view](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/templates/questions/question.js): `templates/questions/question.js`
- [Mark and controls](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/templates/javascript/common.js): `templates/javascript/common.js`
- [Flask marking server](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/server.py): `server.py`
- [Saved marks](https://github.com/wongcyrus/ai-handwrite-grader/tree/main/data): `data`

### Reporting and return

- [Post-validation](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_preprocessing.ipynb): `notebbooks/scoring_preprocessing.ipynb`
- [Score reports](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/scoring_postporcessing.ipynb): `notebbooks/scoring_postporcessing.ipynb`
- [Annotated scripts](https://github.com/wongcyrus/ai-handwrite-grader/tree/main/data): `data`
- [Email delivery](https://github.com/wongcyrus/ai-handwrite-grader/blob/main/notebbooks/email_score.ipynb): `notebbooks/email_score.ipynb`

### Other components

- **Educator**
- **Students**
- **Gmail SMTP**

## Connections

- Educator → Scanned scripts: uploads scans (evidence: `README.md`)
- Educator → Class and answers: prepares roster (evidence: `README.md`)
- Scanned scripts → Question annotations: annotates questions (evidence: `README.md`)
- Class and answers → Scoring preparation: provides answers (evidence: `README.md`)
- Question annotations → Scoring preparation: prepares scoring (evidence: `README.md`)
- Scoring preparation → Marking website: generates website (evidence: `README.md`)
- Educator → Flask marking server: starts server (evidence: `README.md`)
- Flask marking server → Marking website: serves pages (evidence: `server.py`)
- Marking website → Question view: renders questions
- Educator → Mark and controls: enters marks (evidence: `templates/javascript/common.js`)
- Mark and controls → Flask marking server: posts mark data (evidence: `templates/javascript/common.js`)
- Flask marking server → Saved marks: writes JSON (evidence: `server.py`)
- Educator → Post-validation: checks missing answers (evidence: `README.md`)
- Saved marks → Post-validation: validates saved marks
- Educator → Score reports: generates results (evidence: `README.md`)
- Score reports → Annotated scripts: creates annotated work (evidence: `README.md`)
- Educator → Email delivery: sends scripts (evidence: `README.md`)
- Email delivery → Students: returns scripts (evidence: `README.md`)
- Email delivery → Gmail SMTP: uses mail service (evidence: `README.md`)
