# somaskandan931/sathyabama-intelligrade architecture

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

- Interactive diagram: https://gitdiagram.com/somaskandan931/sathyabama-intelligrade
- Repository: https://github.com/somaskandan931/sathyabama-intelligrade

## Overview

This is a **full-stack AI evaluation platform** for grading **handwritten subjective answers**:

- **Frontend**: a **Streamlit teacher dashboard** (`frontend/dashboard.py`) for single/batch grading + analytics.
- **Backend**: a **FastAPI service** (`backend/api.py`) exposing endpoints for upload/OCR/evaluation/results/rubrics/stats.
- **Core “AI Evaluation Engine”**: orchestrated in `backend/evaluator.py`, combining:
- Image preprocessing (`backend/preprocessor.py`)
- OCR (`backend/ocr_module.py`, TrOCR primary, Tesseract fallback)
- Text processing (`backend/text_processor.py`)
- Similarity scoring (`backend/similarity.py`, Sentence-BERT)
- LLM grading (`backend/llm_evaluator.py`, Gemini API)
- Rubric matching (`backend/rubric_matcher.py`, DeBERTa NLI)
- Score aggregation + feedback generation (`backend/evaluator.py`)
- **Persistence**: SQLAlchemy ORM (`backend/database.py`) for Students/Questions/Submissions/Results/Rubrics; SQLite dev, PostgreSQL prod.
- **Deployment**: Docker Compose with separate Dockerfiles for backend/frontend, plus DB (`docker-compose.yml`, `Dockerfile.backend`, `Dockerfile.frontend`).
- **Supporting tooling**: dataset collection (`datasets/collect_dataset.py`), TrOCR training (`models/train_trocr.py`), prompts (`prompts/evaluation_prompts.py`), tests (`tests/test_all.py`).

##### Online grading runtime (request/response, data flow, services)
2) **Offline tooling/training** (dataset + model fine-tuning) that feeds artifacts into runtime

##### User-facing / entry points
- **Teacher (browser)** → **Streamlit Dashboard** (`frontend/dashboard.py`)
- Potential external clients (future LMS integration per README) → **FastAPI** (`backend/api.py`)

##### Backend service boundary
- **API Layer**: `backend/api.py` (routes: `/upload`, `/ocr/{id}`, `/evaluate`, `/result/{id}`, `/rubric`, `/stats`, `/health`)
- **Evaluation Orchestrator**: `backend/evaluator.py`
- **Pipeline stages**:
- Preprocessor: `backend/preprocessor.py`
- OCR engine: `backend/ocr_module.py`
- Text processing: `backend/text_processor.py`
- Similarity: `backend/similarity.py`
- Rubric matcher: `backend/rubric_matcher.py`
- LLM evaluator: `backend/llm_evaluator.py`
- **Metrics/Analytics**: `backend/metrics.py` (ties to `/stats`)
- **Persistence Adapter**: `backend/database.py`
- **Shared utilities**: `backend/text_processor.py`, `backend/similarity.py`, etc.

##### Data stores + external services
- **Database** (PostgreSQL in prod; SQLite in dev) — from `.env` and README.
- **File storage** for uploads (`UPLOAD_DIR=./uploads`) — model it as a local volume/object store.

##### Offline / non-runtime subsystems
- **Dataset toolchain**: `datasets/collect_dataset.py`
- **Model training**: `models/train_trocr.py` (outputs a fine-tuned TrOCR model used by OCR module)
- **Prompt templates**: `prompts/evaluation_prompts.py` (input to LLM evaluator)

##### Teacher Dashboard → triggers either
- **`/ocr/{id}`** (OCR-only path), OR
- **`/evaluate`** (full pipeline path)
##### Evaluator calls
- **Preprocessor** (OpenCV pipeline) → outputs cleaned image
- **OCR Module** (TrOCR primary, Tesseract fallback) → outputs extracted text + confidence
- **Text Processor** (spaCy/NLTK) → normalized text
- Parallel/branch:
- **Similarity** (SBERT cosine similarity vs teacher answer)
- **Rubric Matcher** (DeBERTa NLI vs rubric criteria)
- **LLM Evaluator** (Gemini) using **Prompt Templates**
##### Persist
- **Results table** + feedback JSON in DB

