# lukablaskovic/edu_bot architecture

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

- Interactive diagram: https://gitdiagram.com/lukablaskovic/edu_bot
- Repository: https://github.com/lukablaskovic/edu_bot

## Overview

##### Project Type and Purpose
- EduBot is a full-stack, cloud-connected RAG (Retrieval-Augmented Generation) chatbot built in Python.
- Front-end: Streamlit multi-page UI for chat, user profile, and learning resources.
- Back-end: Modular RAG pipeline (RAPTOR, SQL-RAG, Web-scraper, Direct LLM) using LlamaIndex.
- Data stores: Chroma DB for embeddings, SQLite for structured data, file store for uploaded docs.
- External integrations: OpenAI/Anthropic/Ollama APIs, Google OAuth, University news website.

##### File Structure Insights
- Top-level scripts: 🤖EduBot.py (Streamlit launcher), chatbot.py, intent_agent.py, modules/*.py
- Front-end pages: pages/👤Korisnički_profil.py, pages/📚Datoteke.py
- Modules directory:
- raptor_module.py – builds & queries hierarchical RAPTOR index
- sqlrag_module.py – translates text→SQL & queries SQLite
- web_scraper_module.py – scrapes news via requests + BeautifulSoup
- db/database.db – local SQLite for academic data
- Data directories:
- chroma_db/ – persistent embedding store (Chroma)
- uploaded_files/ – user-uploaded learning resources
- Config & credentials: .env_template, openai_key.py, google_credentials.json (external), settings.py
- Prompts: prompts/ → tool descriptions for each RAG module
- Tests & notebooks: test_chatbot.py, evaluation/*.ipynb

##### Key Architectural Patterns
- Modular “Query Engine” plugin pattern: Router Query Engine dispatches to specialized engines.
- RAG pipeline: Retrieval (RAPTOR tree / SQL / Web-scrape) → generation (LLM).
- Multi-modal ingestion: PDF/text/slides → embeddings → hierarchical index.
- External service orchestration: OAuth for user info; REST calls to news site; LLM API calls.

##### Main Components & Their Relationships
A. User & UI Layer
- User’s browser runs Streamlit front-end (🤖EduBot.py) → pages & sidebar.
- Google OAuth module provides user identity.
B. Router & Controller
- User query → Router Query Engine (LLMSingleSelector)
- Chooses one of: RAPTOR engine, SQL-RAG engine, Web-scraper engine, or default LLM.
C. RAG Modules (each a separate component)
1. RAPTOR Module
– Ingests uploaded_files → llamaindex RAPTOR Pack → builds tree in chroma_db
– On query: llamaindex RAPTOR Retrieval → returns relevant text chunks
2. SQL-RAG Module
– Query text → text-to-SQL transformer → runs against modules/db/database.db → returns rows
3. Web-scraper Module
– Fetches & parses University news site → returns article text
4. Direct LLM Module
– For chit-chat or fallback queries → direct call to selected LLM
D. LLM Generation
- Once retrieval result available → call chosen LLM (OpenAI, Anthropic, Ollama) → generate answer.
E. Response & Logging
- Generated answer → Streamlit UI
- Actions & errors logged to app.log

- Module responsibilities (e.g., “raptor_module.py: hierarchical embedding + retrieval”).
- Dynamic choice logic in Router (LLMSingleSelector).
- Multi-document ingestion path vs. single-query retrieval.
- Configuration/credentials boundary (e.g., .env, google_credentials.json) as a secure vault.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User & UI Layer
    subgraph "User & UI Layer"
        UI_main["EduBot.py"]:::ui
        UI_profile["Korisnički_profil.py"]:::ui
        UI_files["Datoteke.py"]:::ui
    end

    %% Auth Module
    subgraph "Authentication"
        GO_main["streamlit_google_auth/__init__.py"]:::external
        GO_cookie["streamlit_google_auth/cookie/__init__.py"]:::external
    end

    %% Router & Controller
    Router["Router Query Engine\n(intent_agent.py)"]:::controller

    %% Chatbot & Direct LLM
    Chatbot["Chatbot Orchestration & Direct LLM\n(chatbot.py)"]:::gen

    %% RAG Modules
    subgraph "RAG Modules"
        Raptor["RAPTOR Module\n(raptor_module.py)"]:::retrieval
        SQLRag["SQL-RAG Module\n(sqlrag_module.py)"]:::retrieval
        WebScrape["Web-Scraper Module\n(web_scraper_module.py)"]:::retrieval
    end

    %% LLM Providers
    subgraph "LLM Providers"
        LLM_OpenAI["OpenAI API"]:::external
        LLM_Anthropic["Anthropic API"]:::external
        LLM_Ollama["Ollama API"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        Chroma["Chroma DB"]:::data
        SQLite["SQLite DB"]:::data
        Uploaded["Uploaded Files Store"]:::data
    end

    %% External News
    ExternalNews["University News Website"]:::external

    %% Config & Prompts
    Vault["Config & Credentials"]:::config
    Prompts["Prompt Templates"]:::config

    %% Logging
    Log["Logging (app.log)"]:::log

    %% Tests & Evaluation
    subgraph "Tests & Evaluation"
        TestScript["test_chatbot.py"]:::test
        Notebook["evaluation.ipynb"]:::test
        CSV["*.csv"]:::test
    end

    %% Relationships
    UI_main -->|"user query"| Router
    UI_profile -->|"user query"| Router
    UI_files -->|"user query"| Router
    UI_main -->|"authenticate via OAuth"| GO_main

    Router -->|"select module"| Raptor
    Router -->|"select module"| SQLRag
    Router -->|"select module"| WebScrape
    Router -->|"select module"| Chatbot

    Uploaded -->|"ingest via RAPTOR Pack"| Raptor
    Raptor -->|"store embeddings"| Chroma
    Raptor -->|"retrieve chunks"| Chroma

    SQLRag -->|"text-to-SQL"| SQLite
    SQLRag -->|"return rows"| SQLite

    WebScrape -->|"REST scraping"| ExternalNews

    Raptor -->|"retrieval result"| Chatbot
    SQLRag -->|"retrieval result"| Chatbot
    WebScrape -->|"retrieval result"| Chatbot
    Chatbot -->|"call LLM"| LLM_OpenAI
    Chatbot -->|"call LLM"| LLM_Anthropic
    Chatbot -->|"call LLM"| LLM_Ollama
    LLM_OpenAI -->|"response"| Chatbot
    LLM_Anthropic -->|"response"| Chatbot
    LLM_Ollama -->|"response"| Chatbot

    Chatbot -->|"response"| UI_main

    Router -->|"log actions/errors"| Log
    Raptor -->|"log"| Log
    SQLRag -->|"log"| Log
    WebScrape -->|"log"| Log
    Chatbot -->|"log"| Log

    Vault --> Router
    Vault --> Chatbot
    Vault --> Raptor
    Vault --> SQLRag
    Vault --> WebScrape

    Prompts --> Raptor
    Prompts --> SQLRag
    Prompts --> Chatbot

    %% Click Events
    click UI_main "https://github.com/lukablaskovic/edu_bot/blob/main/🤖EduBot.py"
    click UI_profile "https://github.com/lukablaskovic/edu_bot/blob/main/pages/👤Korisnički_profil.py"
    click UI_files "https://github.com/lukablaskovic/edu_bot/blob/main/pages/📚Datoteke.py"
    click GO_main "https://github.com/lukablaskovic/edu_bot/blob/main/streamlit_google_auth/__init__.py"
    click GO_cookie "https://github.com/lukablaskovic/edu_bot/blob/main/streamlit_google_auth/cookie/__init__.py"
    click Router "https://github.com/lukablaskovic/edu_bot/blob/main/intent_agent.py"
    click Chatbot "https://github.com/lukablaskovic/edu_bot/blob/main/chatbot.py"
    click Raptor "https://github.com/lukablaskovic/edu_bot/blob/main/modules/raptor_module.py"
    click SQLRag "https://github.com/lukablaskovic/edu_bot/blob/main/modules/sqlrag_module.py"
    click WebScrape "https://github.com/lukablaskovic/edu_bot/blob/main/modules/web_scraper_module.py"
    click Chroma "https://github.com/lukablaskovic/edu_bot/tree/main/chroma_db/"
    click SQLite "https://github.com/lukablaskovic/edu_bot/blob/main/modules/db/database.db"
    click Uploaded "https://github.com/lukablaskovic/edu_bot/tree/main/uploaded_files/"
    click Vault "https://github.com/lukablaskovic/edu_bot/blob/main/.env_template"
    click Vault "https://github.com/lukablaskovic/edu_bot/blob/main/openai_key.py"
    click Vault "https://github.com/lukablaskovic/edu_bot/blob/main/settings.py"
    click Prompts "https://github.com/lukablaskovic/edu_bot/blob/main/prompts/RAPTOR_QUERY_TOOL_DESCRIPTION.txt"
    click Prompts "https://github.com/lukablaskovic/edu_bot/blob/main/prompts/SQL_RAG_QUERY_TOOL_DESCRIPTION.txt"
    click Prompts "https://github.com/lukablaskovic/edu_bot/blob/main/prompts/DIRECT_LLM_PROMPT.txt"
    click Prompts "https://github.com/lukablaskovic/edu_bot/tree/main/prompts/default/"
    click Log "https://github.com/lukablaskovic/edu_bot/blob/main/app.log"
    click TestScript "https://github.com/lukablaskovic/edu_bot/blob/main/test_chatbot.py"
    click Notebook "https://github.com/lukablaskovic/edu_bot/blob/main/evaluation/evaluation.ipynb"
    click CSV "https://github.com/lukablaskovic/edu_bot/blob/main/evaluation/*.csv"

    %% Styles
    classDef ui fill:#D8BFD8,stroke:#9370DB,color:#000
    classDef controller fill:#AFEEEE,stroke:#20B2AA,color:#000
    classDef retrieval fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef gen fill:#98FB98,stroke:#008000,color:#000
    classDef data fill:#FFD700,stroke:#FFA500,color:#000
    classDef external fill:#D3D3D3,stroke:#A9A9A9,color:#000
    classDef config fill:#FFFACD,stroke:#FFD700,color:#000
    classDef log fill:#F08080,stroke:#CD5C5C,color:#000
    classDef test fill:#E6E6FA,stroke:#9370DB,color:#000
```
