# spanionsharma/rag architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Python-based, Retrieval-Augmented Generation (RAG) chatbot tool.
- Purpose: Ingest user-provided documents into a vector store (Pinecone), retrieve relevant context at query time, and dispatch prompts to an LLM (ChatOpenAI or Gemini) to generate answers.

a. User Interface (CLI or script runner)
b. Ingestion Module (ingestion.py)
c. Retrieval Module (retrieval.py)
d. Chat Orchestration Module (chatbot_rag.py)
e. Local Documents Folder (“documents/”)
f. Vector Database Service (Pinecone)
g. LLM API Service (ChatOpenAI or Gemini)
h. Configuration Store (API keys, environment variables, requirements.txt)

##### Data Flows & Interactions
- Ingestion Flow:
- User places files in documents/ → ingestion.py reads docs → splits and embeds text → sends embeddings to Pinecone

- Query Flow:
- User issues query via chatbot_rag.py → chatbot_rag invokes retrieval.py → retrieval.py queries Pinecone → Pinecone returns top-k relevant chunks → retrieval.py returns context → chatbot_rag.py formats prompt and calls LLM API → LLM returns generated response → chatbot_rag.py prints to user

- Config/Environment:

##### Architectural Patterns & Design Principles
- Pipeline Pattern: clear separation of ingest → store → retrieve → generate
- Single Responsibility: each script handles one phase (ingestion, retrieval, orchestration)

##### Essential Elements
- Clear labels for all modules and services

[ User (CLI) ]
|
| “/start chat”
↓
[ Chat Orchestration Module ]
|                         ↘── Config (API_KEYS)
| “get_relevant_context”   ───┐
↓                             ↓
[ Retrieval Module ] ──vector_search──▶ [ Pinecone Vector DB ]
|
“return top-k chunks”
↓
Chat Orchestration Module
|
“format prompt + context”
↓
[ LLM API Service ]
|
“generated answer”
↓
Chat Orchestration Module → prints to User

With a parallel branch for:
[ Documents Folder ] ──read & embed──▶ [ Ingestion Module ] ──upload──▶ [ Pinecone Vector DB ]

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "RAG Chatbot System"
        docs[/"Documents Folder"/]:::datastore
        ingest["Ingestion Module"]:::internal
        pinecone[(Pinecone Vector DB)]:::external
        user["User (CLI)"]:::internal
        orchestrator["Chat Orchestration Module"]:::internal
        retrieval["Retrieval Module"]:::internal
        llm[(LLM API Service)]:::external
        config[/Config: API Keys/env/requirements.txt/]:::config
    end

    docs -->|read & embed| ingest
    ingest -->|upload embeddings| pinecone

    user -->|"/start chat"| orchestrator
    orchestrator -->|"get_relevant_context"| retrieval
    retrieval -->|vector_search| pinecone
    pinecone -->|return top-k chunks| retrieval
    retrieval -->|return context| orchestrator
    orchestrator -->|"format prompt + context"| llm
    llm -->|generated answer| orchestrator
    orchestrator -->|print answer| user

    config -.-> orchestrator
    config -.-> ingest
    config -.-> retrieval

    click user "https://github.com/spanionsharma/rag/blob/main/chatbot_rag.py"
    click orchestrator "https://github.com/spanionsharma/rag/blob/main/chatbot_rag.py"
    click ingest "https://github.com/spanionsharma/rag/blob/main/ingestion.py"
    click retrieval "https://github.com/spanionsharma/rag/blob/main/retrieval.py"
    click config "https://github.com/spanionsharma/rag/blob/main/requirements.txt"

    classDef internal fill:#9f6,stroke:#333,stroke-width:1px;
    classDef external fill:#6cf,stroke:#333,stroke-width:1px;
    classDef datastore fill:#fc6,stroke:#333,stroke-width:1px;
    classDef config fill:#ccc,stroke:#333,stroke-width:1px;
```
