# ajai-r/comparative-rag-benchmark architecture

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

- Interactive diagram: https://gitdiagram.com/ajai-r/comparative-rag-benchmark
- Repository: https://github.com/ajai-r/comparative-rag-benchmark

## Overview

This repository is a research platform for comparing three RAG strategies, with document management, interactive querying/comparison, and benchmark evaluation. The user-facing path runs from the dashboard through the API and comparison bridge into a selected pipeline, then returns answers and retrieval traces. The pipelines differ in dense, hybrid, and adaptive-agent retrieval stages. README and excerpts support the principal flows; links inside unsampled backend and Pipeline 2 internals are omitted where caller evidence is unavailable.

Main entry points: [`PIPELINE 3/agent.py`](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/agent.py) (Agent Orchestrator), [`PIPELINE 1/main.py`](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/main.py) (Dense Orchestrator), [`backend/pipeline_bridge.py`](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/pipeline_bridge.py) (Pipeline Bridge), [`PIPELINE 2/main.py`](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/main.py) (Hybrid Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web dashboard"]
  node_app["Dashboard App<br/>[App.jsx]"]
  node_chat["Chat View<br/>[ChatView.jsx]"]
  node_compare["Comparison View"]
  node_docs["Document Manager"]
  node_api_client["API Client<br/>[api.js]"]
end

subgraph group_service["API service"]
  node_server["REST API<br/>[server.py]"]
  node_bridge["Pipeline Bridge<br/>[pipeline_bridge.py]"]
  node_processor["Document Ingestion"]
end

subgraph group_dense["Dense RAG"]
  node_p1_main["Dense Orchestrator<br/>[main.py]"]
  node_p1_loader["Document Loader<br/>[document_loader.py]"]
  node_p1_chunk["Chunking<br/>[chunking.py]"]
  node_p1_embed["Embeddings<br/>[embeddings.py]"]
  node_p1_store[("Vector Store<br/>[vector_store.py]")]
  node_p1_retrieval["Dense Retrieval<br/>[retrieval.py]"]
  node_p1_gen["Answer Generation<br/>[generation.py]"]
end

subgraph group_hybrid["Hybrid RAG"]
  node_p2_main["Hybrid Orchestrator<br/>[main.py]"]
  node_bm25["BM25 Index<br/>[bm25_index.py]"]
  node_hybrid_retrieval["Hybrid Retrieval<br/>[retrieval.py]"]
  node_fusion["Rank Fusion<br/>[fusion.py]"]
  node_reranker["Cross-Encoder Reranker<br/>[reranker.py]"]
end

subgraph group_agent["Agentic RAG"]
  node_agent_main["Agent Orchestrator<br/>[agent.py]"]
  node_classifier["Query Classifier<br/>[classifier.py]"]
  node_decomposer["Query Decomposer<br/>[decomposer.py]"]
  node_calculator["Math Tool<br/>[calculator.py]"]
  node_sufficiency["Evidence Checker<br/>[sufficiency.py]"]
end

subgraph group_evaluation["Benchmarking"]
  node_benchmark["Benchmark Runner<br/>[run_benchmark.py]"]
  node_metrics["Evaluation Metrics<br/>[metrics.py]"]
end

node_user(("User"))
node_openrouter["OpenRouter LLM"]

node_user -->|"asks"| node_chat
node_user -->|"compares"| node_compare
node_app -->|"renders"| node_chat
node_app -->|"renders"| node_compare
node_app -->|"renders"| node_docs
node_chat -->|"submits queries"| node_api_client
node_compare -->|"requests comparisons"| node_api_client
node_docs -->|"manages documents"| node_api_client
node_api_client -->|"calls REST API"| node_server
node_server -->|"delegates requests"| node_bridge
node_bridge -->|"uses for ingestion"| node_processor
node_bridge -.->|"dispatches pipeline"| node_p1_main
node_bridge -.->|"dispatches pipeline"| node_p2_main
node_bridge -.->|"dispatches pipeline"| node_agent_main
node_p1_main -->|"loads documents"| node_p1_loader
node_p1_main -->|"creates chunks"| node_p1_chunk
node_p1_main -->|"embeds chunks"| node_p1_embed
node_p1_main -->|"stores vectors"| node_p1_store
node_p1_main -->|"retrieves matches"| node_p1_retrieval
node_p1_main -->|"generates answer"| node_p1_gen
node_p1_gen -->|"requests completion"| node_openrouter
node_p2_main -->|"loads sparse index"| node_bm25
node_p2_main -->|"runs retrieval"| node_hybrid_retrieval
node_hybrid_retrieval -->|"fuses ranks"| node_fusion
node_p2_main -->|"initializes reranker"| node_reranker
node_p2_main -->|"generates answer"| node_p1_gen
node_agent_main -->|"classifies query"| node_classifier
node_agent_main -->|"decomposes queries"| node_decomposer
node_agent_main -->|"uses math tool"| node_calculator
node_agent_main -->|"checks evidence"| node_sufficiency
node_agent_main -->|"retrieves dense evidence"| node_p1_retrieval
node_agent_main -->|"retrieves hybrid evidence"| node_hybrid_retrieval
node_agent_main -->|"generates answer"| node_p1_gen
node_benchmark -->|"computes scores"| node_metrics
node_benchmark -->|"evaluates agent"| node_agent_main

click node_app "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/App.jsx"
click node_chat "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/components/ChatView.jsx"
click node_compare "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/components/ComparisonDashboard.jsx"
click node_docs "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/components/DocumentManager.jsx"
click node_api_client "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/server.py"
click node_bridge "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/pipeline_bridge.py"
click node_processor "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/document_processor.py"
click node_p1_main "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/main.py"
click node_p1_loader "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/document_loader.py"
click node_p1_chunk "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/chunking.py"
click node_p1_embed "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/embeddings.py"
click node_p1_store "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/vector_store.py"
click node_p1_retrieval "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/retrieval.py"
click node_p1_gen "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/generation.py"
click node_p2_main "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/main.py"
click node_bm25 "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/bm25_index.py"
click node_hybrid_retrieval "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/retrieval.py"
click node_fusion "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/fusion.py"
click node_reranker "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/reranker.py"
click node_agent_main "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/agent.py"
click node_classifier "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/classifier.py"
click node_decomposer "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/decomposer.py"
click node_calculator "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/calculator.py"
click node_sufficiency "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/sufficiency.py"
click node_benchmark "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/Evaluation/run_benchmark.py"
click node_metrics "https://github.com/ajai-r/comparative-rag-benchmark/blob/main/Evaluation/metrics.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_app,node_chat,node_compare,node_docs,node_api_client,node_user toneBlue
class node_server,node_bridge,node_processor toneAmber
class node_p1_main,node_p1_loader,node_p1_chunk,node_p1_embed,node_p1_store,node_p1_retrieval,node_p1_gen,node_openrouter toneMint
class node_p2_main,node_bm25,node_hybrid_retrieval,node_fusion,node_reranker toneRose
class node_agent_main,node_classifier,node_decomposer,node_calculator,node_sufficiency toneIndigo
class node_benchmark,node_metrics toneTeal
```

## Components

### Web dashboard

- [Dashboard App](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat View](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/components/ChatView.jsx): `frontend/src/components/ChatView.jsx`
- [Comparison View](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/components/ComparisonDashboard.jsx): `frontend/src/components/ComparisonDashboard.jsx`
- [Document Manager](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/components/DocumentManager.jsx): `frontend/src/components/DocumentManager.jsx`
- [API Client](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API service

- [REST API](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/server.py): `backend/server.py`
- [Pipeline Bridge](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/pipeline_bridge.py): `backend/pipeline_bridge.py`
- [Document Ingestion](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/backend/document_processor.py): `backend/document_processor.py`

### Dense RAG

- [Dense Orchestrator](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/main.py): `PIPELINE 1/main.py`
- [Document Loader](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/document_loader.py): `PIPELINE 1/document_loader.py`
- [Chunking](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/chunking.py): `PIPELINE 1/chunking.py`
- [Embeddings](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/embeddings.py): `PIPELINE 1/embeddings.py`
- [Vector Store](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/vector_store.py): `PIPELINE 1/vector_store.py`
- [Dense Retrieval](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/retrieval.py): `PIPELINE 1/retrieval.py`
- [Answer Generation](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%201/generation.py): `PIPELINE 1/generation.py`

### Hybrid RAG

- [Hybrid Orchestrator](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/main.py): `PIPELINE 2/main.py`
- [BM25 Index](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/bm25_index.py): `PIPELINE 2/bm25_index.py`
- [Hybrid Retrieval](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/retrieval.py): `PIPELINE 2/retrieval.py`
- [Rank Fusion](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/fusion.py): `PIPELINE 2/fusion.py`
- [Cross-Encoder Reranker](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%202/reranker.py): `PIPELINE 2/reranker.py`

### Agentic RAG

- [Agent Orchestrator](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/agent.py): `PIPELINE 3/agent.py`
- [Query Classifier](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/classifier.py): `PIPELINE 3/classifier.py`
- [Query Decomposer](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/decomposer.py): `PIPELINE 3/decomposer.py`
- [Math Tool](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/calculator.py): `PIPELINE 3/calculator.py`
- [Evidence Checker](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/PIPELINE%203/sufficiency.py): `PIPELINE 3/sufficiency.py`

### Benchmarking

- [Benchmark Runner](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/Evaluation/run_benchmark.py): `Evaluation/run_benchmark.py`
- [Evaluation Metrics](https://github.com/ajai-r/comparative-rag-benchmark/blob/main/Evaluation/metrics.py): `Evaluation/metrics.py`

### Other components

- **User**
- **OpenRouter LLM**

## Connections

- User → Chat View: asks (evidence: `README.md`)
- User → Comparison View: compares (evidence: `README.md`)
- Dashboard App → Chat View: renders (evidence: `frontend/src/App.jsx`)
- Dashboard App → Comparison View: renders (evidence: `frontend/src/App.jsx`)
- Dashboard App → Document Manager: renders (evidence: `frontend/src/App.jsx`)
- Chat View → API Client: submits queries (evidence: `frontend/src/components/ChatView.jsx`)
- Comparison View → API Client: requests comparisons (evidence: `frontend/src/components/ComparisonDashboard.jsx`)
- Document Manager → API Client: manages documents (evidence: `frontend/src/components/DocumentManager.jsx`)
- API Client → REST API: calls REST API (evidence: `frontend/src/services/api.js`)
- REST API → Pipeline Bridge: delegates requests (evidence: `backend/server.py`)
- Pipeline Bridge → Document Ingestion: uses for ingestion (evidence: `backend/pipeline_bridge.py`)
- Pipeline Bridge → Dense Orchestrator: dispatches pipeline
- Pipeline Bridge → Hybrid Orchestrator: dispatches pipeline
- Pipeline Bridge → Agent Orchestrator: dispatches pipeline
- Dense Orchestrator → Document Loader: loads documents (evidence: `PIPELINE 1/main.py`)
- Dense Orchestrator → Chunking: creates chunks (evidence: `PIPELINE 1/main.py`)
- Dense Orchestrator → Embeddings: embeds chunks (evidence: `PIPELINE 1/main.py`)
- Dense Orchestrator → Vector Store: stores vectors (evidence: `PIPELINE 1/main.py`)
- Dense Orchestrator → Dense Retrieval: retrieves matches (evidence: `PIPELINE 1/main.py`)
- Dense Orchestrator → Answer Generation: generates answer (evidence: `PIPELINE 1/main.py`)
- Answer Generation → OpenRouter LLM: requests completion (evidence: `PIPELINE 1/generation.py`)
- Hybrid Orchestrator → BM25 Index: loads sparse index (evidence: `PIPELINE 2/main.py`)
- Hybrid Orchestrator → Hybrid Retrieval: runs retrieval (evidence: `PIPELINE 2/main.py`)
- Hybrid Retrieval → Rank Fusion: fuses ranks (evidence: `PIPELINE 2/retrieval.py`)
- Hybrid Orchestrator → Cross-Encoder Reranker: initializes reranker (evidence: `PIPELINE 2/main.py`)
- Hybrid Orchestrator → Answer Generation: generates answer (evidence: `PIPELINE 2/main.py`)
- Agent Orchestrator → Query Classifier: classifies query (evidence: `PIPELINE 3/agent.py`)
- Agent Orchestrator → Query Decomposer: decomposes queries (evidence: `PIPELINE 3/agent.py`)
- Agent Orchestrator → Math Tool: uses math tool (evidence: `PIPELINE 3/agent.py`)
- Agent Orchestrator → Evidence Checker: checks evidence (evidence: `PIPELINE 3/agent.py`)
- Agent Orchestrator → Dense Retrieval: retrieves dense evidence
- Agent Orchestrator → Hybrid Retrieval: retrieves hybrid evidence
- Agent Orchestrator → Answer Generation: generates answer (evidence: `PIPELINE 3/main.py`)
- Benchmark Runner → Evaluation Metrics: computes scores (evidence: `Evaluation/run_benchmark.py`)
- Benchmark Runner → Agent Orchestrator: evaluates agent (evidence: `Evaluation/run_benchmark.py`)
