# jose-0000/exam-grading-assistant architecture

> Architecture diagram of the GitHub repository jose-0000/exam-grading-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jose-0000/exam-grading-assistant
- Repository: https://github.com/jose-0000/exam-grading-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Exam Grading Assistant”) built with Python/Flask on the backend and plain HTML/CSS/JS on the frontend.
- Purpose: Automate grading of handwritten exam scripts by applying image preprocessing, OCR extraction, and semantic similarity scoring (via BERT).

##### File Structure Analysis
- Top level:
- app.py, main.py – Flask routing and server startup
- grading.py – BERT-based grading logic
- imagepre.py, image.py – image preprocessing functions (resizing, contrast/brightness adjust)
- ocr_utils.py – OCR wrapper (PyTesseract calls)
- templates/ – HTML views (front.html, index.html, result.html)
- .env, requirements.txt – configuration and dependency listing
- No dedicated static/ uploads/ processed/ dirs shown, but implied by README.
- No microservices or external API servers—single-process Flask app.

##### README Insights
- Confirms tech stack (Flask, OpenCV, Pillow, PyTesseract, Tesseract-OCR, BERT).
- High-level workflow: upload → preprocess → OCR → BERT similarity → render result.

##### Main Components
a. Client Layer
- Client Browser
- Renders front.html, index.html, result.html
b. Backend Layer (Flask Server)
- Routes & Controllers (app.py / main.py)
- Configuration (env variables, requirements.txt)
- Service Modules:
- Image Preprocessor (imagepre.py, image.py)
- OCR Module (ocr_utils.py)
- Grading Module (grading.py)
c. Storage
- Uploaded images directory
- Processed images directory
d. External Engine
- Tesseract-OCR binary
- BERT model (could be local or loaded via a Python library)

##### Component Interactions
- Client → POST image → Routes
- Routes → Image Preprocessor → enhanced image
- Preprocessor → OCR Module → extracted text
- OCR Module → Grading Module → similarity scores
- Grading Module → Routes → render result.html back to Client
- Routes → Save raw / processed images to Storage

##### Architectural Patterns & Design Principles
- Layered architecture (Presentation, Application Logic, Services, Storage)
- Separation of concerns: distinct modules for preprocessing, OCR, grading
- Single‐process monolith (no microservices)
- Standard MVC-style routing & templating (Flask controllers → Jinja2 templates)

##### Technologies & Frameworks
- Flask (HTTP routing, templating)
- Pillow & OpenCV (image manipulation)
- PyTesseract + Tesseract-OCR (text extraction)
- BERT (semantic similarity scoring, grading)
- HTML/CSS/JS (UI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend - Templates"
        Front["front.html"]:::frontend
        Index["index.html"]:::frontend
        Result["result.html"]:::frontend
    end
    Client["Client Browser"]:::frontend

    Client -->|renders| Front
    Client -->|renders| Index
    Client -->|renders| Result
    Client -->|POST image| Routes

    subgraph "Backend - Flask Server"
        Routes["Routes\n(app.py, main.py)"]:::backend
        Config["Config\n(.env, requirements.txt)"]:::backend
        subgraph "Service Modules"
            Pre["Image Preprocessor\n(imagepre.py, image.py)"]:::module
            OCR["OCR Module\n(ocr_utils.py)"]:::module
            Grader["Grading Module\n(grading.py)"]:::module
        end
    end

    Routes -->|enhance image| Pre
    Pre -->|enhanced image| OCR
    OCR -->|extracted text| Grader
    Grader -->|similarity scores| Routes
    Routes -->|render result.html| Client
    Routes -->|save files| Storage["File Storage"]:::storage

    click Front "https://github.com/jose-0000/exam-grading-assistant/blob/main/templates/front.html"
    click Index "https://github.com/jose-0000/exam-grading-assistant/blob/main/templates/index.html"
    click Result "https://github.com/jose-0000/exam-grading-assistant/blob/main/templates/result.html"
    click Routes "https://github.com/jose-0000/exam-grading-assistant/blob/main/app.py"
    click Routes "https://github.com/jose-0000/exam-grading-assistant/blob/main/main.py"
    click Config "https://github.com/jose-0000/exam-grading-assistant/blob/main/.env"
    click Config "https://github.com/jose-0000/exam-grading-assistant/blob/main/requirments.txt"
    click Pre "https://github.com/jose-0000/exam-grading-assistant/blob/main/imagepre.py"
    click Pre "https://github.com/jose-0000/exam-grading-assistant/blob/main/image.py"
    click OCR "https://github.com/jose-0000/exam-grading-assistant/blob/main/ocr_utils.py"
    click Grader "https://github.com/jose-0000/exam-grading-assistant/blob/main/grading.py"

    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px
    classDef module fill:#98fb98,stroke:#000,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#000,stroke-width:1px
```
