# jfagan/llm-rag-invoice-haystack architecture

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

- Interactive diagram: https://gitdiagram.com/jfagan/llm-rag-invoice-haystack
- Repository: https://github.com/jfagan/llm-rag-invoice-haystack

## Overview

##### Project Type and Purpose
- This is a Retrieval-Augmented Generation (RAG) pipeline for invoice data extraction and Q&A, using:
- Haystack 2 for document retrieval
- Weaviate as the vector store
- Llama2 (hosted on Hugging Face) as the LLM
- Docker Compose for full containerization

##### File Structure
- Root:
- docker-compose.yml & dockerfile → container orchestration
- ingest.py → ingestion pipeline (PDF → embeddings)
- main.py → query/answer pipeline (CLI → answer)
- llm/ folder:
- llm.py, prompts.py, wrapper.py → LLM integration (prompt templating + HF API calls)
- data/ folder:
- invoice PDFs fed to ingest.py
- config.yml, requirements.txt → configuration & dependencies

##### README Insights
- “docker-compose up --build” spins up:
1. Application container
2. Weaviate vector database container
- ingest.py loads PDFs → vector embeddings in Weaviate
- main.py executes a Haystack retrieval + LLM generation pipeline

##### Main Components & Their Interactions
a. Data Source
- Local `data/` directory (invoice_1.pdf, etc.)
b. Ingestion Service
- ingest.py reads PDFs → uses Haystack DocumentStore + Weaviate client → stores embeddings
c. Vector Store
- Weaviate container (Docker Compose service) — holds embeddings & metadata
d. Retrieval & LLM Service
- main.py initializes Haystack pipeline:
- Retriever queries Weaviate → retrieves top-k document chunks
- Reader/Generator uses Llama2 via Hugging Face API through llm.wrapper
e. External Services
- Hugging Face Model Hub (Llama2) — accessed via API token
f. Orchestration
- Docker Compose network connecting the app container and Weaviate

##### Architectural Patterns & Design Principles
- Pipeline pattern: ingest → index → retrieve → generate
- Separation of concerns:
- Ingest module vs. Query module
- Document storage (Weaviate) vs. compute (app container)
- Containerization ensures environment parity

##### Essential Details to Capture
- The llm/ folder’s role in abstracting prompt logic and API calls
- The fact that Weaviate is spun up locally but acts as an external vector DB
- How PDF files flow from disk → embeddings → vector store → downstream retrieval
- The user-facing CLI (main.py) feeding natural-language queries into the pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Container Orchestration
    subgraph "Container Orchestration"
        DC["docker-compose.yml"]:::infra
        DF["dockerfile"]:::infra
    end

    %% Infrastructure
    subgraph "Infrastructure"
        WV["Weaviate Service"]:::infra
    end

    %% Application Modules
    subgraph "Application Modules"
        %% Ingestion
        subgraph "Ingestion Service"
            DS["Local Data Store\n(data/)"]:::data
            ING["ingest.py"]:::app
        end
        %% Query
        subgraph "Query Service"
            CLI["CLI Input/Output"]:::app
            Q["main.py"]:::app
            subgraph "LLM Integration"
                LM["llm/"]:::app
            end
        end
        CFG["config.yml"]:::config
        REQ["requirements.txt"]:::config
        SP["prompts-structured.txt"]:::config
    end

    %% External
    HF["Hugging Face API\n(Llama2)"]:::external

    %% Connections
    DS -->|reads PDFs| ING
    ING -->|stores embeddings| WV
    DC -->|defines Weaviate service| WV
    DC -->|orchestrates app| ING
    DF -->|builds app container| ING
    CLI -->|user query| Q
    Q -->|retrieves chunks| WV
    Q -->|calls LLM| HF
    HF -->|returns generation| Q
    Q -->|outputs answer| CLI

    %% Click Events
    click DS "https://github.com/jfagan/llm-rag-invoice-haystack/tree/main/data/"
    click ING "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/ingest.py"
    click DC "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/docker-compose.yml"
    click DF "https://github.com/jfagan/llm-rag-invoice-haystack/tree/main/dockerfile"
    click WV "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/docker-compose.yml"
    click Q "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/main.py"
    click LM "https://github.com/jfagan/llm-rag-invoice-haystack/tree/main/llm/"
    click CFG "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/config.yml"
    click REQ "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/requirements.txt"
    click SP "https://github.com/jfagan/llm-rag-invoice-haystack/blob/main/prompts-structured.txt"

    %% Styles
    classDef app fill:#D0E8FF,stroke:#3399FF,stroke-width:2px;
    classDef infra fill:#D6F5D6,stroke:#33CC33,stroke-width:2px;
    classDef data fill:#FFE6CC,stroke:#FF9900,stroke-width:2px;
    classDef external fill:#E5CCFF,stroke:#9933FF,stroke-width:2px;
    classDef config fill:#F2F2F2,stroke:#999999,stroke-width:2px;
```
