# tamaghnadutta/tutor-vision-engine architecture

> Architecture diagram of the GitHub repository tamaghnadutta/tutor-vision-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tamaghnadutta/tutor-vision-engine
- Repository: https://github.com/tamaghnadutta/tutor-vision-engine

## Overview

##### Project type and purpose
- This is a backend microservice/API focused on step-level error detection in student handwritten math solutions. It exposes a RESTful endpoint (`/api/v1/detect-error`) implemented with FastAPI, orchestrates three AI-based approaches (OCR→LLM, Direct VLM, Hybrid), persists request/response data in SQLite, and provides observability via Prometheus and Grafana.

##### File structure
- Top-level service code lives under `src/api/` (FastAPI app, routes, middleware).
- AI logic is in `src/models/` (approach implementations, model routing, circuit breakers).
- Data handling modules under `src/data/` and `src/analytics/` for caching and persistence.
- Configuration in `src/config/`.
- Tests under `testing/`.
- Scripts for demo, evaluation, load testing, and analytics are in `scripts/`.
- Monitoring manifests (`prometheus.yml`, `docker-compose.monitoring.yml`) and Grafana dashboards under `grafana/`.

##### README insights
- Stateless, horizontally scalable design
- Async processing and background jobs
- Circuit breaker patterns for AI provider fallbacks
- Structured logging, Prometheus metrics, API key auth
- Caching layer for repeated results

##### Main components
a. Client / Consumer
- Demo scripts, load-test runners, or external UI/CLI
b. API Layer (FastAPI)
- Request validation, authentication middleware (`src/api/middleware.py`)
- Routing (`src/api/routes/error_detection.py`)
- Metrics endpoint (`/metrics`)
- Background workers (async tasks for long-running AI calls)
c. AI-Processing Layer
- Model Router (`src/models/model_router.py`), Robust Router (`robust_model_router.py`)
- OCR→LLM module, Direct VLM module (`error_detection_approaches.py`)
- Gemini processor (`gemini_processor.py`)
d. Persistence & Caching
- SQLite database (`data/analytics.db`) via `src/analytics/result_storage.py` and `src/utils/persistence.py`
- In-memory or file-based cache with expiration
e. External Services
- OpenAI API (OCR model, reasoning model)
- Google Gemini API
- Optional local image server for sample images
f. Monitoring & Observability
- Prometheus (scrapes metrics from FastAPI)
- Grafana (dashboards under `grafana/dashboards/`)
- Structured logging (`src/utils/logging.py`), metrics collection (`src/utils/metrics.py`)
g. Configuration & Deployment
- Environment variables (`.env.sample`, `src/config/settings.py`)
- Dockerfile, docker-compose for service and monitoring stack

##### Relationships and data flows
1. Client issues HTTP POST → FastAPI
2. FastAPI authenticates (API key), logs request, increments Prometheus counters
3. Route handler enqueues or directly invokes AI-Processing Layer
4. Model Router selects approach based on `ERROR_DETECTION_APPROACH` env var
5. AI modules call external OpenAI/Gemini APIs (with retries, timeouts, circuit breakers)
6. Results returned to API layer; cache/store in SQLite; cost & token usage computed
7. API responds to client; metrics exported for Prometheus

