# vincentkoc/airgapped-offfline-rag architecture

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

- Interactive diagram: https://gitdiagram.com/vincentkoc/airgapped-offfline-rag
- Repository: https://github.com/vincentkoc/airgapped-offfline-rag

## Overview

##### Main Components
a. User Interface (UI) – the Streamlit front-end
b. Backend Application – “app/” codebase
- DocumentProcessor (app/document_processor.py)
- RAG Orchestrator (app/rag.py) using LangChain
- ModelHandler (app/model_handler.py) invoking local Llama C++/Gemini/Mistral
- Utility functions (app/utils.py)
c. Vector Storage – ChromaDB (or Qdrant via Chromadb API)
d. Model Store – local filesystem folder “models/” containing GGUF files
e. Configuration – config.yaml, .env, example.env
f. Persistence – “documents/” for uploaded PDFs
g. Infrastructure – Docker, Docker-Compose, Makefile

##### Relationships & Data Flow
1. User uploads a PDF via Streamlit UI.
2. UI sends file + query request to the Backend Application.
3. DocumentProcessor reads PDF → splits into chunks → calls Sentence-Transformer to embed.
4. Embeddings are written to Vector Storage (ChromaDB).
5. On question submit, RAG Orchestrator:
a. Queries Vector Storage for top-k relevant chunks
b. Builds prompt (including retrieved chunks)
c. Calls ModelHandler to invoke llama.cpp (or analogous local binaries)
d. Receives streamed response
6. Response is returned to UI for display.
7. All components read parameters (model paths, chunk sizes) from config.yaml/.env.

##### Architectural Patterns & Technologies
- Modular monolith: single container running Streamlit + Python modules
- Retrieval-Augmented Generation via LangChain (app/rag.py)
- Local LLM inference with llama.cpp + GGUF models (app/model_handler.py)
- Vector database integration (ChromaDB) for offline embeddings
- Docker Compose orchestration for service lifecycle
- Test suite (pytest + tox) for component validation

– Clearly labeled components and containers
– Annotations of key libraries/frameworks (LangChain, llama.cpp, Streamlit)
– Configuration flow from config.yaml/.env into modules
– Optional: include ports (e.g., Streamlit:8501, ChromaDB:8000)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: App Container
    subgraph "App Container"
        direction TB
        UI["Streamlit UI<br/>(Streamlit 1.x)"]:::frontend
        DP["DocumentProcessor"]:::code
        RAG["RAG Orchestrator<br/>(LangChain)"]:::code
        MH["ModelHandler<br/>(llama.cpp GGUF)"]:::code
        Utils["Utility Functions"]:::code
        Config["Configuration<br/>(config.yaml/.env)"]:::config
    end

    %% Subgraph: External Storage
    subgraph "External Storage"
        direction TB
        VectorDB["ChromaDB<br/>(Chromadb 0.x)"]:::db
        ModelStore["Model Store<br/>(models/)"]:::folder
        Persistence["PDF Storage<br/>(documents/)"]:::doc
    end

    %% Subgraph: Infrastructure
    subgraph "Infrastructure"
        direction TB
        DC["Docker Compose"]:::infra
        DF["Dockerfile"]:::infra
        MF["Makefile"]:::infra
    end

    %% Data Flow
    UI -->|"upload PDF & query"| DP
    Persistence -->|stores PDFs| DP
    DP -->|"embeddings"| VectorDB
    UI -->|"submit question"| RAG
    RAG -->|"top-k query"| VectorDB
    VectorDB -->|"retrieved chunks"| RAG
    RAG -->|"prompt"| MH
    MH -->|"streamed response"| RAG
    RAG -->|"answer"| UI

    %% Config Injection
    Config --> UI
    Config --> DP
    Config --> RAG
    Config --> MH
    Config --> Utils

    %% Model download (one-time)
    subgraph "Setup (One-Time)"
        direction TB
        Internet((Internet)):::external
        Internet -.->|download<br/>Sentence-Transformer| DP
        Internet -.->|download models| ModelStore
    end

    %% Infrastructure links
    DC -->|orchestrates| DF
    DC -->|defines services| MF

    %% Click Events
    click UI "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/app/main.py"
    click DP "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/app/document_processor.py"
    click RAG "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/app/rag.py"
    click MH "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/app/model_handler.py"
    click Utils "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/app/utils.py"
    click Config "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/config.yaml"
    click ModelStore "https://github.com/vincentkoc/airgapped-offfline-rag/tree/main/models/"
    click Persistence "https://github.com/vincentkoc/airgapped-offfline-rag/tree/main/documents/"
    click DC "https://github.com/vincentkoc/airgapped-offfline-rag/blob/main/docker-compose.yml"
    click DF "https://github.com/vincentkoc/airgapped-offfline-rag/tree/main/dockerfile"
    click MF "https://github.com/vincentkoc/airgapped-offfline-rag/tree/main/Makefile"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef frontend fill:#FFF5D0,stroke:#D4A017,color:#D4A017;
    classDef db fill:#D0FFD6,stroke:#028A0F,color:#028A0F,stroke-width:2px;
    classDef folder fill:#FFF0B3,stroke:#D4A017,color:#D4A017,stroke-dasharray: 5 5;
    classDef doc fill:#FFE0E0,stroke:#D41717,color:#D41717;
    classDef config fill:#E8E8E8,stroke:#666666,color:#333333,stroke-dasharray: 2 2;
    classDef infra fill:#F0E0FF,stroke:#8A17D4,color:#8A17D4;
    classDef external fill:#FFFFFF,stroke:#AAAAAA,color:#555555,stroke-dasharray: 2 2;
```