##### External boundary calls
- Evaluator → **Gemini API** (explicitly outside your trust boundary; label “external SaaS”)
- OCR engine may load local model artifacts; show **TrOCR model files** as an internal dependency (from `models/` output).

##### Architectural patterns/principles to reflect
Explicitly because they’re “the story” of the system:

- **API-based architecture**: Streamlit is not directly running ML; it’s a client of FastAPI.
- **Pipeline orchestration** pattern: `evaluator.py` composes multiple stages; show it as a coordinator.
- **Hybrid scoring**: deterministic similarity + rubric coverage + LLM judgment.
- **Separation of concerns**:
- Preprocessing vs OCR vs NLP vs scoring vs persistence
- **Environment-config driven behavior**: `.env` selects `OCR_ENGINE`, weights, database URL.

- **Name** (e.g., “OCR Module”)
- **Repo anchor** (file path, e.g., `backend/ocr_module.py`)
- **Tech** (e.g., “TrOCR/Tesseract”, “SBERT”, “Gemini”, “SQLAlchemy”)
- **Key I/O** (e.g., “Input: image; Output: text+confidence”)

- protocol/type: `HTTP/JSON`, `SQL`, `File I/O`, `External HTTPS`
- payload: “answer image”, “rubric JSON”, “feedback JSON”, “scores”

