# shubhammandowara/llm_rag architecture

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

- Interactive diagram: https://gitdiagram.com/shubhammandowara/llm_rag
- Repository: https://github.com/shubhammandowara/llm_rag

## Overview

##### Project type and purpose
- This is a lightweight full-stack (client + server logic) web application built with Streamlit.
- Its purpose is to let users upload a PDF, automatically extract and index its contents with FAISS, and answer user questions by invoking a large language model via the Hugging Face Inference API.

##### File structure
- Top level:
- app.py – the single entry point containing UI, PDF handling, FAISS indexing, and API calls
- requirements.txt – Python dependencies (Streamlit, FAISS, Hugging Face SDK, PDF parser)
- secrets.toml – Streamlit‐specific secret store for the Hugging Face token
- .github/workflows/ci.yaml – CI pipeline (install, lint, possibly test)
- No separate “frontend” or “backend” code directories: the app bundles both UI and processing in one Python script.

##### Key architectural components
a. Streamlit UI
- Renders the web interface in the user’s browser.
b. PDF ingestion & text extraction
- Uses a PDF library (PyPDF2/pdfplumber) to parse raw text and tables.
c. Text chunking & vectorization
- Splits the full text into segments (“chunks”).
- Generates embeddings for each chunk (embedded locally or via Hugging Face Embedding API).
d. FAISS vector store
- Stores and indexes chunk embeddings for fast similarity search.
e. Query pipeline
- User question → embed query → FAISS retrieves top-k related chunks → combine with user prompt.
f. Hugging Face Inference API
- Sends prompt+context to a chosen LLM (e.g., Mistral-7B) → receives generated answer.
g. Secrets management & configuration
- Hugging Face API token loaded from Streamlit secrets or environment.
h. CI workflow (optional to show)
- Validates code style and dependencies on each commit.

##### Relationships & data flow
1. User (browser) → Streamlit frontend (app.py)
2. Upload PDF → PDF extraction module → raw text
3. Text → chunker → embedding generator → FAISS index
4. User submits question → question embedding → FAISS similarity search → retrieve context chunks
5. Streamlit orchestrates context + question → Hugging Face Inference API → LLM answer
6. Streamlit displays answer back to user

##### Architectural patterns & design principles
- Single-process, event-driven web UI (Streamlit)
- Modular separation within a single script: ingestion, indexing, retrieval, API integration
- Externalized secret management for API tokens (separation of config vs code)
- Use of a vector database (FAISS) as a retrieval-augmented generation (RAG) pattern

##### Detail
- Every major responsibility as its own component—even if all live in app.py—to make dependencies explicit.
- Directional data flows for PDF ingestion, indexing, query retrieval, and LLM invocation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User (Browser)"]:::external
    StreamlitUI["Streamlit UI\n(Streamlit)"]:::inapp
    PDFParser["PDF Parser & Text Extractor\n(PyPDF2/pdfplumber)"]:::inapp
    Chunker["Text Chunking & Vectorization"]:::inapp
    EmbeddingSvc["Embedding Service\n(Hugging Face Embeddings)"]:::inapp
    FAISS["FAISS Vector Store"]:::inapp
    QueryPipeline["Query Pipeline\n(Embed Query, FAISS Retrieval,\nAssemble Context)"]:::inapp
    HFClient["Hugging Face API Client"]:::inapp
    HFAPI["Hugging Face Inference API"]:::external
    Secrets["Secrets Store\n(secrets.toml)"]:::config
    Requirements["Python Dependencies\n(requirements.txt)"]:::config
    CI["CI Workflow\n(.github/workflows/ci.yaml)"]:::ci

    User --> StreamlitUI
    StreamlitUI --> PDFParser
    PDFParser --> Chunker
    Chunker --> EmbeddingSvc
    EmbeddingSvc --> FAISS
    StreamlitUI --> QueryPipeline
    QueryPipeline --> FAISS
    QueryPipeline --> HFClient
    HFClient --> HFAPI
    HFAPI --> HFClient
    HFClient --> StreamlitUI

    Secrets --> HFClient
    Requirements --> StreamlitUI

    CI

    click StreamlitUI "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click PDFParser "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click Chunker "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click EmbeddingSvc "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click FAISS "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click QueryPipeline "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click HFClient "https://github.com/shubhammandowara/llm_rag/blob/main/app.py"
    click Secrets "https://github.com/shubhammandowara/llm_rag/blob/main/secrets.toml"
    click Requirements "https://github.com/shubhammandowara/llm_rag/blob/main/requirements.txt"
    click CI "https://github.com/shubhammandowara/llm_rag/blob/main/.github/workflows/ci.yaml"

    classDef inapp fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#d4edda,stroke:#333,stroke-width:1px
    classDef config fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef ci fill:#fff3cd,stroke:#333,stroke-width:1px
```
