# shivamdevkar/automated-subjective-question-answer-evaluation-system architecture

> Architecture diagram of the GitHub repository shivamdevkar/automated-subjective-question-answer-evaluation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shivamdevkar/automated-subjective-question-answer-evaluation-system
- Repository: https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system

## Overview

This is a DBMS handwritten-answer grading application. Educators or students submit an image or text answer through the Streamlit interface; the evaluator coordinates OCR (for images), text preparation, similarity analysis, grade prediction, and scoring with feedback. The README also describes batch evaluation, PDF-based training-data extraction, model training, and evaluation history. The main pipeline is documented, but excerpts do not expose all runtime calls, so some secondary links are omitted or marked unverified.

Main entry points: [`src/evaluator.py`](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/evaluator.py) (Evaluation orchestrator), [`app.py`](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/app.py) (Streamlit interface), [`config.py`](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/config.py) (System configuration), [`src/ocr_processor.py`](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ocr_processor.py) (Handwriting OCR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Streamlit interface<br/>[app.py]"]
  node_validation["Input validation<br/>[validators.py]"]
end

subgraph group_ingestion["Answer ingestion"]
  node_ocr["Handwriting OCR<br/>[ocr_processor.py]"]
  node_pdf["PDF extraction<br/>[pdf_processor.py]"]
end

subgraph group_analysis["Answer analysis"]
  node_text["Text processing<br/>[text_processor.py]"]
  node_similarity["Similarity metrics"]
  node_bert["BERT similarity<br/>[bert_similarity.py]"]
  node_simcse["SimCSE similarity"]
end

subgraph group_grading["Grading and feedback"]
  node_evaluator["Evaluation orchestrator<br/>[evaluator.py]"]
  node_classifier["Grade classifier<br/>[ml_classifier.py]"]
  node_classifier_v2["Classifier v2"]
  node_ensemble["Model ensemble<br/>[ensemble.py]"]
  node_scoring["Scoring and feedback<br/>[scoring_system.py]"]
end

subgraph group_learning["Training and configuration"]
  node_config["System configuration<br/>[config.py]"]
  node_training_data["Training datasets<br/>[training_data.csv]"]
  node_samples["Sample questions"]
  node_dbms_pairs["DBMS training pairs"]
end

node_user(("Educator or student"))

node_user -->|"submits answer"| node_app
node_app -.->|"validates input"| node_validation
node_app -->|"requests evaluation"| node_evaluator
node_evaluator -->|"extracts handwriting"| node_ocr
node_evaluator -->|"prepares text"| node_text
node_evaluator -->|"calculates metrics"| node_similarity
node_evaluator -->|"predicts grade"| node_classifier
node_evaluator -->|"scores answer"| node_scoring
node_evaluator -->|"processes training PDFs"| node_pdf
node_pdf -->|"uses OCR"| node_ocr
node_evaluator -.->|"may use similarity"| node_bert
node_evaluator -.->|"may use similarity"| node_simcse
node_evaluator -.->|"may predict grade"| node_classifier_v2
node_evaluator -.->|"may combine models"| node_ensemble
node_evaluator -.->|"reads settings"| node_config
node_classifier -.->|"reads settings"| node_config
node_ocr -.->|"reads settings"| node_config
node_text -.->|"reads settings"| node_config
node_similarity -.->|"reads settings"| node_config
node_scoring -.->|"reads settings"| node_config
node_app -.->|"loads training data"| node_training_data
node_app -.->|"loads sample questions"| node_samples
node_evaluator -.->|"trains from data"| node_training_data
node_evaluator -.->|"may use training pairs"| node_dbms_pairs
node_app -->|"presents results"| node_user

click node_app "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/app.py"
click node_validation "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/validators.py"
click node_evaluator "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/evaluator.py"
click node_ocr "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ocr_processor.py"
click node_pdf "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/pdf_processor.py"
click node_text "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/text_processor.py"
click node_similarity "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/similarity_calculator.py"
click node_bert "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/bert_similarity.py"
click node_simcse "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/simcse_similarity.py"
click node_classifier "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ml_classifier.py"
click node_classifier_v2 "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ml_classifier_v2.py"
click node_ensemble "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ensemble.py"
click node_scoring "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/scoring_system.py"
click node_config "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/config.py"
click node_training_data "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/data/training_data.csv"
click node_samples "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/data/sample_questions.json"
click node_dbms_pairs "https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/data/dbms_training_pairs.json"

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_validation toneBlue
class node_ocr,node_pdf toneAmber
class node_text,node_similarity,node_bert,node_simcse toneMint
class node_evaluator,node_classifier,node_classifier_v2,node_ensemble,node_scoring toneRose
class node_config,node_training_data,node_samples,node_dbms_pairs,node_user toneIndigo
```

## Components

### User interface

- [Streamlit interface](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/app.py): `app.py`
- [Input validation](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/validators.py): `src/validators.py`

### Answer ingestion

- [Handwriting OCR](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ocr_processor.py): `src/ocr_processor.py`
- [PDF extraction](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/pdf_processor.py): `src/pdf_processor.py`

### Answer analysis

- [Text processing](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/text_processor.py): `src/text_processor.py`
- [Similarity metrics](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/similarity_calculator.py): `src/similarity_calculator.py`
- [BERT similarity](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/bert_similarity.py): `src/bert_similarity.py`
- [SimCSE similarity](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/simcse_similarity.py): `src/simcse_similarity.py`

### Grading and feedback

- [Evaluation orchestrator](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/evaluator.py): `src/evaluator.py`
- [Grade classifier](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ml_classifier.py): `src/ml_classifier.py`
- [Classifier v2](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ml_classifier_v2.py): `src/ml_classifier_v2.py`
- [Model ensemble](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/ensemble.py): `src/ensemble.py`
- [Scoring and feedback](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/src/scoring_system.py): `src/scoring_system.py`

### Training and configuration

- [System configuration](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/config.py): `config.py`
- [Training datasets](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/data/training_data.csv): `data/training_data.csv`
- [Sample questions](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/data/sample_questions.json): `data/sample_questions.json`
- [DBMS training pairs](https://github.com/shivamdevkar/automated-subjective-question-answer-evaluation-system/blob/main/data/dbms_training_pairs.json): `data/dbms_training_pairs.json`

### Other components

- **Educator or student**

## Connections

- Educator or student → Streamlit interface: submits answer (evidence: `README.md`)
- Streamlit interface → Input validation: validates input (evidence: `app.py`)
- Streamlit interface → Evaluation orchestrator: requests evaluation (evidence: `README.md`)
- Evaluation orchestrator → Handwriting OCR: extracts handwriting (evidence: `README.md`)
- Evaluation orchestrator → Text processing: prepares text (evidence: `README.md`)
- Evaluation orchestrator → Similarity metrics: calculates metrics (evidence: `README.md`)
- Evaluation orchestrator → Grade classifier: predicts grade (evidence: `README.md`)
- Evaluation orchestrator → Scoring and feedback: scores answer (evidence: `README.md`)
- Evaluation orchestrator → PDF extraction: processes training PDFs (evidence: `src/evaluator.py`)
- PDF extraction → Handwriting OCR: uses OCR (evidence: `src/pdf_processor.py`)
- Evaluation orchestrator → BERT similarity: may use similarity (evidence: `src/evaluator.py`)
- Evaluation orchestrator → SimCSE similarity: may use similarity
- Evaluation orchestrator → Classifier v2: may predict grade (evidence: `src/evaluator.py`)
- Evaluation orchestrator → Model ensemble: may combine models (evidence: `src/evaluator.py`)
- Evaluation orchestrator → System configuration: reads settings (evidence: `src/evaluator.py`)
- Grade classifier → System configuration: reads settings (evidence: `src/ml_classifier.py`)
- Handwriting OCR → System configuration: reads settings (evidence: `src/ocr_processor.py`)
- Text processing → System configuration: reads settings (evidence: `src/text_processor.py`)
- Similarity metrics → System configuration: reads settings (evidence: `src/similarity_calculator.py`)
- Scoring and feedback → System configuration: reads settings (evidence: `src/scoring_system.py`)
- Streamlit interface → Training datasets: loads training data
- Streamlit interface → Sample questions: loads sample questions
- Evaluation orchestrator → Training datasets: trains from data
- Evaluation orchestrator → DBMS training pairs: may use training pairs
- Streamlit interface → Educator or student: presents results (evidence: `README.md`)