##### Architectural patterns & principles
- Stateless REST API for horizontal scaling
- Modular separation: API vs AI logic vs data vs utils
- Circuit breaker and retry patterns for external calls
- Async processing for long-running calls
- Cache-aside pattern for repeated results
- Observability: metrics, logging, dashboards

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client / Consumer" 
        direction TB
        Demo["Demo Script"]:::external
        LoadTest["Load-Test Runner"]:::external
        Locust["Locust Script"]:::external
    end

    %% API Layer
    subgraph "API Layer (FastAPI)" 
        direction TB
        Main["main.py"]:::api
        Middleware["middleware.py"]:::api
        Routes["error_detection.py"]:::api
        Schemas["schemas.py"]:::api
        Main --> Middleware
        Main --> Routes
        Routes --> Schemas
    end

    %% AI Processing Layer
    subgraph "AI Processing Layer" 
        direction TB
        Router["model_router.py"]:::ai
        RobustRouter["robust_model_router.py"]:::ai
        Approaches["error_detection_approaches.py"]:::ai
        Detector["error_detector.py"]:::ai
        GeminiProc["gemini_processor.py"]:::ai
        GeminiSchemas["gemini_schemas.py"]:::ai
        Router --> Approaches
        Router --> RobustRouter
        Approaches --> Detector
        Detector --> GeminiProc
        GeminiProc --> GeminiSchemas
    end

    %% Data Persistence & Caching
    subgraph "Persistence & Caching" 
        direction TB
        ResultStore["result_storage.py"]:::data
        PersistenceUtil["persistence.py"]:::data
        DB["analytics.db"]:::data
        ResultStore --> DB
        PersistenceUtil --> DB
    end

    %% Configuration
    subgraph "Config & Deployment"
        direction TB
        Env[".env.sample"]:::data
        Settings["settings.py"]:::data
    end

    %% Monitoring & Observability
    subgraph "Monitoring & Observability"
        direction TB
        Logging["logging.py"]:::monitor
        MetricsUtil["metrics.py"]:::monitor
        PromConfig["prometheus.yml"]:::monitor
        ComposeMon["docker-compose.monitoring.yml"]:::monitor
        GrafanaDash["error-detection-api-dashboard.json"]:::monitor
        MetricsUtil --> PromConfig
        PromConfig --> ComposeMon
        ComposeMon --> GrafanaDash
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        GeminiAPI["Google Gemini API"]:::external
        ImageServer["Local Image Server (Optional)"]:::external
    end

    %% Relationships
    Demo -->|HTTP POST /api/v1/detect-error| Main
    LoadTest -->|HTTP POST /api/v1/detect-error| Main
    Locust -->|HTTP POST /api/v1/detect-error| Main

    Main -->|Auth & Logging| Middleware
    Middleware -->|Route Handling| Routes
    Routes -->|Invoke AI Processing| Router
    Router -->|Select Approach| Approaches
    RobustRouter -->|Fallback| Approaches
    Approaches -->|Call External| OpenAI
    Approaches -->|Call External| GeminiAPI
    Approaches -->|Use Hybrid| Detector
    Detector -->|Gemini Calls| GeminiAPI
    Detector -->|Gemini Schema| GeminiSchemas

    Approaches -->|Store Results| ResultStore
    ResultStore -->|DB Write| DB
    PersistenceUtil -->|DB Access| DB
    Routes -->|Respond to Client| Demo
    Routes -->|Respond to Client| LoadTest
    Routes -->|Respond to Client| Locust

    Main -->|Expose /metrics| MetricsUtil
    PromConfig -->|Scrape| MetricsUtil
    MetricsUtil -->|Logs| Logging
    ComposeMon -->|Dashboard| GrafanaDash

    %% Click Events
    click Main "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/api/main.py"
    click Middleware "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/api/middleware.py"
    click Routes "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/api/routes/error_detection.py"
    click Schemas "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/api/schemas.py"
    click Router "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/models/model_router.py"
    click RobustRouter "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/models/robust_model_router.py"
    click Approaches "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/models/error_detection_approaches.py"
    click Detector "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/models/error_detector.py"
    click GeminiProc "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/models/gemini_processor.py"
    click GeminiSchemas "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/models/gemini_schemas.py"
    click ResultStore "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/analytics/result_storage.py"
    click PersistenceUtil "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/utils/persistence.py"
    click DB "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/data/analytics.db"
    click Env "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/.env.sample"
    click Settings "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/config/settings.py"
    click Logging "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/utils/logging.py"
    click MetricsUtil "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/src/utils/metrics.py"
    click PromConfig "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/prometheus.yml"
    click ComposeMon "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/docker-compose.monitoring.yml"
    click GrafanaDash "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/grafana/dashboards/error-detection-api-dashboard.json"
    click Demo "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/scripts/demo.py"
    click LoadTest "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/scripts/load_test.py"
    click Locust "https://github.com/tamaghnadutta/tutor-vision-engine/blob/main/scripts/locustfile.py"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef ai fill:#DFF5D8,stroke:#28A745,color:#28A745;
    classDef data fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef monitor fill:#E9D8FD,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#F0F0F0,stroke:#6C757D,color:#6C757D;
```
