# jamwithai/build_your_local_rag_system architecture

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

- Interactive diagram: https://gitdiagram.com/jamwithai/build_your_local_rag_system
- Repository: https://github.com/jamwithai/build_your_local_rag_system

## Overview

##### Main Components
- Frontend/UI:
- This is represented by the Streamlit entry point (Welcome.py) and supporting pages (found in the “pages” directory, e.g., the Chatbot and Upload Documents pages). These provide the user interface where users interact with the system.
- Document Processing & Ingestion:
- Modules in the “src” folder such as ingestion.py and ocr.py handle the processing of incoming documents (including OCR if needed) and prepare them for further processing.
- Embedding Generation:
- The embeddings.py module (and the “embedding_model” folder) is responsible for transforming documents into vector representations using Sentence Transformers or a similar technology.
- Search and Indexing:
- opensearch.py in “src” indicates integration with OpenSearch. This component handles indexing of document embeddings and performing hybrid search (traditional text matching + semantic search).
- Chat/LLM Interaction:
- The chat.py module in “src” seems to facilitate the conversation logic, integrating responses from a local LLM to generate context-aware answers based on retrieved documents.
- Configuration & Utilities:
- constant.py and index_config.json store configuration parameters and settings. The utils.py module provides supporting functionality.
- Logging & Monitoring:
- There are multiple logging setups (app.log at the root and inside the “logs” directory) to capture system events.

##### Relationships and Data Flow
- User interactions via the Frontend trigger document upload or chat-based queries.
- For uploaded documents:
- The Frontend routes the file uploads to the ingestion module (src/ingestion.py) and the OCR module (src/ocr.py) if needed.
- Processed documents are then passed to the embedding generator (src/embeddings.py) to create vector representations.
- These representations get stored/indexed in OpenSearch through the opensearch.py module.
- For query handling:
- A user’s query is received by the Frontend and forwarded to the chat module (src/chat.py).
- The chat module uses OpenSearch to retrieve relevant document embeddings.
- The system then uses the local LLM (configured via constants in constants.py) to generate natural language responses that augment the retrieved information.
- The data flow also includes logs-generation and error/exception monitoring across every stage.

##### Architectural Patterns & Technologies
- The design follows a layered architecture that separates the UI, business logic (ingestion, processing, embedding generation), and data layer (OpenSearch).
- A modular design is evident with clearly delineated roles for each module.
- Dependency injection is possible via configuration files (like constants.py and index_config.json).
- Technologies/Frameworks:
- Frontend: Streamlit (as indicated by the Welcome.py and pages scripts).
- Search and indexing: OpenSearch.
- AI Components: Local LLMs and Sentence Transformers handling the document embeddings and text generation.
- Auxiliary libraries and utilities (as referenced by pyproject.toml and requirements.txt).

## Diagram (Mermaid)

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

    %% Frontend/UI Subgraph
    subgraph "Frontend/UI"
        F1["Welcome.py"]:::frontend
        F2["Chatbot Page"]:::frontend
        F3["Upload Documents Page"]:::frontend
    end

    %% Document Processing & Ingestion Subgraph
    subgraph "Document Processing & Ingestion"
        D1["Ingestion Module (src/ingestion.py)"]:::processing
        D2["OCR Module (src/ocr.py)"]:::processing
    end

    %% Embedding Generation Subgraph
    subgraph "Embedding Generation"
        E1["Embeddings Module (src/embeddings.py)"]:::embedding
        E2["Embedding Model Directory"]:::embedding
    end

    %% Search and Indexing Subgraph
    subgraph "Search and Indexing"
        S1["OpenSearch Integration (src/opensearch.py)"]:::search
        S2["OpenSearch Service"]:::external
    end

    %% Chat/LLM Interaction Subgraph
    subgraph "Chat/LLM Interaction"
        C1["Chat Module (src/chat.py)"]:::chat
    end

    %% Configuration & Utilities Subgraph
    subgraph "Configuration & Utilities"
        U1["Constants (src/constants.py)"]:::config
        U2["Index Config (src/index_config.json)"]:::config
        U3["Utils (src/utils.py)"]:::config
    end

    %% Logging & Monitoring Subgraph
    subgraph "Logging & Monitoring"
        L1["App Log (app.log)"]:::logging
        L2["Logs Directory (logs/)"]:::logging
    end

    %% Data Flow Connections
    User --> F1
    User --> F2
    User --> F3

    %% Document Upload Flow
    F3 -->|"SendsDocument"| D1
    F3 -->|"SendsDocument"| D2
    D1 -->|"ProcessesDoc"| E1
    D2 -->|"OCROutput"| E1
    E1 -->|"UsesModel"| E2
    E1 -->|"IndexEmbeddings"| S1
    S1 -->|"StoresData"| S2

    %% Chat Query Flow
    F2 -->|"SendsQuery"| C1
    C1 -->|"RetrieveEmbedding"| S1
    S1 -->|"ReturnResults"| C1
    C1 -->|"LLMResponse"| F2

    %% Configuration & Utilities Dependencies
    D1 ---|"UsesConfig"| U1
    D2 ---|"UsesConfig"| U1
    E1 ---|"UsesConfig"| U2
    S1 ---|"UsesConfig"| U3
    C1 ---|"UsesConfig"| U1

    %% Logging Flow (dotted lines indicate logging)
    D1 ---|"Logs"| L1
    D1 ---|"Logs"| L2
    D2 ---|"Logs"| L1
    D2 ---|"Logs"| L2
    E1 ---|"Logs"| L1
    S1 ---|"Logs"| L1
    C1 ---|"Logs"| L1

    %% Click Events for Frontend/UI
    click F1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/Welcome.py"
    click F2 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/pages/1_🤖_Chatbot.py"
    click F3 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/pages/2_📄_Upload_Documents.py"

    %% Click Events for Document Processing & Ingestion
    click D1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/ingestion.py"
    click D2 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/ocr.py"

    %% Click Events for Embedding Generation
    click E1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/embeddings.py"
    click E2 "https://github.com/jamwithai/build_your_local_rag_system/tree/main/embedding_model/"

    %% Click Events for Search and Indexing
    click S1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/opensearch.py"

    %% Click Event for Chat/LLM Interaction
    click C1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/chat.py"

    %% Click Events for Configuration & Utilities
    click U1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/constants.py"
    click U2 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/index_config.json"
    click U3 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/src/utils.py"

    %% Click Events for Logging & Monitoring
    click L1 "https://github.com/jamwithai/build_your_local_rag_system/blob/main/app.log"
    click L2 "https://github.com/jamwithai/build_your_local_rag_system/tree/main/logs/"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef processing fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef embedding fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef search fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef chat fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef config fill:#E1BEE7,stroke:#9C27B0,stroke-width:2px;
    classDef logging fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;
    classDef external fill:#CFD8DC,stroke:#607D8B,stroke-width:2px;
```
