# keshx-3/web-based-rag-assistant architecture

> Architecture diagram of the GitHub repository keshx-3/web-based-rag-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keshx-3/web-based-rag-assistant
- Repository: https://github.com/keshx-3/web-based-rag-assistant

## Overview

##### What this project is (type + purpose)
This is a **single-service Python application** with a **Streamlit web UI** that runs a **Retrieval-Augmented Generation (RAG)** workflow. It has two explicit “logic loops”:

- **Knowledge Ingestion (ETL)**: URL(s) → fetch web content → clean/split → embed → store vectors in **local ChromaDB**.
- **Contextual Inference (RAG)**: user question → embed query → similarity search in Chroma → build grounded prompt with top‑k chunks → call **Groq LLaMA 3.1** → answer + citations (and LaTeX rendering).

It’s not a multi-service distributed system; it’s a **monolithic app** that depends on **external APIs** (Groq) and **local persistence** (Chroma vectorstore on disk).

##### What the file tree implies architecturally
From the tree:

- `main.py` = **presentation + interaction layer**
Streamlit UI, chat memory, LaTeX rendering, user inputs (URLs, questions), displays citations.
- `rag.py` = **domain/service layer**
ETL (WebBaseLoader, chunking) + embeddings + vectorstore ops + retrieval + prompt assembly (likely) + LLM call orchestration (via LangChain).
- `requirements.txt` = dependency boundary (Streamlit, LangChain, Chroma, HF embeddings, Groq SDK, etc.)
- `.env.example` + `.env` (runtime) = **secret/config boundary** (`GROQ_API_KEY`)

README also mentions a `resources/vectorstore/` persistent path (not shown in tree but should exist at runtime). Treat it as **local disk storage** owned by the app process.

Goal: show what runs, what it talks to, and what data stores exist.

**Nodes to include**
- **User (Browser)**
- **Streamlit App (Python process)**
- **External Web Sources** (any HTTP/HTTPS site)
- **Groq API (LLaMA 3.1 8B Instant)** (external inference)
- **Local Vector Store (ChromaDB on disk)** (persistent)
- **Embedding Model runtime**: HuggingFace `gte-base-en-v1.5`
(likely local inference; if it downloads model weights, note “HF model files cache” as optional local storage)

- Browser → Streamlit: “User inputs (URLs, questions)”
- Streamlit → Web Sources: “Fetch HTML/text”
- Streamlit → Embeddings: “Compute embeddings”
- Streamlit ↔ ChromaDB: “Upsert chunks / Similarity search (cosine)”
- Streamlit → Groq: “RAG prompt + context”
- Groq → Streamlit: “Grounded answer”
- Streamlit → Browser: “Answer + citations + rendered LaTeX”

**Labels that matter**
- “k=8 top chunks”
- “chunk size ~1500 chars w/ overlap”
- “768-d embeddings”
- “persistent vectorstore path: resources/vectorstore/ (local)”

Goal: show the two loops as time-ordered interactions.

**Sequence 1: Ingestion loop (ETL)**
##### Return ingestion status to UI

**Sequence 2: Inference loop (RAG)**
##### UI renders response + `st.latex()` where applicable + citations

Goal: map **files → responsibilities** and show internal boundaries.

- `main.py`
- UI components (URL input, query input, chat display)
- Session state / chat memory
- LaTeX detection & rendering pipeline (`st.latex`)
- Calls into `rag.py`
- `rag.py`
- Loader: WebBaseLoader
- Cleaner: regex artifact stripper
- Splitter: RecursiveCharacterTextSplitter
- Embeddings: HF `gte-base-en-v1.5`
- Vectorstore adapter: Chroma
- Retriever: top‑k (k=8), cosine similarity
- Prompt builder: “strict grounding”
- LLM client: Groq (LLaMA 3.1)

**Cross-cutting**
- Config: `.env` → `GROQ_API_KEY`
- Persistence: `resources/vectorstore/` (Chroma collection)

- Custom: orchestration glue, cleaning, prompt constraints, UI/latex, memory
- Library-managed: chunker, embeddings wrapper, Chroma client, Groq client (depending on implementation)

##### Relationships + interactions to highlight (the “truth” of the architecture)

- It’s a **single runtime** (Streamlit) doing both ingestion and inference.
- It has a **local durable store** (Chroma on disk) that is reused across sessions/runs.
- It has **two major external dependencies**:
1) arbitrary websites for ingestion
2) Groq for generation
- Embeddings are a distinct compute stage (often local, CPU/GPU dependent) and are **used twice** (docs and query).
- Citation support depends on **document metadata** (URL) flowing from ingestion → vectorstore → retrieval → UI.

##### Practical “don’t overthink it” checklist (but be very detailed)

