# hitrong/rag-student-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/hitrong/rag-student-chatbot
- Repository: https://github.com/hitrong/rag-student-chatbot

## Overview

##### Project Type & Purpose
- This project is a full-stack application intended to help Vietnamese students by providing a chatbot that supports both a normal LLM chat mode and a Retrieval Augmented Generation (RAG) chat mode.
- The system not only provides chatbot responses but also manages document data (Word and PDF) using a vector database (using FAISS) to offer context-based responses.

##### Analyzing the File Structure
- The top-level files include configuration files (db_config.yml, history_config.yml, model_config.yml) that set up model paths and database settings.
- The main application file is application.py, which is initiated using Streamlit.
- There are several modules like llm_chain.py (LLM chain logic), history_handle.py (session management), prompt_template.py (prompts), vectordb.py (handling vector database interactions), and utils.py.
- The data_store folder contains documents (example Word docs) and a vector_db directory with FAISS index files.
- The structure shows separation between core logic (chaining, history, and vector database management) and static configuration/document resources.

##### Key Components
a. Frontend / UI Layer:
- Streamlit Web Application (application.py) that acts as the user interface where students interact with the chatbot.
b. Chatbot Logic Layer (Business Logic):
- Normal LLM Chatbot Module (using llm_chain.py) that uses a standard prompt template from prompt_template.py.
- RAG Chatbot Module (same llm_chain.py but with added retrieval process) that queries the Vector Database.
c. Data Retrieval / Vector Database:
- A VectorDB module (vectordb.py) that handles document embedding, similarity searches, and interacts with FAISS indices (data_store/vector_db/faiss) to retrieve relevant context.
- Local Document Storage (data_store/word, and wherever PDF/documents are stored) that are indexed.
d. Session & History Management:
- A session system backed by history_handle.py that captures and manages conversation history, including extracting session names using keywords.
e. Configuration & Model Management:
- Model configuration is managed through model_config.yml (e.g., specifying the path for the Vinallama model from Hugging Face).
- Other configuration files (db_config.yml, history_config.yml) set up underlying system parameters.
f. External Dependencies & Libraries:
- Hugging Face’s Sentence Transformer for embeddings.
- LangChain (LLMChain and RetrievalQA patterns) which orchestrate the LLM interactions.
- FAISS for the vector database.
- Streamlit for delivering the web UI.

## Diagram (Mermaid)

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

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        LLM["LLM Chatbot (LLMChain)"]:::business
        Prompt["Prompt Template"]:::business
        RAG["RAG Chatbot (RetrievalQA)"]:::business
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        VectorDB["Vector Database (FAISS)"]:::data
        FAISS["FAISS Index"]:::data
        Doc["Document Storage"]:::data
    end

    %% Session Management
    subgraph "Session Management"
        Session["Session/History Management"]:::session
    end

    %% Configuration & External Components
    subgraph "Configuration & External Components"
        ModelConf["model_config.yml"]:::config
        DBConf["db_config.yml"]:::config
        HistConf["history_config.yml"]:::config
        Ext["External Libraries (HuggingFace, LangChain, FAISS, SentenceTransformer)"]:::external
    end

    %% Connections from UI to Business Logic
    UI -->|"chatMessage"| LLM
    UI -->|"chatMessage"| RAG

    %% Business Logic Internal connections
    LLM -->|"uses"| Prompt
    Session -->|"providesHistory"| LLM
    Session -->|"providesHistory"| RAG

    %% RAG Chatbot connects to Data Access Layer
    RAG -->|"retrievalQuery"| VectorDB
    VectorDB -->|"indexLookup"| FAISS
    VectorDB -->|"documentScan"| Doc

    %% Configuration influences Business Logic
    ModelConf -.-> LLM
    DBConf -.-> VectorDB
    HistConf -.-> Session

    %% External Libraries utilized by Business Logic and Data Access
    Ext -.-> LLM
    Ext -.-> RAG
    Ext -.-> VectorDB

    %% Click events for mapped components
    click UI "https://github.com/hitrong/rag-student-chatbot/blob/main/application.py"
    click LLM "https://github.com/hitrong/rag-student-chatbot/blob/main/llm_chain.py"
    click Prompt "https://github.com/hitrong/rag-student-chatbot/blob/main/prompt_template.py"
    click RAG "https://github.com/hitrong/rag-student-chatbot/blob/main/vectordb.py"
    click VectorDB "https://github.com/hitrong/rag-student-chatbot/blob/main/vectordb.py"
    click FAISS "https://github.com/hitrong/rag-student-chatbot/tree/main/data_store/vector_db/faiss"
    click Doc "https://github.com/hitrong/rag-student-chatbot/tree/main/data_store/word"
    click Session "https://github.com/hitrong/rag-student-chatbot/blob/main/history_handle.py"
    click ModelConf "https://github.com/hitrong/rag-student-chatbot/blob/main/model_config.yml"
    click DBConf "https://github.com/hitrong/rag-student-chatbot/blob/main/db_config.yml"
    click HistConf "https://github.com/hitrong/rag-student-chatbot/blob/main/history_config.yml"

    %% Styles
    classDef frontend fill:#FFDDCC,stroke:#B36B00,stroke-width:2px;
    classDef business fill:#CCE5FF,stroke:#00509E,stroke-width:2px;
    classDef data fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef session fill:#FFF3CD,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#F9EBEA,stroke:#922B21,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;
```
