# harsh-br0/chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/harsh-br0/chatbot
- Repository: https://github.com/harsh-br0/chatbot

## Overview

##### Project Type and Purpose
- This is a specialized full-stack chatbot application that uses Retrieval-Augmented Generation (RAG) to support context-aware conversation.
- It leverages FastAPI as the backend API server, MongoDB (with a manual vector search index) for document and history storage, and Hugging Face models (via local download or API) for embeddings and response generation.
- The project also utilizes LangChain to manage the conversation chain.

##### Main Components
- API Server (Backend): The project’s entry point is main.py which starts the FastAPI server.
- Chatbot Logic Module (chatbot package): Contains overall chatbot orchestration with components such as:
- Chain management (chain.py): Likely orchestrates how inputs are processed through retrieval and LLM generation.
- Document Loaders (in chatbot/document_loader): Different loaders for CSV, PDF, and text files allow processing of various document types.
- Database Components (in chatbot/database): Modules that manage storing chat history, interacting with MongoDB (mongo.py), and handling the vector store for embeddings (vector_store.py).
- Utility Files (such as defaults.py, functions.py, logging.py, and utils.py) that manage configurations, logging, and helper functionalities.
- Exception handling to ensure robust error management (exceptions.py).

- External Services / Dependencies:
- MongoDB: Acts as the persistence layer and hosts the vector search index (which must be created manually in Atlas).
- Hugging Face Models: Used for embeddings and chat responses (embedding model “all-mpnet-base-v2” runs locally and the LLM “TinyLlama-1.1B-Chat-v1.0” is accessed via the Inference API).
- LangChain: Supports chaining operations for the chatbot’s RAG mechanism.

##### Relationships and Data Flows
- A user sends a request (via the API endpoint provided by FastAPI in main.py).
- The request is processed by the chatbot’s chain management (chain.py) which involves:
- Loading and chunking documents through the document_loader modules.
- Generating vector embeddings using the Hugging Face embedding model.
- Storing or retrieving from the MongoDB vector store (managed via mongo.py and vector_store.py).
- The chain architecture then interacts with the LLM via the Hugging Face API (TinyLlama) to generate context-aware responses.
- Logging and error handling components provide observability during these steps.

##### Architectural Patterns and Important Design Principles
- Modular Design: The structure is organized into dedicated modules (document loaders, database interactions, chain logic), making it easier to extend or modify individual components.
- Separation of Concerns: There is a clear separation between API handling (FastAPI in main.py), business logic (chain and document loading), and persistence (MongoDB related code).
- API-driven Communication: The use of FastAPI and clear endpoints (as seen in the Swagger docs) ensures that API interactions are explicit and scalable.
- Data Pipelines: The flow from document ingestion, through vectorization, to chat response shows a cohesive pipeline which can be depicted as sequential blocks with directional data flow indications.

- API Component: Clearly mark the entry point (main.py) that proxies user requests.
- Database Integration: Emphasize how MongoDB is integrated both for chat history (chat_history.py) and for vector search through vector_store.py along with manual index creation.
- Model Integration: Represent the use of Hugging Face’s embedding model and LLM, noting that one runs locally while the other is accessed via an API.
- Configurations & Constants: Mention defaults defined in defaults.py which impact the streaming or chunking logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Request"]:::external
    A["API Server (FastAPI)"]:::api
    C["Chatbot Logic / Chain Management"]:::logic

    subgraph "Document Loaders"
        CSV["CSV Loader"]:::loader
        PDF["PDF Loader"]:::loader
        TXT["Text Loader"]:::loader
        LUTIL["Loader Utilities"]:::loader
    end

    subgraph "Database Module"
        CHAT["Chat History"]:::database
        MONGO["MongoDB Connections"]:::database
        VSTORE["Vector Store"]:::database
    end

    subgraph "Utilities & Configs"
        DEF["Defaults & Configurations"]:::utils
        HELP["Helper Functions"]:::utils
    end

    EXCEP["Exception Handling"]:::exception

    subgraph "External Services"
        EMB["Hugging Face Embedding Model"]:::external_service
        LLM["Hugging Face LLM"]:::external_service
        M_ATLAS["MongoDB Atlas"]:::external_service
    end

    %% Data Flow
    U -->|"sends_request"| A
    A -->|"handles_request"| C

    %% Document Loader interactions
    C -->|"loads_documents"| CSV
    C -->|"loads_documents"| PDF
    C -->|"loads_documents"| TXT
    C -->|"uses_utilities"| LUTIL

    CSV -->|"returns_data"| C
    PDF -->|"returns_data"| C
    TXT -->|"returns_data"| C
    LUTIL -->|"processes_data"| C

    %% Database interactions
    C -->|"stores_history"| CHAT
    C -->|"queries_db"| MONGO
    C -->|"manages_vectors"| VSTORE

    MONGO -->|"connects_to"| M_ATLAS
    VSTORE -->|"indexes_in"| M_ATLAS

    %% External Services interactions
    C -->|"generates_embeddings"| EMB
    C -->|"calls_LLM"| LLM

    %% Utility & Exception support
    C -.->|"config"| DEF
    C -.->|"helpers"| HELP
    C -.->|"error_handling"| EXCEP

    %% Click Events
    click A "https://github.com/harsh-br0/chatbot/blob/main/main.py"
    click C "https://github.com/harsh-br0/chatbot/blob/main/chatbot/chain.py"
    click CSV "https://github.com/harsh-br0/chatbot/blob/main/chatbot/document_loader/csv.py"
    click PDF "https://github.com/harsh-br0/chatbot/blob/main/chatbot/document_loader/pdf.py"
    click TXT "https://github.com/harsh-br0/chatbot/blob/main/chatbot/document_loader/text.py"
    click LUTIL "https://github.com/harsh-br0/chatbot/blob/main/chatbot/document_loader/loader.py"
    click CHAT "https://github.com/harsh-br0/chatbot/blob/main/chatbot/database/chat_history.py"
    click MONGO "https://github.com/harsh-br0/chatbot/blob/main/chatbot/database/mongo.py"
    click VSTORE "https://github.com/harsh-br0/chatbot/blob/main/chatbot/database/vector_store.py"
    click DEF "https://github.com/harsh-br0/chatbot/blob/main/chatbot/defaults.py"
    click HELP "https://github.com/harsh-br0/chatbot/blob/main/chatbot/functions.py"
    click EXCEP "https://github.com/harsh-br0/chatbot/blob/main/chatbot/exceptions.py"

    %% Styles
    classDef external fill:#bbdefb,stroke:#1976d2,stroke-width:2px;
    classDef api fill:#ffe082,stroke:#f57f17,stroke-width:2px;
    classDef logic fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef loader fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef database fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef utils fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef exception fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
    classDef external_service fill:#d7ccc8,stroke:#5d4037,stroke-width:2px;
```
