# vivek5143/rag-chatbot architecture

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

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

## Overview

This is a document-grounded RAG chatbot: operators index the canonical eBook, then users submit questions through the chat API. The runtime retrieves candidate passages, grades whether they are sufficient, generates only from approved evidence, and independently validates grounding; insufficient or ungrounded answers are refused. The README documents the major workflow stages, while sampled source supports the API, orchestration, and adapter relationships shown here. Some implementation details, especially unsampled runtime wiring, are represented only where the README establishes them.

Main entry points: [`src/graph.py`](https://github.com/vivek5143/rag-chatbot/blob/main/src/graph.py) (RAG Workflow), [`src/indexing.py`](https://github.com/vivek5143/rag-chatbot/blob/main/src/indexing.py) (Chunk Indexing), [`src/api.py`](https://github.com/vivek5143/rag-chatbot/blob/main/src/api.py) (Chat API), [`src/retrieval.py`](https://github.com/vivek5143/rag-chatbot/blob/main/src/retrieval.py) (Evidence Retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Chat API"]
  node_chat_api["Chat API<br/>[api.py]"]
end

subgraph group_runtime["Answer Workflow"]
  node_workflow["RAG Workflow<br/>[graph.py]"]
  node_retrieval["Evidence Retrieval<br/>[retrieval.py]"]
  node_grading["Evidence Grader<br/>[grading.py]"]
  node_generation["Answer Generation<br/>[generation.py]"]
  node_validation["Grounding Validator<br/>[validation.py]"]
end

subgraph group_indexing["Knowledge Indexing"]
  node_pdf["Canonical eBook"]
  node_ingestion["PDF Ingestion<br/>[ingestion.py]"]
  node_indexing_service["Chunk Indexing<br/>[indexing.py]"]
end

subgraph group_providers["Models And Services"]
  node_settings["Runtime Settings<br/>[config.py]"]
  node_domain_models["Domain Contracts<br/>[models.py]"]
  node_embeddings["Embedding Adapter<br/>[embeddings.py]"]
  node_vector_store[("Pinecone Index")]
end

node_user(("Questioner"))
node_openai{{"OpenAI API"}}

node_user -->|"asks"| node_chat_api
node_chat_api -->|"invokes"| node_workflow
node_chat_api -->|"loads settings"| node_settings
node_workflow -->|"retrieves candidates"| node_retrieval
node_workflow -->|"grades evidence"| node_grading
node_workflow -->|"generates answer"| node_generation
node_workflow -->|"validates grounding"| node_validation
node_workflow -->|"uses settings"| node_settings
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"queries"| node_vector_store
node_ingestion -->|"extracts pages"| node_pdf
node_indexing_service -->|"chunks document"| node_ingestion
node_indexing_service -->|"embeds chunks"| node_embeddings
node_indexing_service -->|"upserts vectors"| node_vector_store
node_embeddings -->|"requests vectors"| node_openai
node_generation -->|"requests answer"| node_openai
node_grading -->|"grades evidence"| node_openai
node_validation -->|"checks claims"| node_openai

click node_chat_api "https://github.com/vivek5143/rag-chatbot/blob/main/src/api.py"
click node_settings "https://github.com/vivek5143/rag-chatbot/blob/main/src/config.py"
click node_workflow "https://github.com/vivek5143/rag-chatbot/blob/main/src/graph.py"
click node_retrieval "https://github.com/vivek5143/rag-chatbot/blob/main/src/retrieval.py"
click node_grading "https://github.com/vivek5143/rag-chatbot/blob/main/src/grading.py"
click node_generation "https://github.com/vivek5143/rag-chatbot/blob/main/src/generation.py"
click node_validation "https://github.com/vivek5143/rag-chatbot/blob/main/src/validation.py"
click node_domain_models "https://github.com/vivek5143/rag-chatbot/blob/main/src/models.py"
click node_pdf "https://github.com/vivek5143/rag-chatbot/blob/main/data/Ebook-Agentic-AI.pdf"
click node_ingestion "https://github.com/vivek5143/rag-chatbot/blob/main/src/ingestion.py"
click node_indexing_service "https://github.com/vivek5143/rag-chatbot/blob/main/src/indexing.py"
click node_embeddings "https://github.com/vivek5143/rag-chatbot/blob/main/src/embeddings.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_api toneBlue
class node_workflow,node_retrieval,node_grading,node_generation,node_validation toneAmber
class node_pdf,node_ingestion,node_indexing_service,node_openai toneMint
class node_settings,node_domain_models,node_embeddings,node_vector_store toneRose
class node_user toneIndigo
```

## Components

### Chat API

- [Chat API](https://github.com/vivek5143/rag-chatbot/blob/main/src/api.py): `src/api.py`

### Answer Workflow

- [RAG Workflow](https://github.com/vivek5143/rag-chatbot/blob/main/src/graph.py): `src/graph.py`
- [Evidence Retrieval](https://github.com/vivek5143/rag-chatbot/blob/main/src/retrieval.py): `src/retrieval.py`
- [Evidence Grader](https://github.com/vivek5143/rag-chatbot/blob/main/src/grading.py): `src/grading.py`
- [Answer Generation](https://github.com/vivek5143/rag-chatbot/blob/main/src/generation.py): `src/generation.py`
- [Grounding Validator](https://github.com/vivek5143/rag-chatbot/blob/main/src/validation.py): `src/validation.py`

### Knowledge Indexing

- [Canonical eBook](https://github.com/vivek5143/rag-chatbot/blob/main/data/Ebook-Agentic-AI.pdf): `data/Ebook-Agentic-AI.pdf`
- [PDF Ingestion](https://github.com/vivek5143/rag-chatbot/blob/main/src/ingestion.py): `src/ingestion.py`
- [Chunk Indexing](https://github.com/vivek5143/rag-chatbot/blob/main/src/indexing.py): `src/indexing.py`

### Models And Services

- [Runtime Settings](https://github.com/vivek5143/rag-chatbot/blob/main/src/config.py): `src/config.py`
- [Domain Contracts](https://github.com/vivek5143/rag-chatbot/blob/main/src/models.py): `src/models.py`
- [Embedding Adapter](https://github.com/vivek5143/rag-chatbot/blob/main/src/embeddings.py): `src/embeddings.py`
- **Pinecone Index**

### Other components

- **Questioner**
- **OpenAI API**

## Connections

- Questioner → Chat API: asks (evidence: `README.md`)
- Chat API → RAG Workflow: invokes (evidence: `src/api.py`)
- Chat API → Runtime Settings: loads settings (evidence: `src/api.py`)
- RAG Workflow → Evidence Retrieval: retrieves candidates (evidence: `src/graph.py`)
- RAG Workflow → Evidence Grader: grades evidence (evidence: `src/graph.py`)
- RAG Workflow → Answer Generation: generates answer (evidence: `src/graph.py`)
- RAG Workflow → Grounding Validator: validates grounding (evidence: `src/graph.py`)
- RAG Workflow → Runtime Settings: uses settings (evidence: `src/graph.py`)
- Evidence Retrieval → Embedding Adapter: embeds query (evidence: `src/retrieval.py`)
- Evidence Retrieval → Pinecone Index: queries (evidence: `README.md`)
- PDF Ingestion → Canonical eBook: extracts pages (evidence: `src/ingestion.py`)
- Chunk Indexing → PDF Ingestion: chunks document (evidence: `src/indexing.py`)
- Chunk Indexing → Embedding Adapter: embeds chunks (evidence: `src/indexing.py`)
- Chunk Indexing → Pinecone Index: upserts vectors (evidence: `README.md`)
- Embedding Adapter → OpenAI API: requests vectors (evidence: `src/embeddings.py`)
- Answer Generation → OpenAI API: requests answer (evidence: `src/generation.py`)
- Evidence Grader → OpenAI API: grades evidence (evidence: `README.md`)
- Grounding Validator → OpenAI API: checks claims (evidence: `src/validation.py`)
