# shashankkrishnav/researchrag architecture

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

- Interactive diagram: https://gitdiagram.com/shashankkrishnav/researchrag
- Repository: https://github.com/shashankkrishnav/researchrag

## Overview

ResearchRAG is a local research-paper RAG app. Users upload papers in the Library, where the API extracts page-aware text, chunks it, embeds it, and stores the index; in Ask, a question triggers hybrid retrieval and reranking, then optionally streams a grounded answer with citations from local Ollama. The graph preserves the documented rebuild and library-management capabilities. Some API and UI wiring is shown only in the README, so those edges cite it; unsampled implementation details are not inferred.

Main entry points: [`app/main.py`](https://github.com/shashankkrishnav/researchrag/blob/main/app/main.py) (FastAPI routes), [`app/retriever.py`](https://github.com/shashankkrishnav/researchrag/blob/main/app/retriever.py) (Hybrid retrieval), [`app/reindex.py`](https://github.com/shashankkrishnav/researchrag/blob/main/app/reindex.py) (Index rebuild), [`app/store.py`](https://github.com/shashankkrishnav/researchrag/blob/main/app/store.py) (Persistent index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_library["Library page<br/>[library.html]"]
  node_library_ui["Library controls<br/>[library.js]"]
  node_ask["Ask page<br/>[ask.html]"]
  node_ask_ui["Ask controls<br/>[ask.js]"]
end

subgraph group_api["Application API"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_pipeline["Document and retrieval pipeline"]
  node_ingest["Parse and chunk<br/>[ingest.py]"]
  node_models["Embedding and reranking<br/>[models.py]"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_bm25["BM25 search<br/>[bm25.py]"]
  node_llm["Grounded generation<br/>[llm.py]"]
end

subgraph group_state["Index and maintenance"]
  node_index[("Persistent index<br/>[store.py]")]
  node_reindex["Index rebuild<br/>[reindex.py]"]
end

node_user(("Researcher"))
node_ollama["Ollama service"]

node_user -->|"uploads papers"| node_library
node_user -->|"asks questions"| node_ask
node_library -->|"loads controls"| node_library_ui
node_ask -->|"loads controls"| node_ask_ui
node_library_ui -->|"manages library"| node_api
node_ask_ui -->|"searches and asks"| node_api
node_api -->|"parses uploads"| node_ingest
node_api -->|"embeds documents"| node_models
node_api -->|"stores documents"| node_index
node_api -->|"retrieves passages"| node_retriever
node_retriever -->|"reads index"| node_index
node_retriever -->|"scores keywords"| node_bm25
node_retriever -->|"embeds and reranks"| node_models
node_index -->|"builds keyword index"| node_bm25
node_api -->|"streams answer"| node_llm
node_llm -->|"requests generation"| node_ollama
node_api -->|"starts rebuild"| node_reindex
node_reindex -->|"reparses papers"| node_ingest
node_reindex -->|"re-embeds chunks"| node_models
node_reindex -->|"rebuilds index"| node_index
node_api -->|"uses settings"| node_config
node_llm -->|"reads model settings"| node_config

click node_library "https://github.com/shashankkrishnav/researchrag/blob/main/web/library.html"
click node_library_ui "https://github.com/shashankkrishnav/researchrag/blob/main/web/library.js"
click node_ask "https://github.com/shashankkrishnav/researchrag/blob/main/web/ask.html"
click node_ask_ui "https://github.com/shashankkrishnav/researchrag/blob/main/web/ask.js"
click node_api "https://github.com/shashankkrishnav/researchrag/blob/main/app/main.py"
click node_ingest "https://github.com/shashankkrishnav/researchrag/blob/main/app/ingest.py"
click node_models "https://github.com/shashankkrishnav/researchrag/blob/main/app/models.py"
click node_retriever "https://github.com/shashankkrishnav/researchrag/blob/main/app/retriever.py"
click node_bm25 "https://github.com/shashankkrishnav/researchrag/blob/main/app/bm25.py"
click node_index "https://github.com/shashankkrishnav/researchrag/blob/main/app/store.py"
click node_reindex "https://github.com/shashankkrishnav/researchrag/blob/main/app/reindex.py"
click node_config "https://github.com/shashankkrishnav/researchrag/blob/main/app/config.py"
click node_llm "https://github.com/shashankkrishnav/researchrag/blob/main/app/llm.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_library,node_library_ui,node_ask,node_ask_ui toneBlue
class node_api,node_config toneAmber
class node_ingest,node_models,node_retriever,node_bm25,node_llm toneMint
class node_index,node_reindex toneRose
class node_user,node_ollama toneIndigo
```

## Components

### Web interface

- [Library page](https://github.com/shashankkrishnav/researchrag/blob/main/web/library.html): `web/library.html`
- [Library controls](https://github.com/shashankkrishnav/researchrag/blob/main/web/library.js): `web/library.js`
- [Ask page](https://github.com/shashankkrishnav/researchrag/blob/main/web/ask.html): `web/ask.html`
- [Ask controls](https://github.com/shashankkrishnav/researchrag/blob/main/web/ask.js): `web/ask.js`

### Application API

- [FastAPI routes](https://github.com/shashankkrishnav/researchrag/blob/main/app/main.py): `app/main.py`
- [Runtime settings](https://github.com/shashankkrishnav/researchrag/blob/main/app/config.py): `app/config.py`

### Document and retrieval pipeline

- [Parse and chunk](https://github.com/shashankkrishnav/researchrag/blob/main/app/ingest.py): `app/ingest.py`
- [Embedding and reranking](https://github.com/shashankkrishnav/researchrag/blob/main/app/models.py): `app/models.py`
- [Hybrid retrieval](https://github.com/shashankkrishnav/researchrag/blob/main/app/retriever.py): `app/retriever.py`
- [BM25 search](https://github.com/shashankkrishnav/researchrag/blob/main/app/bm25.py): `app/bm25.py`
- [Grounded generation](https://github.com/shashankkrishnav/researchrag/blob/main/app/llm.py): `app/llm.py`

### Index and maintenance

- [Persistent index](https://github.com/shashankkrishnav/researchrag/blob/main/app/store.py): `app/store.py`
- [Index rebuild](https://github.com/shashankkrishnav/researchrag/blob/main/app/reindex.py): `app/reindex.py`

### Other components

- **Researcher**
- **Ollama service**

## Connections

- Researcher → Library page: uploads papers (evidence: `README.md`)
- Researcher → Ask page: asks questions (evidence: `README.md`)
- Library page → Library controls: loads controls (evidence: `README.md`)
- Ask page → Ask controls: loads controls (evidence: `README.md`)
- Library controls → FastAPI routes: manages library (evidence: `README.md`)
- Ask controls → FastAPI routes: searches and asks (evidence: `README.md`)
- FastAPI routes → Parse and chunk: parses uploads (evidence: `app/main.py`)
- FastAPI routes → Embedding and reranking: embeds documents (evidence: `app/main.py`)
- FastAPI routes → Persistent index: stores documents (evidence: `app/main.py`)
- FastAPI routes → Hybrid retrieval: retrieves passages (evidence: `app/main.py`)
- Hybrid retrieval → Persistent index: reads index (evidence: `app/retriever.py`)
- Hybrid retrieval → BM25 search: scores keywords (evidence: `app/retriever.py`)
- Hybrid retrieval → Embedding and reranking: embeds and reranks (evidence: `app/retriever.py`)
- Persistent index → BM25 search: builds keyword index (evidence: `app/store.py`)
- FastAPI routes → Grounded generation: streams answer (evidence: `app/main.py`)
- Grounded generation → Ollama service: requests generation (evidence: `app/llm.py`)
- FastAPI routes → Index rebuild: starts rebuild (evidence: `app/main.py`)
- Index rebuild → Parse and chunk: reparses papers (evidence: `app/reindex.py`)
- Index rebuild → Embedding and reranking: re-embeds chunks (evidence: `app/reindex.py`)
- Index rebuild → Persistent index: rebuilds index (evidence: `app/reindex.py`)
- FastAPI routes → Runtime settings: uses settings (evidence: `app/main.py`)
- Grounded generation → Runtime settings: reads model settings (evidence: `app/llm.py`)