# kuldeep27396/agentic-rag architecture

> Architecture diagram of the GitHub repository kuldeep27396/agentic-rag, 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/kuldeep27396/agentic-rag
- Repository: https://github.com/kuldeep27396/agentic-rag

## Overview

##### Project type and purpose
- This is an educational, full-stack demo application showcasing a Retrieval-Augmented Generation (RAG) system that evolves from Traditional RAG to Agentic RAG.
- The core is a Streamlit-based UI that interacts with a modular Python back-end implementing routing, retrieval, and generation.

##### File structure
- Top-level scripts:
- launch_demo.py, run_enhanced_ui.py – orchestration/entry points
- agentic_rag_demo.py, enhanced_streamlit_app.py – Streamlit apps (demo vs full-featured)
- agentic_rag_complete_demo.ipynb – Jupyter tutorial
- Configuration:
- requirements.txt, requirements_ui.txt – dependencies
- .streamlit/secrets.toml, .env.example – API keys and secrets
- Documents folder: sample markdown files for local retrieval.

##### README insights
- The README describes:
- Three routing modes (LOCAL, WEB, HYBRID)
- Intelligent Router and Quality Assessor modules
- Vector DB (FAISS), Embeddings (HuggingFace), LLM (Groq), Web Search (Serper.dev)

##### Main components & relationships
a. User Interface (UI)
- Streamlit app that captures user queries and renders results/visualizations
b. Intelligence Layer
- Intelligent Router: decides LOCAL vs WEB vs HYBRID
- Quality Assessor (QA): evaluates and filters retrieved context
c. Retrieval Layer
- LOCAL: vector similarity search on FAISS over sample documents
- WEB: real-time Serper.dev API calls for web results
- HYBRID: merges local & web contexts
d. Data Layer
- Documents (MD files) + persisted FAISS index
e. AI Layer
- Embeddings service (HuggingFace Embeddings)
- LLM (Groq via LangChain) for routing decisions and final answer generation

Interaction flow:
User → UI → Router → {Local Retrieval ↔ Vector DB ↔ Documents; Web Search → QA} → QA → LLM → UI

##### Architectural patterns & design principles
- Layered architecture: clear separation of UI, intelligence, retrieval, data, and AI services
- Modular pipeline: each stage (routing, retrieval, quality assessment, generation) is decoupled

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        DemoApp["Streamlit UI: agentic_rag_demo.py"]:::ui
        EnhancedApp["Streamlit UI: enhanced_streamlit_app.py"]:::ui
        LaunchDemo["Launcher: launch_demo.py"]:::ui
        RunUI["Runner: run_enhanced_ui.py"]:::ui
    end

    subgraph "Intelligence Layer"
        Router["Intelligent Router"]:::intelligence
        QA["Quality Assessor"]:::intelligence
    end

    subgraph "Retrieval Layer"
        Local["Local Retrieval (FAISS)"]:::retrieval
        Web["Web Search (Serper.dev)"]:::retrieval
        Hybrid["Hybrid Retrieval"]:::retrieval
        Serper["Serper.dev API"]:::external
    end

    subgraph "Data Layer"
        Docs["Documents (MD Files)"]:::data
        Index["FAISS Index"]:::data
    end

    subgraph "AI Layer"
        Embeddings["Embeddings (HuggingFace)"]:::ai
        LLM["LLM (Groq via LangChain)"]:::ai
        GroqAPI["Groq API"]:::external
    end

    subgraph "Configuration"
        Req["requirements.txt"]:::config
        ReqUI["requirements_ui.txt"]:::config
        Secrets[".streamlit/secrets.toml"]:::config
        Env[".env.example"]:::config
        Notebook["Tutorial Notebook: agentic_rag_complete_demo.ipynb"]:::config
    end

    %% Data Flow
    DemoApp -->|query| Router
    EnhancedApp -->|query| Router
    LaunchDemo -->|start| DemoApp
    RunUI -->|start| EnhancedApp

    Router -->|route LOCAL| Local
    Router -->|route WEB| Web
    Router -->|route HYBRID| Hybrid

    Local -->|uses index| Index
    Index -->|reads| Docs
    Web -->|API call| Serper

    Local -->|results| QA
    Web -->|results| QA
    Hybrid -->|merged results| QA

    QA -->|context| LLM
    Embeddings -->|embeddings| Local
    Embeddings -->|embeddings| LLM
    LLM -->|response| DemoApp
    LLM -->|response| EnhancedApp
    LLM -->|calls| GroqAPI

    %% Configuration dependencies
    Secrets -.->|Serper API key| Web
    Env -.->|env vars| Web
    Req -.->|deps| DemoApp
    ReqUI -.->|deps| EnhancedApp

    %% Click Events
    click DemoApp "https://github.com/kuldeep27396/agentic-rag/blob/main/agentic_rag_demo.py"
    click EnhancedApp "https://github.com/kuldeep27396/agentic-rag/blob/main/enhanced_streamlit_app.py"
    click LaunchDemo "https://github.com/kuldeep27396/agentic-rag/blob/main/launch_demo.py"
    click RunUI "https://github.com/kuldeep27396/agentic-rag/blob/main/run_enhanced_ui.py"
    click Docs "https://github.com/kuldeep27396/agentic-rag/tree/main/documents/"
    click Req "https://github.com/kuldeep27396/agentic-rag/blob/main/requirements.txt"
    click ReqUI "https://github.com/kuldeep27396/agentic-rag/blob/main/requirements_ui.txt"
    click Secrets "https://github.com/kuldeep27396/agentic-rag/blob/main/.streamlit/secrets.toml"
    click Env "https://github.com/kuldeep27396/agentic-rag/blob/main/.env.example"
    click Notebook "https://github.com/kuldeep27396/agentic-rag/blob/main/agentic_rag_complete_demo.ipynb"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef intelligence fill:#d4edda,stroke:#155724,color:#155724
    classDef retrieval fill:#fff3cd,stroke:#856404,color:#856404
    classDef data fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef ai fill:#e5ccff,stroke:#4b0082,color:#4b0082
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