- Where does content come from? (URLs → loader)
- Where does it persist? (Chroma on disk path)
- What transforms happen before storage? (clean → chunk → embed)
- What transforms happen before generation? (embed query → retrieve → prompt)
- What enforces correctness? (grounding prompt constraints)
- What’s external and failure-prone? (web fetch + Groq API)
- Where are secrets stored? (`.env` / GROQ_API_KEY)
- What is the runtime entrypoint? (`streamlit run main.py`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram A — Context / Container (C4-style)
    %% =========================
    subgraph A["Diagram A — Context / Container"]
        direction TB

        User["User (Browser)"]:::external

        App["Streamlit App (Python process)\nUI + RAG Orchestrator"]:::inproc

        Web["External Web Sources\n(HTTP/HTTPS sites)"]:::external
        Groq["Groq API\n(LLaMA 3.1 8B Instant)"]:::external

        Embed["Embedding Runtime\nHuggingFace gte-base-en-v1.5\n(768-d)"]:::compute

        Chroma[("Local Vector Store\nChromaDB (persistent)")]:::storage
        Disk[("Local Filesystem\nresources/vectorstore/")]:::storage
        HFCache[("Optional Local Storage\nHF model cache")]:::storage

        User -->|"User_inputs(URLs,questions)"| App
        App -->|"Fetch_raw_HTML/text"| Web
        App -->|"Compute_embeddings(768-d)"| Embed
        Embed -.->|"Model_weights_download/cache"| HFCache

        App -->|"Upsert_chunks+metadata(url)\n(chunk~1500_chars+overlap)"| Chroma
        App -->|"Similarity_search(cosine)\nTop-k=8_context"| Chroma
        Chroma -.->|"Persist_vectors+metadata"| Disk

        App -->|"RAG_prompt+Top-k_context"| Groq
        Groq -->|"Grounded_answer"| App
        App -->|"Answer+citations+rendered_LaTeX"| User
    end

    %% =========================
    %% Diagram B — Sequence (runtime behavior)
    %% =========================
    subgraph B["Diagram B — Sequence (Runtime Behavior)"]
        direction TB

        subgraph B1["Sequence 1 — Ingestion (ETL loop)"]
            direction TB
            u1["User"]:::external
            ui1["main.py\n(Streamlit UI)"]:::inproc
            rag1["rag.py\n(ingest(urls))"]:::inproc
            web1["WebBaseLoader\n(HTTP GET)"]:::lib
            clean1["Cleaner\n(regex/artifact stripping)"]:::inproc
            split1["RecursiveCharacterTextSplitter\n(1500 + overlap)"]:::lib
            emb1["Embeddings\n(gte-base-en-v1.5, 768-d)"]:::compute
            chroma1[("ChromaDB\nupsert docs+metadata(url)")]:::storage

            u1 -->|"Enter_URLs"| ui1
            ui1 -->|"Call_ingest(urls)"| rag1
            rag1 -->|"Load_pages"| web1
            web1 -->|"raw_HTML/text"| rag1
            rag1 -->|"Clean_text"| clean1
            clean1 -->|"clean_text"| rag1
            rag1 -->|"Split_into_chunks"| split1
            split1 -->|"chunks"| rag1
            rag1 -->|"Embed_chunks(768-d)"| emb1
            emb1 -->|"vectors"| rag1
            rag1 -->|"Upsert(chunks+vectors+metadata:url)"| chroma1
            rag1 -->|"Ingestion_status"| ui1
            ui1 -->|"Display_status"| u1
        end

        subgraph B2["Sequence 2 — Inference (RAG loop)"]
            direction TB
            u2["User"]:::external
            ui2["main.py\n(Streamlit UI)"]:::inproc
            mem2["Streamlit Session State\n(chat memory)"]:::inproc
            rag2["rag.py\n(answer(query,history))"]:::inproc
            emb2["Embed_query\n(gte-base-en-v1.5, 768-d)"]:::compute
            chroma2[("ChromaDB\nsimilarity_search(cosine)")]:::storage
            prompt2["Prompt Builder\n(strict grounding: only context)\nCollect citations from metadata(url)"]:::inproc
            groq2["Groq API\nLLaMA 3.1"]:::external
            latex2["Post-process + LaTeX hints\n(st.latex where applicable)"]:::inproc

            u2 -->|"Ask_question"| ui2
            ui2 -->|"Read/Update_history"| mem2
            ui2 -->|"Call_answer(query,history)"| rag2
            rag2 -->|"Embed_query"| emb2
            emb2 -->|"query_vector"| rag2
            rag2 -->|"Similarity_search_top-k=8"| chroma2
            chroma2 -->|"Top-k_chunks+metadata(url)"| rag2
            rag2 -->|"Build_prompt+context"| prompt2
            prompt2 -->|"prompt+context"| groq2
            groq2 -->|"answer_text"| rag2
            rag2 -->|"Post_process_for_LaTeX+citations"| latex2
            latex2 -->|"Render_answer+citations"| ui2
            ui2 -->|"Display_response"| u2
        end
    end

    %% =========================
    %% Diagram C — Component diagram (code-level mapping)
    %% =========================
    subgraph C["Diagram C — Component Diagram (Code-level Mapping)"]
        direction TB

        subgraph C0["Single Runtime: Streamlit App Process"]
            direction TB

            subgraph C1["Presentation + Interaction Layer"]
                direction TB
                main["main.py\n- URL input + Query input\n- Chat UI\n- Session state / memory\n- LaTeX detection & st.latex\n- Calls rag.py"]:::inproc
            end

            subgraph C2["Domain / Service Layer (RAG)"]
                direction TB
                rag["rag.py\n- ETL orchestration\n- Retrieval\n- Prompt grounding\n- LLM call"]:::inproc

                subgraph C2a["Knowledge Ingestion (ETL loop)"]
                    direction TB
                    loader["WebBaseLoader"]:::lib
                    cleaner["Cleaner (regex)"]:::inproc
                    splitter["RecursiveCharacterTextSplitter"]:::lib
                    docEmb["Doc Embeddings\n(gte-base-en-v1.5, 768-d)"]:::compute
                    vsUpsert["Vectorstore Ops\n(Upsert chunks+metadata:url)"]:::lib
                end

                subgraph C2b["Contextual Inference (RAG loop)"]
                    direction TB
                    qEmb["Query Embedding\n(768-d)"]:::compute
                    retr["Retriever\n(cosine similarity, top-k=8)"]:::lib
                    prompt["Prompt Builder\n(strict grounding)"]:::inproc
                    llm["LLM Client\n(Groq SDK → LLaMA 3.1)"]:::lib
                end
            end
        end

        subgraph Cx["Cross-cutting Boundaries"]
            direction TB
            env["Configuration / Secrets\nGROQ_API_KEY"]:::config
            deps["Dependencies Boundary\n(requirements.txt)"]:::config
            docs["Project Documentation\n(usage, persistence notes)"]:::config
            devc["Dev Environment\n.devcontainer"]:::config
            store[("Persistent Vectorstore\nresources/vectorstore/ (local)")]:::storage
        end

        main -->|"calls"| rag

        rag -->|"fetch"| loader
        loader -->|"raw_text"| cleaner
        cleaner -->|"clean_text"| splitter
        splitter -->|"chunks"| docEmb
        docEmb -->|"embeddings"| vsUpsert
        vsUpsert -->|"write_vectors+metadata(url)"| store

        rag -->|"embed_query"| qEmb
        qEmb -->|"query_vector"| retr
        retr -->|"Top-k_chunks+metadata(url)"| prompt
        prompt -->|"prompt+context"| llm

        env -->|"provides_key"| llm
        deps -.->|"pins_versions"| main
        deps -.->|"pins_versions"| rag
        docs -.->|"explains_runtime"| main
        devc -.->|"dev_container_config"| main
    end

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click App "https://github.com/keshx-3/web-based-rag-assistant/blob/main/main.py"
    click main "https://github.com/keshx-3/web-based-rag-assistant/blob/main/main.py"
    click mem2 "https://github.com/keshx-3/web-based-rag-assistant/blob/main/main.py"
    click latex2 "https://github.com/keshx-3/web-based-rag-assistant/blob/main/main.py"

    click rag "https://github.com/keshx-3/web-based-rag-assistant/blob/main/rag.py"
    click rag1 "https://github.com/keshx-3/web-based-rag-assistant/blob/main/rag.py"
    click rag2 "https://github.com/keshx-3/web-based-rag-assistant/blob/main/rag.py"

    click env "https://github.com/keshx-3/web-based-rag-assistant/blob/main/.env.example"
    click deps "https://github.com/keshx-3/web-based-rag-assistant/blob/main/requirements.txt"
    click devc "https://github.com/keshx-3/web-based-rag-assistant/blob/main/.devcontainer/devcontainer.json"
    click docs "https://github.com/keshx-3/web-based-rag-assistant/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef inproc fill:#D6EAF8,stroke:#1B4F72,stroke-width:1.5px,color:#0B2239
    classDef external fill:#FADBD8,stroke:#922B21,stroke-width:1.5px,color:#3B0A06
    classDef storage fill:#D5F5E3,stroke:#1E8449,stroke-width:1.5px,color:#0B2B16
    classDef compute fill:#FCF3CF,stroke:#9A7D0A,stroke-width:1.5px,color:#3A2E00
    classDef lib fill:#E8DAEF,stroke:#6C3483,stroke-width:1.2px,color:#2B1433
    classDef config fill:#EAECEE,stroke:#424949,stroke-width:1.2px,color:#111515
```