- Streamlit Dashboard (`frontend/dashboard.py`)
- FastAPI API (`backend/api.py`)
- Evaluator Orchestrator (`backend/evaluator.py`)
- Preprocessing (`backend/preprocessor.py`)
- OCR (`backend/ocr_module.py`) with TrOCR + Tesseract fallback
- Text Processing (`backend/text_processor.py`)
- Similarity (`backend/similarity.py`, SBERT)
- Rubric Matcher (`backend/rubric_matcher.py`, DeBERTa NLI)
- LLM Evaluator (`backend/llm_evaluator.py`, Gemini) + prompts (`prompts/evaluation_prompts.py`)
- Metrics (`backend/metrics.py`) powering `/stats`
- Database layer (`backend/database.py`, SQLAlchemy) + DB (SQLite/Postgres)
- Upload storage (`UPLOAD_DIR`)
- Docker Compose boundary + separate backend/frontend containers
- Offline: dataset collection (`datasets/collect_dataset.py`) + TrOCR training (`models/train_trocr.py`) → model artifacts used by OCR

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram A: Deployment / Container View (Vertical)
    %% =========================
    subgraph "Docker Compose Deployment (Runtime Plane)" 
        DC["Docker Compose\n(services wiring)"]:::ops

        subgraph "Teacher Environment"
            TB["Teacher Browser\n(HTTPS)"]:::external
        end

        subgraph "Frontend Container"
            FE["Streamlit Teacher Dashboard\n(UI + batch grading + analytics)\nTech: Streamlit"]:::service
        end

        subgraph "Backend Container"
            BE["FastAPI Backend Service\n(API + AI pipeline)\nTech: FastAPI"]:::service
        end

        subgraph "Data Plane (Internal)"
            UP[("Upload Storage\n(UPLOAD_DIR volume)\nFile I/O: images/PDFs")]:::datastore
            DB[("Database\n(PostgreSQL prod / SQLite dev)\nSQLAlchemy ORM")]:::datastore
            MW[/"TrOCR Model Artifacts\n(fine-tuned weights)\nLoaded locally"/]:::artifact
            ENV[/"Environment Config\n(DB_URL, OCR_ENGINE, weights)\n.env"/]:::artifact
        end

        subgraph "External SaaS (Out of Trust Boundary)"
            GEMINI(("Gemini API\nExternal HTTPS\nLLM grading")):::externalSaaS
        end

        DC -->|"runs"| FE
        DC -->|"runs"| BE
        DC -->|"runs"| DB

        TB -->|"HTTPS"| FE
        FE -->|"HTTP/JSON"| BE
        BE -->|"SQL"| DB
        BE -->|"File I/O"| UP
        BE -->|"loads"| MW
        BE -->|"reads"| ENV
        BE -->|"External HTTPS\n(only LLM requests)"| GEMINI
    end

    %% =========================
    %% Diagram B: Backend Component + Dataflow View (Vertical)
    %% =========================
    subgraph "Backend Component & Dataflow (Runtime Plane)"
        API["API Layer / Routes\n/upload, /ocr/{id}, /evaluate,\n/result/{id}, /rubric, /stats, /health\nFile: backend/api.py"]:::service

        subgraph "Evaluation Orchestration"
            EV["Evaluator Orchestrator\n(score aggregation + feedback JSON)\nFile: backend/evaluator.py"]:::orchestrator
            HYB["Hybrid Score Calculation\nFinal = 0.6*LLM + 0.4*Similarity*MaxMarks"]:::calc
        end

        subgraph "Pipeline Stages (AI Evaluation Engine)"
            PRE["Image Preprocessing\nInput: image -> Output: cleaned image\nTech: OpenCV\nFile: backend/preprocessor.py"]:::ml
            OCR["OCR Module (Strategy)\nTrOCR primary + Tesseract fallback\nInput: cleaned image -> Output: text+confidence\nFile: backend/ocr_module.py"]:::ml
            TXT["Text Processing / Normalization\nInput: text -> Output: normalized text\nTech: spaCy/NLTK\nFile: backend/text_processor.py"]:::ml

            SIM["Similarity Scoring\nSBERT cosine similarity vs teacher answer\nInput: normalized text -> Output: similarity score\nFile: backend/similarity.py"]:::ml
            RUB["Rubric Matcher\nDeBERTa NLI vs rubric criteria\nInput: normalized text + rubric -> Output: rubric coverage\nFile: backend/rubric_matcher.py"]:::ml
            LLM["LLM Evaluator\nGemini client\nInput: normalized text + prompt -> Output: LLM score + feedback\nFile: backend/llm_evaluator.py"]:::ml

            PR["Prompt Templates\nUsed by LLM evaluator\nFile: prompts/evaluation_prompts.py"]:::artifact
        end

        subgraph "Persistence & Analytics"
            ORM["Persistence Adapter\nSQLAlchemy models + sessions\nFile: backend/database.py"]:::persistence
            MET["Metrics / Analytics\nPowers /stats\nFile: backend/metrics.py"]:::analytics
        end

        %% Runtime request paths
        FE2["Streamlit Dashboard (client)\nTriggers grading flows"]:::service
        FE2 -->|"HTTP/JSON: /upload\n(image/PDF + metadata)"| API

        API -->|"stores file"| UP
        API -->|"creates submission record"| ORM
        ORM -->|"SQL"| DB

        FE2 -->|"HTTP/JSON: /ocr/{id}\n(OCR-only path)"| API
        API -->|"loads submission + file"| ORM
        API -->|"reads file"| UP
        API -->|"calls"| OCR
        OCR -->|"reads TrOCR weights"| MW
        API -->|"returns text+confidence"| FE2

        FE2 -->|"HTTP/JSON: /evaluate\n(full pipeline)"| API
        API -->|"calls"| EV

        EV -->|"reads file"| UP
        EV -->|"loads submission + rubric + question"| ORM

        EV -->|"image -> cleaned image"| PRE
        PRE -->|"cleaned image"| OCR
        OCR -->|"text+confidence"| TXT
        TXT -->|"normalized text"| SIM
        TXT -->|"normalized text"| RUB
        TXT -->|"normalized text"| LLM

        LLM -->|"uses"| PR
        LLM -->|"External HTTPS"| GEMINI

        SIM -->|"similarity score"| HYB
        RUB -->|"rubric coverage signals"| HYB
        LLM -->|"LLM score + draft feedback"| HYB
        HYB -->|"final score + feedback JSON"| EV

        EV -->|"persist result + feedback"| ORM
        ORM -->|"SQL write: Results table"| DB

        FE2 -->|"HTTP/JSON: /result/{id}"| API
        API -->|"reads result"| ORM
        ORM -->|"SQL read"| DB
        API -->|"returns marks + feedback JSON"| FE2

        FE2 -->|"HTTP/JSON: /stats"| API
        API -->|"calls"| MET
        MET -->|"reads aggregates"| ORM
        ORM -->|"SQL"| DB
        MET -->|"returns analytics JSON"| API
    end

    %% =========================
    %% Diagram C: Offline Tooling / Training Plane (Vertical)
    %% =========================
    subgraph "Offline Tooling & Training (Non-Runtime Plane)"
        DS["Dataset Collection Tooling\nCollect/prepare handwritten dataset\nFile: datasets/collect_dataset.py"]:::offline
        TR["TrOCR Training / Fine-tuning\nProduces model weights\nFile: models/train_trocr.py"]:::offline
        TS["Test Suite\nRegression for end-to-end components\nFile: tests/test_all.py"]:::offline
        ENVX["Environment Template\nOCR_ENGINE, DB URL, weights\nFile: .env.example"]:::artifact

        DS -->|"training dataset"| TR
        TR -->|"outputs fine-tuned weights"| MW
        ENVX -->|"configures runtime behavior"| ENV
        TS -->|"tests API + evaluator modules"| API
    end

    %% =========================
    %% Cross-plane guidance (subtle links)
    %% =========================
    DC -.->|"builds"| BE
    DC -.->|"builds"| FE
    ENVX -.->|"copied/filled to"| ENV

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click FE "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/frontend/dashboard.py"
    click FE2 "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/frontend/dashboard.py"
    click API "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/api.py"
    click BE "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/api.py"
    click EV "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/evaluator.py"
    click PRE "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/preprocessor.py"
    click OCR "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/ocr_module.py"
    click TXT "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/text_processor.py"
    click SIM "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/similarity.py"
    click RUB "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/rubric_matcher.py"
    click LLM "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/llm_evaluator.py"
    click PR "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/prompts/evaluation_prompts.py"
    click MET "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/metrics.py"
    click ORM "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/backend/database.py"
    click DS "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/datasets/collect_dataset.py"
    click TR "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/models/train_trocr.py"
    click DC "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/docker-compose.yml"
    click ENVX "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/.env.example"
    click TS "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/tests/test_all.py"

    %% Build configs as artifacts (not required nodes but clickable references)
    DFBE[/"Backend Container Build\nDockerfile.backend"/]:::artifact
    DFFE[/"Frontend Container Build\nDockerfile.frontend"/]:::artifact
    DFBE -.->|"build config"| BE
    DFFE -.->|"build config"| FE
    click DFBE "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/Dockerfile.backend"
    click DFFE "https://github.com/somaskandan931/sathyabama-intelligrade/blob/main/Dockerfile.frontend"

    %% =========================
    %% Styles (color coding)
    %% =========================
    classDef service fill:#1f77b4,stroke:#0b3d91,stroke-width:2px,color:#ffffff
    classDef orchestrator fill:#2a5aa6,stroke:#0b3d91,stroke-width:3px,color:#ffffff
    classDef ml fill:#2ca02c,stroke:#1b6e1b,stroke-width:2px,color:#ffffff
    classDef calc fill:#1b9e77,stroke:#0f5a44,stroke-width:2px,color:#ffffff
    classDef persistence fill:#ff7f0e,stroke:#a84f00,stroke-width:2px,color:#ffffff
    classDef datastore fill:#f39c12,stroke:#a86000,stroke-width:2px,color:#1b1b1b
    classDef analytics fill:#ffb347,stroke:#a86000,stroke-width:2px,color:#1b1b1b
    classDef artifact fill:#f2f2f2,stroke:#7f7f7f,stroke-width:2px,color:#111111
    classDef offline fill:#9e9e9e,stroke:#616161,stroke-width:2px,color:#111111
    classDef external fill:#ffffff,stroke:#444444,stroke-width:2px,color:#111111
    classDef externalSaaS fill:#ffe6e6,stroke:#cc0000,stroke-width:3px,color:#111111
    classDef ops fill:#6c8ebf,stroke:#2b4c7e,stroke-width:2px,color:#ffffff
```
