# juancvalencias/chat-rag architecture

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

- Interactive diagram: https://gitdiagram.com/juancvalencias/chat-rag
- Repository: https://github.com/juancvalencias/chat-rag

## Overview

##### Project type and purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) prototype built with Python and Streamlit.
- It ingests a PDF (“23_migracion.pdf”), splits it into chunks, computes embeddings via a local Ollama “nomic-embed-text” model, stores them in an in-memory vector store, and then answers user questions by retrieving relevant chunks and forwarding them (with context) to a local Llama2 LLM via Ollama.

##### File structure
- Top level
- README.md – project description and setup steps
- pyproject.toml – Python dependencies and project metadata
- data/23_migracion.pdf – source document for RAG
- temp.pdf – probably a scratch/test file
- src/
- app.py – Streamlit UI and entry point
- rag.py – core RAG pipeline (PDF loader, chunker, embedding, retrieval, LLM call)
- test_pdf_loader.py – unit test for PDF ingestion/chunking
- test_embeddings.py – unit test for embedding integration
- Configuration
- .python-version – pinned Python version
- .gitignore – excludes environment, temp files

##### Insights from README
- Requires Ollama local server with two models pulled:
- “llama2:7b” for generation
- “nomic-embed-text:latest” for embeddings
- Run via `uv run streamlit run app.py` in the src/ directory.

a. Main Components
1. User Interface (Streamlit app.py)
2. RAG Pipeline (rag.py), comprising:
– PDF Loader & Chunker
– Embedding Engine (nomic-embed-text via Ollama)
– Vector Store (in-memory or lightweight DB)
– Retriever (nearest-neighbor search)
– LLM Service (Llama2 via Ollama)
3. Data Store
– Local file system storing the source PDF
4. External Services
– Ollama server hosting the two models
b. Relationships & Interactions
- User submits a question in the Streamlit UI
- UI calls RAG pipeline
- PDF Loader reads chunks (or reuses cached chunks)
- Chunks passed to embedding service → embedding vectors
- Vectors indexed/stored in vector store
- Query embedding compared to stored vectors → top-k contexts
- Context + user question sent to LLM service → answer
- UI renders the generated response
c. Architectural Patterns
- Layered separation: Presentation (UI), Application (RAG pipeline), Data (vector store + PDF), Infrastructure (Ollama models)
- Single-process Python app, but clear module boundaries (app.py vs rag.py)
d. Key Technologies
- Python 3.x, Streamlit, Ollama CLI/daemon
- nomic-embed-text model, llama2:7b model
- pyproject.toml / pip for dependency management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User"]:::external
    UI["Streamlit UI<br>(app.py)"]:::frontend

    %% Pipeline Layer
    subgraph "RAG Pipeline" 
        direction TB
        Loader["PDF Loader & Chunker"]:::pipeline
        Embed["Embedding Engine<br>(nomic-embed-text)"]:::pipeline
        Store["Vector Store<br>(in-memory)"]:::pipeline
        Retrieve["Retriever<br>(nearest-neighbor search)"]:::pipeline
        LLM["LLM Service<br>(llama2:7b)"]:::pipeline
    end

    %% Data Layer
    subgraph "Data Store"
        direction TB
        PDF["Source Document<br>(23_migracion.pdf)"]:::data
    end

    %% External Services
    Ollama["Ollama Server<br>(embedding & generation)"]:::external

    %% Testing Modules
    subgraph "Testing"
        direction TB
        TestLoader["test_pdf_loader.py"]:::test
        TestEmbed["test_embeddings.py"]:::test
    end

    %% Config & Metadata
    subgraph "Configuration & Metadata"
        direction TB
        Metadata["pyproject.toml"]:::config
        Env[".python-version<br>.gitignore"]:::config
        README["README.md"]:::config
    end

    %% Connections
    User -->|"asks question"| UI
    UI -->|"invoke RAG pipeline"| Loader
    Loader -->|"read chunks from PDF"| PDF
    Loader -->|"send chunks"| Embed
    Embed -->|"return embeddings"| Store
    Store -->|"perform index"| Retrieve
    Retrieve -->|"top-k contexts + query"| LLM
    LLM -->|"generated answer"| UI
    UI -->|"display answer"| User
    Embed --> Ollama
    LLM --> Ollama

    %% Testing connections
    Loader --> TestLoader
    Embed --> TestEmbed

    %% Click Events
    click UI "https://github.com/juancvalencias/chat-rag/blob/main/src/app.py"
    click Loader "https://github.com/juancvalencias/chat-rag/blob/main/src/rag.py"
    click Embed "https://github.com/juancvalencias/chat-rag/blob/main/src/rag.py"
    click Store "https://github.com/juancvalencias/chat-rag/blob/main/src/rag.py"
    click Retrieve "https://github.com/juancvalencias/chat-rag/blob/main/src/rag.py"
    click LLM "https://github.com/juancvalencias/chat-rag/blob/main/src/rag.py"
    click TestLoader "https://github.com/juancvalencias/chat-rag/blob/main/src/test_pdf_loader.py"
    click TestEmbed "https://github.com/juancvalencias/chat-rag/blob/main/src/test_embeddings.py"
    click PDF "https://github.com/juancvalencias/chat-rag/blob/main/data/23_migracion.pdf"
    click Metadata "https://github.com/juancvalencias/chat-rag/blob/main/pyproject.toml"
    click Env "https://github.com/juancvalencias/chat-rag/blob/main/.python-version"
    click Env "https://github.com/juancvalencias/chat-rag/blob/main/.gitignore"
    click README "https://github.com/juancvalencias/chat-rag/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef pipeline fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef data fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef external fill:#FADBD8,stroke:#C0392B,color:#641E16;
    classDef test fill:#E8DAEF,stroke:#6C3483,color:#4A235A;
    classDef config fill:#F2F3F4,stroke:#566573,color:#2C3E50;
```
