# fuwad13/physics-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/fuwad13/physics-chatbot
- Repository: https://github.com/fuwad13/physics-chatbot

## Overview

##### Project Overview & Main Purpose
- This project is a full-stack chatbot focused on answering questions from Class 9-10 NCTB Physics textbooks.
- It employs a Retrieval-Augmented Generation (RAG) approach: first retrieving relevant physics documents from a vector database (Chroma) using embedding models, and then running locally hosted LLM models (via Ollama) to generate answers.

##### And Label Core Components
a. Frontend:
- Component: Chat User Interface
- File Reference: src/frontend/chat_ui.py (with initialization in src/frontend/__init__.py)
- Role: Presents the chat interface to end-users, collects user queries, and displays answers.

b. Backend:
- General Entry Point: main.py and config.py at the root for overall configuration.
- LLM and RAG Workflow:
- Located in src/backend/LLM where you see:
- The "chroma server" folder – this constitutes the vector database setup. The multiple subdirectories (identified by UUIDs) house binary files (data_level0.bin, header.bin, length.bin, link_lists.bin) that represent stored vectors and index metadata.
- The "llm-api" folder – likely a service endpoint or script (main.py inside it) that wraps around the LLM execution.
- The "data" folder under src/backend/LLM contains scripts for data ingestion (e.g., data_population.py) and reference QnA (reference_qna.py) as well as a reference PDF file.

c. Vector Database:
- Component: Chroma Server
- File/Folder Reference: src/backend/LLM/chroma server containing binary files and a chroma.sqlite3 file (which may store metadata or be used for persistence).
- Role: Stores document embeddings generated from physics content. It is crucial for retrieving relevant snippets when processing queries.

d. External LLM and Embeddings Service:
- Component: LLM Host (Ollama)
- Role: Provides locally hosted LLM models (like llama3.2, gemma2, mistral) used in combination with embedding models (e.g., all-MiniLM-L6-v2, nomic-embed-text) to process retrieval and generation.
- External services form part of the RAG pipeline and are indirectly referenced by the backend logic.

e. Testing and Evaluation:
- Component: Automated Testing Suite
- File/Folder Reference: testing/ (includes automated_testing.py, dataset curation scripts, and JSON datasets)
- Role: Validates system functionality, ensuring correct data flow and response generation.

##### Component Interactions and Data Flow
- User Interface (src/frontend) initiates a chat session by sending a query.
- The gateway (main.py at the root and within src/backend) receives this query and splits the workflow:
- It forwards the query to the vector database (Chroma Server) to retrieve relevant document snippets via embedding models.
- The retrieved context is sent, along with the original query, to the LLM API (in src/backend/LLM/llm-api) which interacts with the locally hosted LLMs (via Ollama) to generate the answer.
- Request from Frontend to Backend.
- Retrieval request from Backend to Chroma vector store.
- Processing step that involves external LLM models for answer generation.
- Response flow from Backend back to Frontend.

##### Architectural Patterns and Design Principles
- RAG Workflow: Clearly design the pipeline that decouples document retrieval from natural language generation.
- Modularity: Separate components for UI, backend processing, database interactions (chroma server), and LLM interfacing.
- Extensibility: Highlight the modular directory structure that enables additions like new embedding models, further API endpoints (e.g., in llm-api), or testing modules.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Layer"
        FUI["Frontend Chat UI"]:::frontend
    end

    subgraph "Backend Layer"
        BC["Backend Controller (Entry: main.py, config.py)"]:::backend
        subgraph "LLM and RAG Workflow"
            DB["Chroma Server (Vector DB)"]:::database
            API["LLM API Service"]:::backend
            LI["Data Ingestion & QnA Scripts"]:::backend
            EXT["LLM Service - Ollama (External)"]:::external
        end
    end

    subgraph "Testing"
        TEST["Automated Testing Suite"]:::testing
    end

    %% Data Flow
    FUI -->|"sendsQuery"| BC
    BC -->|"retrievesDocs"| DB
    DB -->|"returnsContext"| API
    API -->|"callsLLM"| EXT
    EXT -->|"returnsAnswer"| API
    API -->|"aggregatesResponse"| BC
    BC -->|"sendsAnswer"| FUI
    LI ---|"populatesData"| DB
    TEST ---|"validatesSystem"| BC

    %% Click Events
    click FUI "https://github.com/fuwad13/physics-chatbot/blob/main/src/frontend/chat_ui.py"
    click BC "https://github.com/fuwad13/physics-chatbot/blob/main/main.py"
    click DB "https://github.com/fuwad13/physics-chatbot/tree/main/src/backend/LLM/chroma server"
    click API "https://github.com/fuwad13/physics-chatbot/blob/main/src/backend/LLM/llm-api/main.py"
    click LI "https://github.com/fuwad13/physics-chatbot/tree/main/src/backend/LLM/data"
    click TEST "https://github.com/fuwad13/physics-chatbot/tree/main/testing/"

    %% Styles
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#cdf,stroke:#333,stroke-width:2px;
    classDef database fill:#bfb,stroke:#333,stroke-width:2px;
    classDef external fill:#fbb,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffb,stroke:#333,stroke-width:2px;
```
