# pruthakjani5/gtutor architecture

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

- Interactive diagram: https://gitdiagram.com/pruthakjani5/gtutor
- Repository: https://github.com/pruthakjani5/gtutor

## Overview

##### Project Type & Purpose
- GTUtor is a full-stack web application (though monolithic in nature) with a heavy emphasis on document-based knowledge integration.
- Its purpose is to handle multi-subject tutoring by processing documents (PDFs), managing subjects’ knowledge, and providing context-aware chat responses which sometimes fallback on external AI (Google Gemini Pro).

##### Main Components
a. Frontend / User Interface:
- Represented by the Streamlit interface. This includes the chat interface, subject selection dropdown, and file upload features.
b. Application Logic / Backend:
- The main application logic is contained in app.py, coordinating requests and responses between different modules.
c. Document Processing Module:
- Uses libraries like pypdf for text extraction and automatic chunking from PDF files.
d. Knowledge Base / Vector Database:
- Built on ChromaDB, this module stores the processed document data across multiple subjects (organized in gtutor_data/dbs). Show the separate directories for each subject (e.g., asd, dcn).
e. AI Integration Component:
- Integration with Google Gemini Pro API for generating intelligent, context-aware responses.
f. Persistence Layer:
- Manages persistent storage such as chat histories (gtutor_data/chat_histories) and subject configurations (gtutor_data/subjects.json). This can be depicted as a file-based storage subsystem.
g. Environment & Configuration:
- The .env file holding the API keys and any configuration (also mention the .devcontainer for development deployment environment).

##### Relationships & Data Flows
- Users interact with the UI (Streamlit) to select subjects, upload documents, and enter chat messages.
- The UI passes uploaded PDF documents to the Document Processing Module, which extracts and chunks text.
- Processed information is stored in the Vector Database for fast look-up and context retrieval.
- When a chat message is sent, the system first tries to fetch relevant context from the vector DB; if needed, the query is forwarded to the AI Integration component via the Gemini Pro API.
- The resulting responses flow back through the application logic to the UI, where chat histories are recorded in persistent storage.
- Configuration settings (from the .env file) determine access to external services like the Gemini API.
- Additionally, subject management and chat history management are maintained in separate JSON (or file) storage under gtutor_data.

##### Architectural Patterns and Design Principles
- The system follows a loosely layered architecture where the UI, business logic, and persistence layers are clearly separated.
- It relies on modular design – for example, separating document processing, AI integration, and data storage helps in scaling or modifying individual components as needed.
- The data flow embodies a request-response model with persistent logging (via JSON files) to maintain state and history.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    UI["Streamlit UI (Frontend)"]:::frontend

    %% Backend Layer
    AL["Application Logic (app.py)"]:::backend

    %% Processing Module
    DPM["Document Processing Module (pypdf)"]:::backend

    %% Data Storage: Vector Database
    DB["Vector Database (ChromaDB)"]:::storage
    subgraph "Subjects in Vector Database"
        asd["Subject: asd"]:::storage
        dcn["Subject: dcn"]:::storage
    end

    %% AI Integration Component
    AI["AI Integration Module (Google Gemini Pro API)"]:::external

    %% Chat History and Subject Data Storage
    CH["Chat History & Subject Data Storage"]:::storage

    %% Environment & Configuration
    subgraph "Environment & Configuration"
        ENV[".env"]:::env
        DEV[".devcontainer (devcontainer.json)"]:::env
    end

    %% Data Flows
    UI -->|"User_Input"| AL
    AL -->|"PDF_Upload"| DPM
    DPM -->|"Extracted_Text"| DB
    DB -->|"Context_Retrieval"| AL
    AL -->|"API_Request"| AI
    AI -->|"API_Response"| AL
    AL -->|"Store_ChatHistory"| CH
    AL -->|"Display_Response"| UI
    AL -->|"Load_Config"| ENV
    AL -->|"Load_Dev_Env"| DEV

    %% Subjects Integration
    DB -->|"Organize_Data"| asd
    DB -->|"Organize_Data"| dcn

    %% Click Events
    click UI "https://github.com/pruthakjani5/gtutor/blob/main/app.py"
    click AL "https://github.com/pruthakjani5/gtutor/blob/main/app.py"
    click DB "https://github.com/pruthakjani5/gtutor/tree/main/gtutor_data/dbs"
    click asd "https://github.com/pruthakjani5/gtutor/tree/main/gtutor_data/dbs/asd"
    click dcn "https://github.com/pruthakjani5/gtutor/tree/main/gtutor_data/dbs/dcn"
    click CH "https://github.com/pruthakjani5/gtutor/tree/main/gtutor_data/chat_histories"
    click ENV "https://github.com/pruthakjani5/gtutor/blob/main/.env"
    click DEV "https://github.com/pruthakjani5/gtutor/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef frontend fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef backend fill:#e6f2ff,stroke:#004080,stroke-width:2px;
    classDef storage fill:#e6ffe6,stroke:#006600,stroke-width:2px;
    classDef external fill:#f2e6ff,stroke:#6600cc,stroke-width:2px;
    classDef env fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
```
