# jolual2747/rag-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/jolual2747/rag-architecture
- Repository: https://github.com/jolual2747/rag-architecture

## Overview

##### Project type and purpose
- From the README and file tree, this is a full-stack RAG (Retrieval Augmented Generation) prototype for document-based Q&A and chatbots.
- Purpose: ingest documents, compute embeddings, store them in a vector database, retrieve relevant passages at query time, and generate answers via a generative LLM. Two frontends (Gradio and Streamlit) expose the Q&A/chatbot functionality.

##### File structure
- Top level
- assets/ (demo GIF)
- data/
– unprocessed, processed (CSV/TSV), embeddings folders, and a Chroma SQLite file
- notebooks/ (exploratory data prep, embedding creation, RAG prototyping)
- src/frontend/
– gradio_app.py, st_app.py, templates and utils
- Makefile, pyproject.toml (build scripts, dependencies)
- No separate “backend” folder: the core pipeline lives in notebooks and is invoked by each frontend.
- Vector DB persistence & file-based embeddings indicate a file-system–based data layer rather than a service.

##### README insights
- Describes RAG concepts, Langchain + OpenAI embeddings, vector DB (Chroma), and two UX surfaces: chatbot and Streamlit document Q&A.
- Build instructions for Gradio (`make build_gradio_app`) and Streamlit (`make build_streamlit_app`).

##### Main components & their interactions (
a. Data Ingestion & Processing
- Raw documents (PDF, CSV) → preprocessing scripts (notebooks/utils.py) → cleaned data (data/processed/*.csv/tsv)
b. Embedding Generation
- Cleaned text → OpenAI Embeddings API → embeddings files + Chroma SQLite database (data/data_embeddings/)
c. Vector Database
- Chroma (on‐disk SQLite) storing vectors + metadata; provides similarity search
d. Retrieval Layer
- Langchain Retriever configured to query Chroma
e. Generative LLM
- OpenAI Chat/Completion API that takes retrieved passages + prompt template → generates answer
f. Frontend Applications
- Gradio app (src/frontend/gradio_app.py)
- Streamlit app (src/frontend/st_app.py)
– both call into the same RAG pipeline: retrieve + generate

External Services
- OpenAI Embeddings API
- OpenAI Chat/Completion API

##### Architectural patterns & design principles
- Pipeline pattern: sequential stages (ingest → embed → store → retrieve → generate → serve)
- Separation of concerns: data layer, embedding service, vector DB, retrieval, generation, UI layers
- Reusability: notebooks for prototyping; utils for shared code; two interchangeable frontend wrappers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        RawDocs["Raw Documents\n(data/unprocessed/)"]:::data
        CleanData["Cleaned Data\n(data/processed/)"]:::data
    end

    %% Processing & Embeddings
    subgraph "Processing & Embedding Generation"
        Preprocessing["Document Preprocessing"]:::process
        EmbeddingNotebook["Embedding Generation Service"]:::process
    end

    %% Storage
    subgraph "Storage"
        EmbeddingFiles["Embedding Files\n(data/data_embeddings/)"]:::storage
        VectorDB["Chroma Vector DB"]:::storage
    end

    %% Retrieval & Generation
    subgraph "Retrieval & Generation"
        Retriever["Langchain Retriever"]:::process
        LLMWrapper["Generative LLM Wrapper"]:::process
    end

    %% External Services
    subgraph "External Services"
        OpenAIEmbed["OpenAI Embeddings API"]:::external
        OpenAIChat["OpenAI Chat/Completion API"]:::external
    end

    %% Frontends
    subgraph "Frontends"
        Gradio["Gradio Frontend"]:::ui
        Streamlit["Streamlit Frontend"]:::ui
    end

    %% Prototyping/Dev Tools
    subgraph "Prototyping/Dev Tools"
        RagNotebook["RAG Prototyping Notebook"]:::process
        UtilsNotebook["Data & Embedding Utils Notebook"]:::process
    end

    %% Data Flows
    RawDocs -->|preprocess| Preprocessing
    Preprocessing -->|outputs cleaned data| CleanData
    CleanData -->|generate embeddings| EmbeddingNotebook
    EmbeddingNotebook -->|calls| OpenAIEmbed
    EmbeddingNotebook -->|writes embeddings| EmbeddingFiles
    EmbeddingFiles -->|stores vectors| VectorDB
    VectorDB -->|provides similarity search| Retriever
    Retriever -->|retrieves passages| LLMWrapper
    LLMWrapper -->|calls| OpenAIChat
    LLMWrapper -->|returns answer| Gradio
    LLMWrapper -->|returns answer| Streamlit
    Gradio -->|query pipeline| Retriever
    Streamlit -->|query pipeline| Retriever

    %% Prototyping Links
    RagNotebook -.-> Preprocessing
    RagNotebook -.-> EmbeddingNotebook
    UtilsNotebook -.-> Preprocessing
    UtilsNotebook -.-> EmbeddingNotebook

    %% Click Events
    click Preprocessing "https://github.com/jolual2747/rag-architecture/blob/master/notebooks/utils.py"
    click RawDocs "https://github.com/jolual2747/rag-architecture/tree/master/data/unprocessed/"
    click CleanData "https://github.com/jolual2747/rag-architecture/blob/master/data/processed/clean_dataframe.csv"
    click EmbeddingNotebook "https://github.com/jolual2747/rag-architecture/blob/master/notebooks/embeddings.ipynb"
    click EmbeddingFiles "https://github.com/jolual2747/rag-architecture/tree/master/data/data_embeddings/"
    click VectorDB "https://github.com/jolual2747/rag-architecture/blob/master/data/data_embeddings/chroma.sqlite3"
    click Retriever "https://github.com/jolual2747/rag-architecture/blob/master/src/frontend/utils.py"
    click LLMWrapper "https://github.com/jolual2747/rag-architecture/blob/master/src/frontend/utils.py"
    click Gradio "https://github.com/jolual2747/rag-architecture/blob/master/src/frontend/gradio_app.py"
    click Streamlit "https://github.com/jolual2747/rag-architecture/blob/master/src/frontend/st_app.py"

    %% Styles
    classDef data fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef process fill:#FFD8B1,stroke:#E27A3F,color:#E27A3F;
    classDef storage fill:#D6F5D6,stroke:#28A745,color:#28A745,shape:cylinder;
    classDef external fill:#E2E2E2,stroke:#6C757D,color:#6C757D,shape:cloud;
    classDef ui fill:#EAD7FF,stroke:#6F42C1,color:#6F42C1,shape:parallelogram;
```
