# adityajain8595/conversational-rag-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/adityajain8595/conversational-rag-chatbot
- Repository: https://github.com/adityajain8595/conversational-rag-chatbot

## Overview

##### Project type and purpose
- This is a lightweight, single-process full-stack Python application built on Streamlit.
- Purpose: Let users upload a PDF, perform retrieval-augmented QA via embeddings (Hugging Face + FAISS) and generation (Groq LLM), all in a conversational, stateful UI.

##### File structure
- Top‐level:
- chatbotApp.py – the single Streamlit app entry point
- hf_cache/ – local cache for models, tokenizers, vectorstore files and configs
- requirements.txt – Python dependencies
- .devcontainer/ – VS Code devcontainer config
- No separate “frontend”/“backend” folders because UI and logic live together in chatbotApp.py.
- Presence of config files (hf_cache/*.json) and model binaries (onnx, pytorch, openvino) shows offline caching and acceleration options.

##### README for insights
- Stack: Streamlit UI → LangChain orchestrator → HF embeddings → FAISS (vector store) → Groq LLM API
- Features: PDF ingestion, semantic search, conversational memory, secrets via st.secrets

a. Components:
1. Streamlit UI (chatbotApp.py)
2. PDF Loader & Chunker (runs in chatbotApp.py)
3. Embedding Service (HuggingFace “all-MiniLM-L6-v2”)
4. Vector Store (FAISS index, on-disk in hf_cache/)
5. Retrieval & Conversation Memory (LangChain RunnableWithMessageHistory)
6. Generation Service (Groq LLM API – gemma2-9b-it)
7. Local Cache (hf_cache folder for models, tokenizers, onnx files)
8. Secrets Management (Streamlit’s st.secrets)
b. Interactions / data flow:
- User uploads PDF via Streamlit → PDF Loader/Chunker
- Chunks sent to Embedding Service → embeddings returned
- FAISS index updated (stored on disk)
- User asks a question → LangChain Retrieval queries FAISS → retrieves top chunks
- Retrieved context + question sent to Groq LLM API → answer returned
- Conversation history stored in-memory via LangChain → passed back to UI
c. Architectural patterns & principles:
- Modular layers despite being a single script: ingestion → indexing → retrieval → generation → UI
- Retrieval-Augmented Generation (RAG) pattern
- Use of local cache for performance and offline capabilities
- Secrets injection via environment abstraction (st.secrets)
d. Key technologies:
- Streamlit (UI & hosting)
- LangChain (orchestration, memory)
- Hugging Face embeddings
- FAISS (vector search)
- Groq LLM API (generation)
- On-disk cache (hf_cache) for models and indexes

##### Detail
- File-based cache (hf_cache) and its dual role (models + vector index).
- RAG pattern: Retrieval + LLM Generation path.

## Diagram (Mermaid)

```mermaid
flowchart TB
    UI["Streamlit UI"]:::ui
    subgraph "App Server"
        direction TB
        PDF["PDF Loader & Chunker"]:::process
        Emb["Embedding Service"]:::process
        Ret["Retrieval & Conversation Memory"]:::process
        Gen["Generation Service"]:::process
        Sec["Secrets Management"]:::process
    end
    VS["FAISS Index (on-disk)"]:::local
    LC["Local Cache (models & configs)"]:::local
    HF["Hugging Face Embeddings"]:::external
    GROQ["Groq LLM API"]:::external

    UI -->|"Upload PDF"| PDF
    PDF -->|"Chunks"| Emb
    Emb -->|"Embed Chunks"| VS
    VS -->|"Persist Index"| LC
    LC -->|"Load Models/Configs"| Emb
    UI -->|"User Question"| Ret
    Ret -->|"Query Index"| VS
    VS -->|"Top Chunks"| Ret
    Ret -->|"Context + Question"| Gen
    Gen -->|"Answer"| Ret
    Ret -->|"Display Answer"| UI
    Emb -->|"Call Embedding API"| HF
    Gen -->|"Call Generation API"| GROQ
    Sec -->|"Inject Secrets"| Emb
    Sec -->|"Inject Secrets"| Gen

    click UI "https://github.com/adityajain8595/conversational-rag-chatbot/blob/main/chatbotApp.py"
    click PDF "https://github.com/adityajain8595/conversational-rag-chatbot/blob/main/chatbotApp.py"
    click Emb "https://github.com/adityajain8595/conversational-rag-chatbot/blob/main/chatbotApp.py"
    click Ret "https://github.com/adityajain8595/conversational-rag-chatbot/blob/main/chatbotApp.py"
    click Gen "https://github.com/adityajain8595/conversational-rag-chatbot/blob/main/chatbotApp.py"
    click Sec "https://github.com/adityajain8595/conversational-rag-chatbot/blob/main/chatbotApp.py"
    click VS "https://github.com/adityajain8595/conversational-rag-chatbot/tree/main/hf_cache/"
    click LC "https://github.com/adityajain8595/conversational-rag-chatbot/tree/main/hf_cache/"

    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef process fill:#e3f2fd,stroke:#42a5f5,color:#0d47a1;
    classDef local fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
```
