# fighterdhruv8/rag-agent architecture

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

- Interactive diagram: https://gitdiagram.com/fighterdhruv8/rag-agent
- Repository: https://github.com/fighterdhruv8/rag-agent

## Overview

##### Project Type and Purpose
- This is a Retrieval-Augmented Generation (RAG) system combining document retrieval from a corpus with LLM-based response generation.
- It supports two client interfaces: a CLI (main.py) and a Streamlit web app (app.py).
- It has an offline data-ingestion pipeline and an online query pipeline.

##### File Structure
Top-level directories/files:
- data/ – raw documents (.txt, .csv, .json, .pdf)
- src/ – core code modules
– document_loader.py: loads & chunks docs
– embeddings.py: computes embeddings & interacts with ChromaDB
– retrieval.py: retrieves relevant chunks from vector store
– llm.py: wraps calls to Gemini LLM API
– agent.py: orchestrates retrieval + generation logic
– main.py: CLI entry point
– app.py: Streamlit UI entry point
- requirements.txt – Python dependencies
- chatbot_responses.pdf – sample transcripts

##### Extract Architectural Insights from README
- Embeddings stored in ChromaDB vector store.
- Gemini LLM API used for generation (remote).
- Optionally supports a local-hosted version using Ollama (not in this repo).
- Logging feature accessible via CLI or Streamlit sidebar.

A. User Interfaces
– CLI client (main.py)
– Streamlit Web client (app.py)
B. RAG Agent Core (agent.py)
– Coordinates retrieval and LLM calls
C. Document Ingestion Pipeline
– document_loader.py
– embeddings.py → ChromaDB vector store
D. Query Pipeline
– retrieval.py reads from ChromaDB
– llm.py calls Gemini API
E. Data Store
– ChromaDB vector store
– Raw document storage (data/ directory)
F. External Services
– Gemini API (LLM)
– (Optional / local version: Ollama)
G. Logging Subsystem
– Writes to local logs, surfaced in CLI or Streamlit

##### Relationships and Interactions
1. Offline:
User (or automated script) triggers document_loader → embeddings → ChromaDB.
2. Online Query Flow:
User (CLI or Web) → agent.py
agent.py → retrieval.py querying ChromaDB → returns document chunks
agent.py → llm.py calling Gemini API (with or without context) → returns generated text
agent.py → UI (CLI prints, Web displays via Streamlit)
3. Logging:
agent.py & retrieval.py & llm.py log events to local log files → logs feature in UI.

##### Architectural Patterns and Principles
- Modular separation of concerns (Loader, Embedder, Retriever, LLM, UI).
- Single orchestration layer (agent.py) that isolates business logic.
- Pluggable LLM backend (Gemini vs. Ollama).
- Clear data-flow pipeline: Ingestion vs. Query.
- Use of an external vector store (ChromaDB) for retrieval efficiency.

##### Technologies and Frameworks to Annotate
- Python 3.x modules
- LangChain (implied by design)
- ChromaDB vector store
- Google Gemini API
- Streamlit for web UI
- Standard CLI (argparse / click)

[ ] All components clearly labeled (module name + responsibility)
[ ] Grouping of ingestion vs. query workflows
[ ] External dependencies (ChromaDB, Gemini API) shown outside the core boundary
[ ] Logging paths indicated (optional overlay)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        CLI["main.py\n(CLI Client)"]:::ui
        Web["app.py\n(Streamlit Web Client)"]:::ui
    end

    %% Core Services
    subgraph "Core Services"
        Agent["agent.py\n(orchestration layer)"]:::core
    end

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        Loader["document_loader.py\n(chunking)"]:::core
        Embedder["embeddings.py\n(embeddings & ChromaDB)"]:::core
    end

    %% Query Pipeline
    subgraph "Query Pipeline"
        Retriever["retrieval.py\n(ChromaDB lookup)"]:::core
        LLMWrapper["llm.py\n(Gemini API calls)"]:::core
    end

    %% Data Stores
    subgraph "Data Stores"
        RawData["data/\n(raw docs)"]:::data
        VectorStore["ChromaDB\n(vector store)"]:::data
        Transcripts["chatbot_responses.pdf"]:::data
        Requirements["requirements.txt"]:::data
        Readme["README.md"]:::data
        Logs["log files"]:::data
    end

    %% External Services
    subgraph "External Services"
        Gemini["Gemini API"]:::external
        Ollama["Ollama (optional)"]:::external
    end

    %% Offline Ingestion Flow
    RawData -->|"reads documents"| Loader -->|"chunks data"| Embedder -->|"stores embeddings"| VectorStore

    %% Online Query Flow
    CLI -->|"user input"| Agent
    Web -->|"user input"| Agent
    Agent -->|"retrieve chunks() "| Retriever -->|"query embeddings"| VectorStore
    Agent -->|"generate response() "| LLMWrapper -->|"API call"| Gemini
    Agent -->|"return response"| CLI
    Agent -->|"return response"| Web

    %% Logging
    Agent -->|"logs events"| Logs
    Retriever -->|"logs events"| Logs
    LLMWrapper -->|"logs events"| Logs

    %% Optional LLM backend
    LLMWrapper -.->|"alternative backend"| Ollama

    %% Click Events
    click CLI "https://github.com/fighterdhruv8/rag-agent/blob/main/src/main.py"
    click Web "https://github.com/fighterdhruv8/rag-agent/blob/main/src/app.py"
    click Agent "https://github.com/fighterdhruv8/rag-agent/blob/main/src/agent.py"
    click Loader "https://github.com/fighterdhruv8/rag-agent/blob/main/src/document_loader.py"
    click Embedder "https://github.com/fighterdhruv8/rag-agent/blob/main/src/embeddings.py"
    click Retriever "https://github.com/fighterdhruv8/rag-agent/blob/main/src/retrieval.py"
    click LLMWrapper "https://github.com/fighterdhruv8/rag-agent/blob/main/src/llm.py"
    click RawData "https://github.com/fighterdhruv8/rag-agent/tree/main/data/"
    click Transcripts "https://github.com/fighterdhruv8/rag-agent/blob/main/chatbot_responses.pdf"
    click Requirements "https://github.com/fighterdhruv8/rag-agent/blob/main/requirements.txt"
    click Readme "https://github.com/fighterdhruv8/rag-agent/blob/main/README.md"

    %% Styling
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
