# jamwithai/local-rag-system architecture

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

- Interactive diagram: https://gitdiagram.com/jamwithai/local-rag-system
- Repository: https://github.com/jamwithai/local-rag-system

## Overview

##### Project type and purpose
- This is a full‐stack, privacy‐focused Retrieval‐Augmented Generation (RAG) system.
- It provides both an ingestion pipeline (document OCR, embedding, indexing) and a retrieval/chat pipeline (hybrid search + LLM responses).
- The UI is implemented in Streamlit (welcome.py + pages/ directory), and the backend is pure Python modules under src/.

##### File structure
- Top level:
- welcome.py – entry point for the Streamlit app
- pages/ – two Streamlit pages (1_🤖_Chatbot.py, 2_📄_Upload_Documents.py)
- src/ – core modules for chat, ingestion, embeddings, OCR, OpenSearch, utilities, plus index_config.json
- embedding_model/ – local model and README for embedding extraction
- uploaded_files/ – persisted documents
- logs/ & app.log – logging
- Configuration files: requirements.txt, pyproject.toml, mypy.ini
- Notebooks/ for tutorials (not part of runtime architecture)

##### Extract insights from README
- Uses OpenSearch for hybrid (keyword + semantic) search.
- Uses Sentence Transformers for embeddings.
- Uses a local LLM for generation (in src/chat.py).
- Streamlit provides the UI layer.

##### Final advice
- Be as detailed as possible, capturing every src/*.py as a discrete element if helpful.
- Don’t overcomplicate: two main pipelines + supporting data/model stores.
- This clarity will make onboarding and future enhancements (e.g., swapping OpenSearch for another store) straightforward.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Welcome["Streamlit UI<br/>(welcome.py)"]:::frontend
        UploadPage["Upload Documents Page"]:::frontend
        ChatPage["Chatbot Page"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        subgraph "Ingestion Pipeline"
            direction TB
            IngestOrch["Ingestion Orchestrator"]:::backend
            OCR["OCR Module"]:::backend
            Embeds["Embeddings Module"]:::backend
            IndexClient["OpenSearch Client<br/>(Indexing)"]:::backend
            IndexConfig["Index Config"]:::backend
        end
        subgraph "Retrieval & Chat Pipeline"
            direction TB
            SearchClient["Hybrid Search Client"]:::backend
            ChatModule["Chat Module<br/>(RAG)"]:::backend
        end
        subgraph "Shared Utilities"
            direction TB
            Utils["Utility Functions"]:::backend
            Consts["Configuration Constants"]:::backend
        end
    end

    %% Data Stores & Models
    subgraph "Data & Models"
        direction TB
        OpenSearchCluster["OpenSearch Cluster"]:::datastore
        UploadedFiles["Uploaded Files Store"]:::datastore
        Logs["Logs"]:::datastore
        EmbeddingModel["Embedding Model Files"]:::external
        LLM["Local LLM"]:::external
    end

    %% Frontend to Backend
    UploadPage -->|"triggers ingestion"| IngestOrch
    ChatPage -->|"triggers query"| SearchClient

    %% Ingestion Flow
    IngestOrch --> OCR
    OCR --> Embeds
    Embeds --> IndexClient
    IndexClient --> OpenSearchCluster
    IngestOrch --> IndexConfig

    %% Retrieval Flow
    SearchClient --> OpenSearchCluster
    OpenSearchCluster --> SearchClient
    SearchClient --> ChatModule
    ChatModule --> LLM
    ChatModule --> ChatPage

    %% Utilities
    IngestOrch --> Utils
    SearchClient --> Utils
    ChatModule --> Utils
    IngestOrch --> Consts
    SearchClient --> Consts
    ChatModule --> Consts

    %% Uploaded Files & Logs
    UploadPage --> UploadedFiles
    IngestOrch --> UploadedFiles
    IngestOrch --> Logs
    SearchClient --> Logs
    ChatModule --> Logs

    %% Click Events
    click Welcome "https://github.com/jamwithai/local-rag-system/blob/main/welcome.py"
    click ChatPage "https://github.com/jamwithai/local-rag-system/blob/main/pages/1_🤖_Chatbot.py"
    click UploadPage "https://github.com/jamwithai/local-rag-system/blob/main/pages/2_📄_Upload_Documents.py"
    click OCR "https://github.com/jamwithai/local-rag-system/blob/main/src/ocr.py"
    click Embeds "https://github.com/jamwithai/local-rag-system/blob/main/src/embeddings.py"
    click IngestOrch "https://github.com/jamwithai/local-rag-system/blob/main/src/ingestion.py"
    click IndexConfig "https://github.com/jamwithai/local-rag-system/blob/main/src/index_config.json"
    click SearchClient "https://github.com/jamwithai/local-rag-system/blob/main/src/opensearch.py"
    click ChatModule "https://github.com/jamwithai/local-rag-system/blob/main/src/chat.py"
    click Utils "https://github.com/jamwithai/local-rag-system/blob/main/src/utils.py"
    click Consts "https://github.com/jamwithai/local-rag-system/blob/main/src/constants.py"
    click UploadedFiles "https://github.com/jamwithai/local-rag-system/tree/main/uploaded_files/"
    click Logs "https://github.com/jamwithai/local-rag-system/blob/main/logs/app.log"
    click EmbeddingModel "https://github.com/jamwithai/local-rag-system/tree/main/embedding_model/"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef backend fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef datastore fill:#ABEBC6,stroke:#145A32,color:#0B5345
    classDef external fill:#F9E79F,stroke:#9C640C,color:#7E5109
```
