# gpa95/ai_studybuddy architecture

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

- Interactive diagram: https://gitdiagram.com/gpa95/ai_studybuddy
- Repository: https://github.com/gpa95/ai_studybuddy

## Overview

##### Project type and purpose
- **Type:** Full-stack web application (lightweight)
- **Purpose:** Provide a chat-based UI for students to get explanations, summaries, and quizzes by leveraging Google’s Gemini 2.5 Flash AI API.

##### File structure
- **Top-level files:**
- main.py – entry point (Streamlit app)
- requirements.txt – Python dependencies
- assets/ – static resources (e.g., sample PDFs)
- components/ – UI widgets and handlers for chat, sidebar, and PDF uploads
- core/ – business logic modules (explainer, summarizer, quizzer, PDF handler, AI utilities)
- utils/ – helper for interacting with Gemini API
- **Patterns:**
- Separation of concerns: UI (components) vs core logic vs external API helpers
- No persistent database—stateless, relies on in-memory chat context and external AI service

##### Extract architecture insights from README
- **Frontend:** Streamlit app rendering components and managing user sessions
- **Backend / AI Engine:** Calls to Gemini 2.5 Flash API via `utils/gemini_helper.py`
- **Security:** Credentials managed in `.env` and `st.secrets`
- **PDF processing:** PyPDF2 inside `components/pdf_handler.py` and `core/pdf_handler.py`

##### Main components and their interactions
a. **Frontend Layer (Streamlit UI)**
- Blocks: Chat UI, Sidebar, File uploader (components/chat_ui.py, components/sidebar.py, components/pdf_handler.py)
- Orchestrator: main.py initializes UI and routes interactions to core modules
b. **Core Processing Layer**
- explainer.py, summarizer.py, quizzer.py: contain prompt templates and logic to frame queries
- ai_utils.py: common routines (e.g., formatting responses)
- pdf_handler.py: parse and extract text from uploaded PDFs
c. **Integration Layer (utils)**
- gemini_helper.py: wraps API calls, handles authentication and rate-limits
d. **External Service**
- Google Gemini 2.5 Flash API: generates natural language responses
e. **Configuration & Secrets**
- `.env` / `st.secrets`: store API keys and config

##### Relationships & data flow
1. User interacts with Streamlit UI → submits text or PDF
2. PDF handler extracts text (PyPDF2) → returns raw text
3. Core module (explainer/summarizer/quizzer) receives text or user query → builds prompt
4. gemini_helper.py sends prompt to Gemini API → receives response
5. ai_utils formats the response → Streamlit UI displays reply

##### Architectural patterns & principles
- **Modular Separation:** UI vs business logic vs API integration
- **Statelessness:** No persistent DB; session state lives in Streamlit memory
- **Single Responsibility:** Each module/class has a clear, isolated role
- **Secure Configuration:** Externalizes secrets, avoids hard-coding

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Main["main.py"]:::frontend
        ChatUI["chat_ui.py"]:::frontend
        Sidebar["sidebar.py"]:::frontend
        PDFUI["pdf_handler.py"]:::frontend
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        direction TB
        Explainer["explainer.py"]:::core
        Summarizer["summarizer.py"]:::core
        Quizzer["quizzer.py"]:::core
        PDFCore["pdf_handler.py"]:::core
        AIUtils["ai_utils.py"]:::core
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        GeminiHelper["gemini_helper.py"]:::integration
    end

    %% External Service
    GeminiAPI["Google Gemini 2.5 Flash API"]:::external

    %% Configuration & Assets
    Env[".env / st.secrets"]:::config
    Requirements["requirements.txt"]:::config
    Assets["assets/PROBLEM STATEMENTS.pdf"]:::assets

    %% Relationships
    User -->|"interacts"| Main
    Main -->|"renders"| ChatUI
    Main -->|"renders"| Sidebar
    Main -->|"renders"| PDFUI
    PDFUI -->|"upload PDF"| PDFCore
    ChatUI -->|"user query"| Explainer
    ChatUI -->|"user query"| Summarizer
    ChatUI -->|"user query"| Quizzer
    PDFCore -->|"extracted text"| Explainer
    Explainer -->|"build prompt"| GeminiHelper
    Summarizer -->|"build prompt"| GeminiHelper
    Quizzer -->|"build prompt"| GeminiHelper
    GeminiHelper -->|"API request"| GeminiAPI
    GeminiAPI -->|"API response"| GeminiHelper
    GeminiHelper -->|"raw response"| AIUtils
    AIUtils -->|"formatted response"| Main
    Env -.-> GeminiHelper
    Env -.-> Main
    Requirements -.-> Main
    Assets -.-> PDFUI

    %% Click Events
    click Main "https://github.com/gpa95/ai_studybuddy/blob/main/main.py"
    click ChatUI "https://github.com/gpa95/ai_studybuddy/blob/main/components/chat_ui.py"
    click Sidebar "https://github.com/gpa95/ai_studybuddy/blob/main/components/sidebar.py"
    click PDFUI "https://github.com/gpa95/ai_studybuddy/blob/main/components/pdf_handler.py"
    click Explainer "https://github.com/gpa95/ai_studybuddy/blob/main/core/explainer.py"
    click Summarizer "https://github.com/gpa95/ai_studybuddy/blob/main/core/summarizer.py"
    click Quizzer "https://github.com/gpa95/ai_studybuddy/blob/main/core/quizzer.py"
    click PDFCore "https://github.com/gpa95/ai_studybuddy/blob/main/core/pdf_handler.py"
    click AIUtils "https://github.com/gpa95/ai_studybuddy/blob/main/core/ai_utils.py"
    click GeminiHelper "https://github.com/gpa95/ai_studybuddy/blob/main/utils/gemini_helper.py"
    click Assets "https://github.com/gpa95/ai_studybuddy/blob/main/assets/PROBLEM STATEMENTS.pdf"
    click Requirements "https://github.com/gpa95/ai_studybuddy/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef core fill:#DFF5D4,stroke:#228B22,color:#228B22
    classDef integration fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#E0E0E0,stroke:#707070,color:#333333
    classDef config fill:#FFF4C1,stroke:#FFD700,color:#B8860B
    classDef assets fill:#F5D1E2,stroke:#C71585,color:#C71585
```
