# aryansaraogi/researchrag architecture

> Architecture diagram of the GitHub repository aryansaraogi/researchrag, 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/aryansaraogi/researchrag
- Repository: https://github.com/aryansaraogi/researchrag

## Overview

ResearchRAG lets researchers import papers, search and ask citation-grounded questions, compare papers, explore citation links, and evaluate answer and retrieval quality. Its main workflow is paper ingestion into searchable chunks, followed by query planning, filtered hybrid retrieval, answer generation, and citation mapping to paper pages. The README documents several capabilities whose implementation details were not sampled; those branches are shown at the subsystem level. Edges use excerpts or README statements as evidence; unsampled internals are not inferred.

Main entry points: [`backend/app/ingestion/pipeline.py`](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/pipeline.py) (Ingestion pipeline), [`frontend/app/layout.tsx`](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/layout.tsx) (Research UI), [`backend/app/retrieval/hybrid.py`](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/hybrid.py) (Hybrid retrieval), [`backend/app/generation/rag.py`](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/rag.py) (Query planning and RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Paper ingestion"]
  node_paperapi["Paper API<br/>[papers.py]"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_arxiv["arXiv client<br/>[arxiv_client.py]"]
  node_parser["PDF parser<br/>[pdf_parser.py]"]
  node_chunker["Section chunker<br/>[chunker.py]"]
  node_references["Reference extraction<br/>[references.py]"]
  node_summaries["Paper summaries<br/>[summaries.py]"]
  node_metadata["Paper metadata<br/>[models.py]"]
  node_sqldb[("SQLite metadata and runs<br/>[db.py]")]
end

subgraph group_query["Search and answers"]
  node_searchapi["Search API<br/>[search.py]"]
  node_chatapi["Chat API<br/>[chat.py]"]
  node_rag["Query planning and RAG<br/>[rag.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_embeddings["Embedding models<br/>[embeddings.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_vectors[("Qdrant vector store<br/>[vector_store.py]")]
  node_llm["Gemini client<br/>[llm.py]"]
  node_citation["Citation validation<br/>[citations.py]"]
end

subgraph group_research["Research tools"]
  node_compareapi["Comparison API<br/>[compare.py]"]
  node_comparison["Paper comparison<br/>[compare.py]"]
  node_citationgraph["Citation graph view<br/>[CitationGraph.tsx]"]
end

subgraph group_evaluation["Evaluation"]
  node_evalapi["Evaluation API<br/>[eval.py]"]
  node_evalrunner["Evaluation runner<br/>[runner.py]"]
  node_evaldata["Evaluation dataset<br/>[dataset.py]"]
  node_metrics["Evaluation metrics"]
end

subgraph group_interface["Web interface"]
  node_web["Research UI<br/>[layout.tsx]"]
  node_library["Paper library<br/>[page.tsx]"]
  node_searchui["Search page<br/>[page.tsx]"]
  node_chatui["Chat page<br/>[page.tsx]"]
  node_compareui["Compare page<br/>[page.tsx]"]
  node_evalui["Evaluation page<br/>[page.tsx]"]
end

node_researcher(("Researcher"))
node_api["FastAPI app<br/>[main.py]"]
node_gemini{{"Google Gemini"}}

node_researcher -->|"uses"| node_web
node_web -->|"navigates"| node_library
node_web -->|"navigates"| node_searchui
node_web -->|"navigates"| node_chatui
node_web -->|"navigates"| node_compareui
node_web -->|"navigates"| node_evalui
node_library -->|"imports papers"| node_paperapi
node_paperapi -->|"starts ingestion"| node_pipeline
node_pipeline -->|"fetches papers"| node_arxiv
node_pipeline -->|"parses PDFs"| node_parser
node_pipeline -->|"chunks sections"| node_chunker
node_pipeline -->|"extracts references"| node_references
node_pipeline -->|"generates summaries"| node_summaries
node_pipeline -->|"upserts chunks"| node_vectors
node_pipeline -->|"updates paper"| node_metadata
node_paperapi -->|"stores metadata"| node_sqldb
node_searchui -->|"searches papers"| node_searchapi
node_searchapi -->|"runs search"| node_hybrid
node_chatui -->|"asks questions"| node_chatapi
node_chatapi -->|"requests answers"| node_rag
node_rag -->|"retrieves passages"| node_hybrid
node_hybrid -->|"embeds queries"| node_embeddings
node_hybrid -->|"queries vectors"| node_vectors
node_hybrid -->|"optionally reranks"| node_reranker
node_rag -->|"plans and generates"| node_llm
node_rag -->|"validates citations"| node_citation
node_llm -->|"calls model"| node_gemini
node_compareui -->|"requests comparison"| node_compareapi
node_compareapi -->|"builds comparison"| node_comparison
node_compareapi -->|"reads paper records"| node_sqldb
node_researcher -->|"explores citations"| node_citationgraph
node_evalui -->|"runs evaluation"| node_evalapi
node_evalapi -->|"starts evaluation"| node_evalrunner
node_evalapi -->|"loads dataset"| node_evaldata
node_evalrunner -->|"computes retrieval metrics"| node_metrics
node_evalapi -->|"stores run results"| node_sqldb

click node_web "https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/layout.tsx"
click node_library "https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/page.tsx"
click node_searchui "https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/search/page.tsx"
click node_chatui "https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/chat/page.tsx"
click node_compareui "https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/compare/page.tsx"
click node_evalui "https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/eval/page.tsx"
click node_api "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/main.py"
click node_paperapi "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/papers.py"
click node_pipeline "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/pipeline.py"
click node_arxiv "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/arxiv_client.py"
click node_parser "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/pdf_parser.py"
click node_chunker "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/chunker.py"
click node_references "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/references.py"
click node_summaries "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/summaries.py"
click node_metadata "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/models.py"
click node_searchapi "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/search.py"
click node_chatapi "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/chat.py"
click node_rag "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/rag.py"
click node_hybrid "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/hybrid.py"
click node_embeddings "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/embeddings.py"
click node_reranker "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/reranker.py"
click node_vectors "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/vector_store.py"
click node_llm "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/llm.py"
click node_citation "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/citations.py"
click node_compareapi "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/compare.py"
click node_comparison "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/compare.py"
click node_citationgraph "https://github.com/aryansaraogi/researchrag/blob/main/frontend/components/CitationGraph.tsx"
click node_evalapi "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/eval.py"
click node_evalrunner "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/evaluation/runner.py"
click node_evaldata "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/evaluation/dataset.py"
click node_metrics "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/evaluation/retrieval_metrics.py"
click node_sqldb "https://github.com/aryansaraogi/researchrag/blob/main/backend/app/db.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_paperapi,node_pipeline,node_arxiv,node_parser,node_chunker,node_references,node_summaries,node_metadata,node_sqldb toneBlue
class node_searchapi,node_chatapi,node_rag,node_hybrid,node_embeddings,node_reranker,node_vectors,node_llm,node_citation toneAmber
class node_compareapi,node_comparison,node_citationgraph,node_api toneMint
class node_evalapi,node_evalrunner,node_evaldata,node_metrics toneRose
class node_web,node_library,node_searchui,node_chatui,node_compareui,node_evalui,node_researcher,node_gemini toneIndigo
```

## Components

### Paper ingestion

- [Paper API](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/papers.py): `backend/app/api/papers.py`
- [Ingestion pipeline](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/pipeline.py): `backend/app/ingestion/pipeline.py`
- [arXiv client](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/arxiv_client.py): `backend/app/ingestion/arxiv_client.py`
- [PDF parser](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/pdf_parser.py): `backend/app/ingestion/pdf_parser.py`
- [Section chunker](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/chunker.py): `backend/app/ingestion/chunker.py`
- [Reference extraction](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/ingestion/references.py): `backend/app/ingestion/references.py`
- [Paper summaries](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/summaries.py): `backend/app/generation/summaries.py`
- [Paper metadata](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/models.py): `backend/app/models.py`
- [SQLite metadata and runs](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/db.py): `backend/app/db.py`

### Search and answers

- [Search API](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/search.py): `backend/app/api/search.py`
- [Chat API](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Query planning and RAG](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/rag.py): `backend/app/generation/rag.py`
- [Hybrid retrieval](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/hybrid.py): `backend/app/retrieval/hybrid.py`
- [Embedding models](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/embeddings.py): `backend/app/retrieval/embeddings.py`
- [Cross-encoder reranker](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/reranker.py): `backend/app/retrieval/reranker.py`
- [Qdrant vector store](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/retrieval/vector_store.py): `backend/app/retrieval/vector_store.py`
- [Gemini client](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/llm.py): `backend/app/generation/llm.py`
- [Citation validation](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/citations.py): `backend/app/generation/citations.py`

### Research tools

- [Comparison API](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/compare.py): `backend/app/api/compare.py`
- [Paper comparison](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/generation/compare.py): `backend/app/generation/compare.py`
- [Citation graph view](https://github.com/aryansaraogi/researchrag/blob/main/frontend/components/CitationGraph.tsx): `frontend/components/CitationGraph.tsx`

### Evaluation

- [Evaluation API](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/api/eval.py): `backend/app/api/eval.py`
- [Evaluation runner](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/evaluation/runner.py): `backend/app/evaluation/runner.py`
- [Evaluation dataset](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/evaluation/dataset.py): `backend/app/evaluation/dataset.py`
- [Evaluation metrics](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/evaluation/retrieval_metrics.py): `backend/app/evaluation/retrieval_metrics.py`

### Web interface

- [Research UI](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/layout.tsx): `frontend/app/layout.tsx`
- [Paper library](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Search page](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/search/page.tsx): `frontend/app/search/page.tsx`
- [Chat page](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/chat/page.tsx): `frontend/app/chat/page.tsx`
- [Compare page](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/compare/page.tsx): `frontend/app/compare/page.tsx`
- [Evaluation page](https://github.com/aryansaraogi/researchrag/blob/main/frontend/app/eval/page.tsx): `frontend/app/eval/page.tsx`

### Other components

- **Researcher**
- [FastAPI app](https://github.com/aryansaraogi/researchrag/blob/main/backend/app/main.py): `backend/app/main.py`
- **Google Gemini**

## Connections

- Researcher → Research UI: uses (evidence: `README.md`)
- Research UI → Paper library: navigates (evidence: `frontend/app/layout.tsx`)
- Research UI → Search page: navigates (evidence: `frontend/app/layout.tsx`)
- Research UI → Chat page: navigates (evidence: `frontend/app/layout.tsx`)
- Research UI → Compare page: navigates (evidence: `frontend/app/layout.tsx`)
- Research UI → Evaluation page: navigates (evidence: `frontend/app/layout.tsx`)
- Paper library → Paper API: imports papers (evidence: `README.md`)
- Paper API → Ingestion pipeline: starts ingestion (evidence: `backend/app/api/papers.py`)
- Ingestion pipeline → arXiv client: fetches papers (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → PDF parser: parses PDFs (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Section chunker: chunks sections (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Reference extraction: extracts references (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Paper summaries: generates summaries (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Qdrant vector store: upserts chunks (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Paper metadata: updates paper (evidence: `backend/app/ingestion/pipeline.py`)
- Paper API → SQLite metadata and runs: stores metadata (evidence: `backend/app/api/papers.py`)
- Search page → Search API: searches papers (evidence: `README.md`)
- Search API → Hybrid retrieval: runs search (evidence: `backend/app/api/search.py`)
- Chat page → Chat API: asks questions (evidence: `README.md`)
- Chat API → Query planning and RAG: requests answers (evidence: `backend/app/api/chat.py`)
- Query planning and RAG → Hybrid retrieval: retrieves passages (evidence: `backend/app/generation/rag.py`)
- Hybrid retrieval → Embedding models: embeds queries (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid retrieval → Qdrant vector store: queries vectors (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid retrieval → Cross-encoder reranker: optionally reranks (evidence: `backend/app/retrieval/hybrid.py`)
- Query planning and RAG → Gemini client: plans and generates (evidence: `backend/app/generation/rag.py`)
- Query planning and RAG → Citation validation: validates citations (evidence: `backend/app/generation/rag.py`)
- Gemini client → Google Gemini: calls model (evidence: `README.md`)
- Compare page → Comparison API: requests comparison (evidence: `README.md`)
- Comparison API → Paper comparison: builds comparison (evidence: `backend/app/api/compare.py`)
- Comparison API → SQLite metadata and runs: reads paper records (evidence: `backend/app/api/compare.py`)
- Researcher → Citation graph view: explores citations (evidence: `README.md`)
- Evaluation page → Evaluation API: runs evaluation (evidence: `README.md`)
- Evaluation API → Evaluation runner: starts evaluation (evidence: `backend/app/api/eval.py`)
- Evaluation API → Evaluation dataset: loads dataset (evidence: `backend/app/api/eval.py`)
- Evaluation runner → Evaluation metrics: computes retrieval metrics (evidence: `README.md`)
- Evaluation API → SQLite metadata and runs: stores run results (evidence: `backend/app/api/eval.py`)
