# sujithvarma-ai/advanced-rag-knowledge-base architecture

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

- Interactive diagram: https://gitdiagram.com/sujithvarma-ai/advanced-rag-knowledge-base
- Repository: https://github.com/sujithvarma-ai/advanced-rag-knowledge-base

## Overview

This repository is an enterprise-knowledge RAG assistant. Markdown collections are loaded, chunked, embedded, and stored for retrieval; the chat interface sends user questions through retrieval and LLM answer generation, with retrieved context displayed alongside the answer. A separate advanced RAG module demonstrates query rewriting and reranking, but its integration with the primary answer path is not established by the sampled code. Evaluation covers retrieval metrics and LLM-judged answer quality. The graph reflects the sampled source and README; evaluation test-loading details and the advanced module’s runtime wiring are only partly evidenced.

Main entry points: [`answer.py`](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py) (Answer orchestration), [`app.py`](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/app.py) (Chat interface), [`eval.py`](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/eval.py) (RAG evaluation), [`ragadvanced.py`](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py) (Advanced RAG demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Knowledge ingestion"]
  node_knowledge["Knowledge documents"]
  node_load["Load Markdown<br/>[ingest.py]"]
  node_chunk["Chunk documents<br/>[ingest.py]"]
  node_embed_store["Embed and index<br/>[ingest.py]"]
  node_vector_db[("Vector database")]
end

subgraph group_answering["Question answering"]
  node_chat["Chat interface<br/>[app.py]"]
  node_answer["Answer orchestration<br/>[answer.py]"]
  node_retrieval["Semantic retrieval<br/>[answer.py]"]
  node_llm{{"Gemini model"}}
  node_context["Retrieved context<br/>[answer.py]"]
end

subgraph group_advanced["Advanced RAG"]
  node_advanced_rag["Advanced RAG demo<br/>[ragadvanced.py]"]
  node_rewrite["Query rewriting<br/>[ragadvanced.py]"]
  node_rerank["Result reranking<br/>[ragadvanced.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_test_data["Evaluation dataset<br/>[tests.jsonl]"]
  node_test_loader["Test loading<br/>[test.py]"]
  node_metrics["RAG evaluation<br/>[eval.py]"]
  node_dashboard["Evaluation dashboard<br/>[evaluator.py]"]
end

node_user(("User"))

node_knowledge -->|"loads"| node_load
node_load -->|"splits"| node_chunk
node_chunk -->|"embeds chunks"| node_embed_store
node_embed_store -->|"stores vectors"| node_vector_db
node_user -->|"asks"| node_chat
node_chat -->|"calls"| node_answer
node_answer -->|"requests context"| node_retrieval
node_retrieval -->|"searches"| node_vector_db
node_retrieval -->|"returns documents"| node_context
node_answer -->|"generates answer"| node_llm
node_context -->|"provides grounding"| node_answer
node_answer -->|"returns answer"| node_chat
node_advanced_rag -->|"defines"| node_rewrite
node_advanced_rag -->|"defines"| node_rerank
node_test_data -.->|"test cases"| node_test_loader
node_test_loader -->|"loads tests"| node_metrics
node_metrics -->|"evaluates answers"| node_answer
node_dashboard -->|"runs evaluations"| node_metrics

click node_knowledge "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/tree/main/knowledge-base"
click node_load "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ingest.py"
click node_chunk "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ingest.py"
click node_embed_store "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ingest.py"
click node_chat "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/app.py"
click node_answer "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py"
click node_retrieval "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py"
click node_context "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py"
click node_advanced_rag "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py"
click node_rewrite "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py"
click node_rerank "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py"
click node_test_data "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/tests.jsonl"
click node_test_loader "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/test.py"
click node_metrics "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/eval.py"
click node_dashboard "https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/evaluator.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_knowledge,node_load,node_chunk,node_embed_store,node_vector_db,node_user toneBlue
class node_chat,node_answer,node_retrieval,node_llm,node_context toneAmber
class node_advanced_rag,node_rewrite,node_rerank toneMint
class node_test_data,node_test_loader,node_metrics,node_dashboard toneRose
```

## Components

### Knowledge ingestion

- [Knowledge documents](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/tree/main/knowledge-base): `knowledge-base`
- [Load Markdown](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ingest.py): `ingest.py`
- [Chunk documents](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ingest.py): `ingest.py`
- [Embed and index](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ingest.py): `ingest.py`
- **Vector database**

### Question answering

- [Chat interface](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/app.py): `app.py`
- [Answer orchestration](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py): `answer.py`
- [Semantic retrieval](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py): `answer.py`
- **Gemini model**
- [Retrieved context](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/answer.py): `answer.py`

### Advanced RAG

- [Advanced RAG demo](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py): `ragadvanced.py`
- [Query rewriting](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py): `ragadvanced.py`
- [Result reranking](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/ragadvanced.py): `ragadvanced.py`

### Evaluation

- [Evaluation dataset](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/tests.jsonl): `tests.jsonl`
- [Test loading](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/test.py): `test.py`
- [RAG evaluation](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/eval.py): `eval.py`
- [Evaluation dashboard](https://github.com/sujithvarma-ai/advanced-rag-knowledge-base/blob/main/evaluator.py): `evaluator.py`

### Other components

- **User**

## Connections

- Knowledge documents → Load Markdown: loads (evidence: `README.md`)
- Load Markdown → Chunk documents: splits (evidence: `ingest.py`)
- Chunk documents → Embed and index: embeds chunks (evidence: `ingest.py`)
- Embed and index → Vector database: stores vectors (evidence: `ingest.py`)
- User → Chat interface: asks (evidence: `app.py`)
- Chat interface → Answer orchestration: calls (evidence: `app.py`)
- Answer orchestration → Semantic retrieval: requests context (evidence: `answer.py`)
- Semantic retrieval → Vector database: searches (evidence: `answer.py`)
- Semantic retrieval → Retrieved context: returns documents (evidence: `answer.py`)
- Answer orchestration → Gemini model: generates answer (evidence: `answer.py`)
- Retrieved context → Answer orchestration: provides grounding (evidence: `answer.py`)
- Answer orchestration → Chat interface: returns answer (evidence: `app.py`)
- Advanced RAG demo → Query rewriting: defines (evidence: `ragadvanced.py`)
- Advanced RAG demo → Result reranking: defines (evidence: `ragadvanced.py`)
- Evaluation dataset → Test loading: test cases (evidence: `README.md`)
- Test loading → RAG evaluation: loads tests (evidence: `eval.py`)
- RAG evaluation → Answer orchestration: evaluates answers (evidence: `eval.py`)
- Evaluation dashboard → RAG evaluation: runs evaluations (evidence: `evaluator.py`)
