# shubhamdalvi1999/gen_ai_assignment_evaluator architecture

> Architecture diagram of the GitHub repository shubhamdalvi1999/gen_ai_assignment_evaluator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubhamdalvi1999/gen_ai_assignment_evaluator
- Repository: https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator

## Overview

##### Project Type and Purpose
- **Type**: Full-stack web application with a monolithic backend (FastAPI) and a static frontend (HTML/CSS/JS).
- **Purpose**: Automatically evaluate student code and text assignments via a Retrieval-Augmented-Generation (RAG) pipeline, returning similarity scores and AI-generated feedback.

##### File Structure
- **Top Level**:
- app.py – main FastAPI application entrypoint
- config/setting.py – environment and service configuration
- static/ & templates/ – frontend assets and HTML
- utils/ – modular services (code_analyzer, docx_processor, embedding_service, rag_processor, db_service, feedback_service, logger, tokenizer_utils, prompts)
- docs/ – architecture and flow documentation
- **Patterns**:
- MVC-style separation: templates + static for “view,” FastAPI for “controller,” utils for “model/business logic.”
- RAG pipeline layers implemented as distinct utility modules.

##### Extract Additional Insights from README
- **Backend**: FastAPI providing API endpoints for code and text evaluation.
- **Frontend**: Single-page interface using JavaScript to call backend endpoints.
- **Database**: MongoDB for embedding storage and retrieval.
- **AI Models**: Ollama (local) and OpenAI (cloud) for embeddings and generation.
- **RAG Stages**: Document processing, embedding gen/storage, retrieval, augmentation, evaluation, scoring, generation, summary.

##### Main Components & Interactions
a. **User Interface (Browser)**
- Static files served by FastAPI: HTML (templates/index.html), CSS, JS.
- JS calls backend endpoints (`/evaluate_code`, `/evaluate_text`).
b. **API Layer (FastAPI app.py)**
- Receives HTTP requests from UI.
- Routes to appropriate controller functions.
c. **Configuration Module (config/setting.py)**
- Loads environment variables (API keys, DB URI, thresholds).
d. **RAG Pipeline & Business Logic (utils/…)**
- `docx_processor.py` / `code_analyzer.py`: parse submissions.
- `tokenizer_utils.py`: estimate tokens.
- `embedding_service.py`: call Ollama/OpenAI for embeddings.
- `db_service.py`: store/retrieve embeddings from MongoDB.
- `rag_processor.py` / `text_rag_processor.py`: orchestrate retrieval + augmentation.
- `feedback_service.py`: generate final feedback via AI.
- `prompts.py`: store prompt templates.
- `logger.py`: log each stage to logs/*.log.
e. **External Services**
- **MongoDB**: stores embeddings & QA docs.
- **Ollama API** (optional local)
- **OpenAI API** (optional cloud)
f. **Logging Subsystem**
- File-based logs for each util: `app.log`, `embedding.log`, `feedback.log`, etc.

##### Architectural Patterns & Principles
- **Layered Architecture**: Presentation (frontend), API (FastAPI), Service/Business Logic (utils), Data Access (db_service), External integrations (AI models, MongoDB).
- **Separation of Concerns**: Each util module handles a distinct RAG stage.
- **Modularity & Extensibility**: New evaluation types can be added by creating new util modules.

##### Step-by-Step Diagramming Workflow
- Config Loader
- Endpoint Controllers
- RAG Pipeline (group the utils modules)
- Logger
4. **Inside RAG Pipeline**, order modules top-down:
- Document/Code Processor → Token Estimator → Embedding Service ↔ MongoDB
- Retrieval → Augmentation → Evaluation → Feedback Generator

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser UI
    subgraph "Browser UI"
        UI_HTML["index.html"]:::frontend
        UI_CSS["styles.css"]:::frontend
        UI_JS1["main.js"]:::frontend
        UI_JS2["script.js"]:::frontend
    end

    %% FastAPI Layer
    subgraph "FastAPI (API Layer)"
        AppEntrypoint["app.py"]:::service
        Config["Config Loader<br/>(config/setting.py)"]:::service
        subgraph "RAG Pipeline"
            DocProc["docx_processor.py"]:::service
            CodeProc["code_analyzer.py"]:::service
            TokenEst["tokenizer_utils.py"]:::service
            EmbService["embedding_service.py"]:::service
            DBService["db_service.py"]:::service
            subgraph "Retrieval & Augmentation"
                RAGProc["rag_processor.py"]:::service
                TextRAG["text_rag_processor.py"]:::service
            end
            Feedback["feedback_service.py"]:::service
            Prompts["prompts.py"]:::service
        end
        Logger["logger.py"]:::service
    end

    %% External Datastore and APIs
    MongoDB[(MongoDB)]:::datastore
    Ollama[(Ollama API)]:::external
    OpenAI[(OpenAI API)]:::external

    %% Data Flows
    UI_JS1 -->|"HTTP POST /evaluate_code"| AppEntrypoint
    UI_JS2 -->|"HTTP POST /evaluate_text"| AppEntrypoint
    AppEntrypoint -->|"loads"| Config
    AppEntrypoint -->|"routes to"| DocProc
    AppEntrypoint -->|"routes to"| CodeProc
    AppEntrypoint -->|"logs to"| Logger

    DocProc --> TokenEst
    CodeProc --> TokenEst
    TokenEst --> EmbService
    EmbService --> DBService
    DBService --> MongoDB
    EmbService --> Ollama
    EmbService --> OpenAI
    EmbService --> RAGProc

    RAGProc --> TextRAG
    TextRAG --> Feedback
    RAGProc --> DBService
    TextRAG --> DBService
    Feedback --> Ollama
    Feedback --> OpenAI

    DocProc -->|"logs to"| Logger
    CodeProc -->|"logs to"| Logger
    TokenEst -->|"logs to"| Logger
    EmbService -->|"logs to"| Logger
    RAGProc -->|"logs to"| Logger
    TextRAG -->|"logs to"| Logger
    Feedback -->|"logs to"| Logger

    Prompts --> EmbService
    Prompts --> Feedback

    AppEntrypoint -->|"JSON response"| UI_JS1

    %% Click Events
    click UI_HTML "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/templates/index.html"
    click UI_CSS "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/static/css/styles.css"
    click UI_JS1 "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/static/js/main.js"
    click UI_JS2 "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/static/js/script.js"
    click AppEntrypoint "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/app.py"
    click Config "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/config/setting.py"
    click DocProc "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/docx_processor.py"
    click CodeProc "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/code_analyzer.py"
    click TokenEst "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/tokenizer_utils.py"
    click EmbService "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/embedding_service.py"
    click DBService "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/db_service.py"
    click RAGProc "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/rag_processor.py"
    click TextRAG "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/text_rag_processor.py"
    click Feedback "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/feedback_service.py"
    click Prompts "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/prompts.py"
    click Logger "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/utils/logger.py"
    click docs "https://github.com/shubhamdalvi1999/gen_ai_assignment_evaluator/blob/main/docs/ARCHITECTURE.md"

    %% Styles
    classDef frontend fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef service fill:#EBF5FB,stroke:#2980B9,color:#1B4F72
    classDef datastore fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef external fill:#FDEDEC,stroke:#E74C3C,color:#641E16
```
