# maheshc4742/ss architecture

> Architecture diagram of the GitHub repository maheshc4742/ss, 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/maheshc4742/ss
- Repository: https://github.com/maheshc4742/ss

## Overview

ScriptSense evaluates handwritten or JSON student answers, returning rubric-based marks, confidence, and feedback. The principal workflow runs from the web dashboard through evaluation endpoints and an orchestrator that optionally extracts answers with vision OCR, scores semantic alignment, applies rubric grading, and either saves a report or stages answers for human review. Approved annotations feed a threshold-gated, versioned fine-tuning pipeline; model management supports checkpoint activation. The README documents major capabilities not fully visible in excerpts, so those relationships are cited there; other edges use indexed source references.

Main entry points: [`backend/services/evaluator.py`](https://github.com/maheshc4742/ss/blob/main/backend/services/evaluator.py) (Evaluation Orchestrator), [`backend/services/hitl_service.py`](https://github.com/maheshc4742/ss/blob/main/backend/services/hitl_service.py) (HITL Workflow), [`frontend/js/app.js`](https://github.com/maheshc4742/ss/blob/main/frontend/js/app.js) (Web Dashboard), [`backend/main.py`](https://github.com/maheshc4742/ss/blob/main/backend/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web Experience"]
  node_evaluate_api["Evaluate API<br/>[evaluate.py]"]
  node_dashboard["Web Dashboard<br/>[app.js]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["Evaluation Orchestrator<br/>[evaluator.py]"]
  node_grading["Rubric Grading<br/>[grading_module.py]"]
  node_semantic["Semantic Scoring<br/>[semantic_module.py]"]
  node_ocr_factory["OCR Provider Factory<br/>[ocr_factory.py]"]
  node_ocr_base["OCR Interface<br/>[base_ocr.py]"]
  node_gemini["Gemini OCR<br/>[gemini_ocr.py]"]
  node_qwen["Qwen OCR<br/>[qwen_ocr.py]"]
  node_pdf["PDF Rendering<br/>[pdf_utils.py]"]
end

subgraph group_human["Human Review"]
  node_hitl_api["Review API<br/>[hitl.py]"]
  node_hitl_service["HITL Workflow<br/>[hitl_service.py]"]
end

subgraph group_models["Model Improvement"]
  node_training_api["Training API<br/>[training.py]"]
  node_models_api["Model API<br/>[models_api.py]"]
  node_verified_data["Verified Annotations"]
  node_dataset_prep["Dataset Preparation<br/>[prepare_dataset.py]"]
  node_trainer["Fine-Tuning<br/>[train.py]"]
  node_checkpoints["Versioned Checkpoints"]
end

subgraph group_platform["Platform"]
  node_config_api["Configuration API<br/>[config_api.py]"]
  node_database[("Application Database<br/>[database.py]")]
  node_records["Evaluation Records<br/>[database_models.py]"]
  node_model_config["Runtime Settings<br/>[config.py]"]
  node_reports["Evaluation Reports"]
  node_server["FastAPI Application<br/>[main.py]"]
end

node_human_reviewer(("Human Reviewer"))

node_dashboard -.->|"submits evaluations"| node_evaluate_api
node_dashboard -.->|"reviews answers"| node_hitl_api
node_dashboard -.->|"triggers training"| node_training_api
node_dashboard -.->|"activates models"| node_models_api
node_dashboard -.->|"configures settings"| node_config_api
node_server -->|"registers routes"| node_evaluate_api
node_server -->|"registers routes"| node_hitl_api
node_server -->|"registers routes"| node_training_api
node_server -->|"registers routes"| node_models_api
node_server -->|"registers routes"| node_config_api
node_evaluate_api -->|"invokes evaluation"| node_evaluator
node_evaluator -->|"selects provider"| node_ocr_factory
node_ocr_factory -->|"creates provider"| node_gemini
node_ocr_factory -->|"creates provider"| node_qwen
node_gemini -->|"implements interface"| node_ocr_base
node_qwen -->|"implements interface"| node_ocr_base
node_gemini -->|"renders PDF pages"| node_pdf
node_qwen -->|"renders PDF pages"| node_pdf
node_evaluator -->|"scores alignment"| node_semantic
node_evaluator -->|"grades rubric"| node_grading
node_evaluator -->|"stages review"| node_hitl_service
node_evaluator -->|"writes report"| node_reports
node_evaluator -.->|"records evaluation"| node_database
node_hitl_api -->|"starts train evaluation"| node_evaluator
node_hitl_api -->|"handles review actions"| node_hitl_service
node_human_reviewer -.->|"submits decisions"| node_hitl_api
node_hitl_service -->|"updates review records"| node_records
node_hitl_service -->|"quantizes marks"| node_grading
node_hitl_service -.->|"appends approvals"| node_verified_data
node_hitl_service -.->|"persists review state"| node_database
node_database -->|"creates tables"| node_records
node_training_api -->|"triggers fine-tuning"| node_trainer
node_trainer -->|"prepares splits"| node_dataset_prep
node_dataset_prep -->|"loads annotations"| node_verified_data
node_trainer -->|"saves versions"| node_checkpoints
node_models_api -->|"manages registry"| node_records
node_models_api -.->|"updates active model"| node_model_config
node_config_api -->|"reads settings"| node_model_config

click node_evaluator "https://github.com/maheshc4742/ss/blob/main/backend/services/evaluator.py"
click node_grading "https://github.com/maheshc4742/ss/blob/main/backend/services/grading_module.py"
click node_semantic "https://github.com/maheshc4742/ss/blob/main/backend/services/semantic_module.py"
click node_ocr_factory "https://github.com/maheshc4742/ss/blob/main/backend/ocr/ocr_factory.py"
click node_ocr_base "https://github.com/maheshc4742/ss/blob/main/backend/ocr/base_ocr.py"
click node_gemini "https://github.com/maheshc4742/ss/blob/main/backend/ocr/gemini_ocr.py"
click node_qwen "https://github.com/maheshc4742/ss/blob/main/backend/ocr/qwen_ocr.py"
click node_pdf "https://github.com/maheshc4742/ss/blob/main/backend/ocr/pdf_utils.py"
click node_evaluate_api "https://github.com/maheshc4742/ss/blob/main/backend/api/evaluate.py"
click node_hitl_api "https://github.com/maheshc4742/ss/blob/main/backend/api/hitl.py"
click node_training_api "https://github.com/maheshc4742/ss/blob/main/backend/api/training.py"
click node_models_api "https://github.com/maheshc4742/ss/blob/main/backend/api/models_api.py"
click node_config_api "https://github.com/maheshc4742/ss/blob/main/backend/api/config_api.py"
click node_dashboard "https://github.com/maheshc4742/ss/blob/main/frontend/js/app.js"
click node_hitl_service "https://github.com/maheshc4742/ss/blob/main/backend/services/hitl_service.py"
click node_database "https://github.com/maheshc4742/ss/blob/main/backend/core/database.py"
click node_records "https://github.com/maheshc4742/ss/blob/main/backend/models/database_models.py"
click node_verified_data "https://github.com/maheshc4742/ss/blob/main/data/verified_training.jsonl"
click node_dataset_prep "https://github.com/maheshc4742/ss/blob/main/backend/training/prepare_dataset.py"
click node_trainer "https://github.com/maheshc4742/ss/blob/main/backend/training/train.py"
click node_checkpoints "https://github.com/maheshc4742/ss/tree/main/models"
click node_model_config "https://github.com/maheshc4742/ss/blob/main/backend/core/config.py"
click node_reports "https://github.com/maheshc4742/ss/tree/main/reports"
click node_server "https://github.com/maheshc4742/ss/blob/main/backend/main.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_evaluate_api,node_dashboard,node_human_reviewer toneBlue
class node_evaluator,node_grading,node_semantic,node_ocr_factory,node_ocr_base,node_gemini,node_qwen,node_pdf toneAmber
class node_hitl_api,node_hitl_service toneMint
class node_training_api,node_models_api,node_verified_data,node_dataset_prep,node_trainer,node_checkpoints toneRose
class node_config_api,node_database,node_records,node_model_config,node_reports,node_server toneIndigo
```

## Components

### Web Experience

- [Evaluate API](https://github.com/maheshc4742/ss/blob/main/backend/api/evaluate.py): `backend/api/evaluate.py`
- [Web Dashboard](https://github.com/maheshc4742/ss/blob/main/frontend/js/app.js): `frontend/js/app.js`

### Evaluation

- [Evaluation Orchestrator](https://github.com/maheshc4742/ss/blob/main/backend/services/evaluator.py): `backend/services/evaluator.py`
- [Rubric Grading](https://github.com/maheshc4742/ss/blob/main/backend/services/grading_module.py): `backend/services/grading_module.py`
- [Semantic Scoring](https://github.com/maheshc4742/ss/blob/main/backend/services/semantic_module.py): `backend/services/semantic_module.py`
- [OCR Provider Factory](https://github.com/maheshc4742/ss/blob/main/backend/ocr/ocr_factory.py): `backend/ocr/ocr_factory.py`
- [OCR Interface](https://github.com/maheshc4742/ss/blob/main/backend/ocr/base_ocr.py): `backend/ocr/base_ocr.py`
- [Gemini OCR](https://github.com/maheshc4742/ss/blob/main/backend/ocr/gemini_ocr.py): `backend/ocr/gemini_ocr.py`
- [Qwen OCR](https://github.com/maheshc4742/ss/blob/main/backend/ocr/qwen_ocr.py): `backend/ocr/qwen_ocr.py`
- [PDF Rendering](https://github.com/maheshc4742/ss/blob/main/backend/ocr/pdf_utils.py): `backend/ocr/pdf_utils.py`

### Human Review

- [Review API](https://github.com/maheshc4742/ss/blob/main/backend/api/hitl.py): `backend/api/hitl.py`
- [HITL Workflow](https://github.com/maheshc4742/ss/blob/main/backend/services/hitl_service.py): `backend/services/hitl_service.py`

### Model Improvement

- [Training API](https://github.com/maheshc4742/ss/blob/main/backend/api/training.py): `backend/api/training.py`
- [Model API](https://github.com/maheshc4742/ss/blob/main/backend/api/models_api.py): `backend/api/models_api.py`
- [Verified Annotations](https://github.com/maheshc4742/ss/blob/main/data/verified_training.jsonl): `data/verified_training.jsonl`
- [Dataset Preparation](https://github.com/maheshc4742/ss/blob/main/backend/training/prepare_dataset.py): `backend/training/prepare_dataset.py`
- [Fine-Tuning](https://github.com/maheshc4742/ss/blob/main/backend/training/train.py): `backend/training/train.py`
- [Versioned Checkpoints](https://github.com/maheshc4742/ss/tree/main/models): `models`

### Platform

- [Configuration API](https://github.com/maheshc4742/ss/blob/main/backend/api/config_api.py): `backend/api/config_api.py`
- [Application Database](https://github.com/maheshc4742/ss/blob/main/backend/core/database.py): `backend/core/database.py`
- [Evaluation Records](https://github.com/maheshc4742/ss/blob/main/backend/models/database_models.py): `backend/models/database_models.py`
- [Runtime Settings](https://github.com/maheshc4742/ss/blob/main/backend/core/config.py): `backend/core/config.py`
- [Evaluation Reports](https://github.com/maheshc4742/ss/tree/main/reports): `reports`
- [FastAPI Application](https://github.com/maheshc4742/ss/blob/main/backend/main.py): `backend/main.py`

### Other components

- **Human Reviewer**

## Connections

- Web Dashboard → Evaluate API: submits evaluations (evidence: `README.md`)
- Web Dashboard → Review API: reviews answers (evidence: `README.md`)
- Web Dashboard → Training API: triggers training (evidence: `README.md`)
- Web Dashboard → Model API: activates models (evidence: `README.md`)
- Web Dashboard → Configuration API: configures settings (evidence: `README.md`)
- FastAPI Application → Evaluate API: registers routes (evidence: `backend/main.py`)
- FastAPI Application → Review API: registers routes (evidence: `backend/main.py`)
- FastAPI Application → Training API: registers routes (evidence: `backend/main.py`)
- FastAPI Application → Model API: registers routes (evidence: `backend/main.py`)
- FastAPI Application → Configuration API: registers routes (evidence: `backend/main.py`)
- Evaluate API → Evaluation Orchestrator: invokes evaluation (evidence: `backend/api/evaluate.py`)
- Evaluation Orchestrator → OCR Provider Factory: selects provider (evidence: `backend/services/evaluator.py`)
- OCR Provider Factory → Gemini OCR: creates provider (evidence: `backend/ocr/ocr_factory.py`)
- OCR Provider Factory → Qwen OCR: creates provider (evidence: `backend/ocr/ocr_factory.py`)
- Gemini OCR → OCR Interface: implements interface (evidence: `backend/ocr/gemini_ocr.py`)
- Qwen OCR → OCR Interface: implements interface (evidence: `backend/ocr/qwen_ocr.py`)
- Gemini OCR → PDF Rendering: renders PDF pages (evidence: `backend/ocr/gemini_ocr.py`)
- Qwen OCR → PDF Rendering: renders PDF pages (evidence: `backend/ocr/qwen_ocr.py`)
- Evaluation Orchestrator → Semantic Scoring: scores alignment (evidence: `backend/services/evaluator.py`)
- Evaluation Orchestrator → Rubric Grading: grades rubric (evidence: `backend/services/evaluator.py`)
- Evaluation Orchestrator → HITL Workflow: stages review (evidence: `backend/services/evaluator.py`)
- Evaluation Orchestrator → Evaluation Reports: writes report (evidence: `README.md`)
- Evaluation Orchestrator → Application Database: records evaluation (evidence: `backend/api/evaluate.py`)
- Review API → Evaluation Orchestrator: starts train evaluation (evidence: `backend/api/hitl.py`)
- Review API → HITL Workflow: handles review actions (evidence: `backend/api/hitl.py`)
- Human Reviewer → Review API: submits decisions (evidence: `README.md`)
- HITL Workflow → Evaluation Records: updates review records (evidence: `backend/services/hitl_service.py`)
- HITL Workflow → Rubric Grading: quantizes marks (evidence: `backend/services/hitl_service.py`)
- HITL Workflow → Verified Annotations: appends approvals (evidence: `README.md`)
- HITL Workflow → Application Database: persists review state (evidence: `README.md`)
- Application Database → Evaluation Records: creates tables (evidence: `backend/core/database.py`)
- Training API → Fine-Tuning: triggers fine-tuning (evidence: `backend/api/training.py`)
- Fine-Tuning → Dataset Preparation: prepares splits (evidence: `backend/training/train.py`)
- Dataset Preparation → Verified Annotations: loads annotations (evidence: `README.md`)
- Fine-Tuning → Versioned Checkpoints: saves versions (evidence: `README.md`)
- Model API → Evaluation Records: manages registry (evidence: `backend/api/models_api.py`)
- Model API → Runtime Settings: updates active model (evidence: `README.md`)
- Configuration API → Runtime Settings: reads settings (evidence: `backend/api/config_api.py`)