# mithun50/ragbot architecture

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

- Interactive diagram: https://gitdiagram.com/mithun50/ragbot
- Repository: https://github.com/mithun50/ragbot

## Overview

RagBot lets users upload documents and ask grounded questions with passage citations. Uploads are parsed page by page, chunked, indexed, and summarized; questions are retrieved and ranked against that index, then answered by a streaming model call or refused when evidence is insufficient. The API also exposes document management and question analytics, presented through a single-page frontend. The README documents retrieval details and API capabilities; some frontend and retrieval internals were not sampled, so their links rely on those documented relationships.

Main entry points: [`app/main.py`](https://github.com/mithun50/ragbot/blob/main/app/main.py) (FastAPI Routes), [`app/ingest.py`](https://github.com/mithun50/ragbot/blob/main/app/ingest.py) (Background Ingestion), [`app/qa.py`](https://github.com/mithun50/ragbot/blob/main/app/qa.py) (Grounded QA), [`app/index.py`](https://github.com/mithun50/ragbot/blob/main/app/index.py) (BM25 Document Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_frontend["Web Frontend<br/>[app.js]"]
  node_api["FastAPI Routes<br/>[main.py]"]
end

subgraph group_ingestion["Document Ingestion"]
  node_ingest["Background Ingestion<br/>[ingest.py]"]
  node_parsing["Document Parsing<br/>[parsing.py]"]
  node_chunking["Page Chunking<br/>[chunking.py]"]
  node_summarize["Document Summaries<br/>[summarize.py]"]
end

subgraph group_qa["Question Answering"]
  node_qa_flow["Grounded QA<br/>[qa.py]"]
  node_prompts["Grounding Prompts<br/>[prompts.py]"]
end

subgraph group_data["Index and Analytics"]
  node_store[("BM25 Document Store<br/>[index.py]")]
  node_analytics[("Question Analytics<br/>[analytics.py]")]
end

subgraph group_external["Model Integration"]
  node_llm["Model Client<br/>[llm.py]"]
end

node_user(("User"))
node_openrouter{{"OpenRouter"}}

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"starts ingestion"| node_ingest
node_api -->|"manages documents"| node_store
node_api -->|"asks question"| node_qa_flow
node_api -->|"serves analytics"| node_analytics
node_ingest -->|"iterates pages"| node_parsing
node_ingest -->|"chunks pages"| node_chunking
node_ingest -->|"adds chunks"| node_store
node_ingest -->|"builds summary"| node_summarize
node_summarize -->|"reads chunks"| node_store
node_summarize -->|"requests summary"| node_llm
node_qa_flow -->|"retrieves passages"| node_store
node_qa_flow -->|"formats context"| node_prompts
node_qa_flow -->|"streams answer"| node_llm
node_qa_flow -->|"records question"| node_analytics
node_analytics -->|"reads document stats"| node_store
node_llm -->|"sends model requests"| node_openrouter

click node_frontend "https://github.com/mithun50/ragbot/blob/main/static/app.js"
click node_api "https://github.com/mithun50/ragbot/blob/main/app/main.py"
click node_ingest "https://github.com/mithun50/ragbot/blob/main/app/ingest.py"
click node_parsing "https://github.com/mithun50/ragbot/blob/main/app/parsing.py"
click node_chunking "https://github.com/mithun50/ragbot/blob/main/app/chunking.py"
click node_summarize "https://github.com/mithun50/ragbot/blob/main/app/summarize.py"
click node_qa_flow "https://github.com/mithun50/ragbot/blob/main/app/qa.py"
click node_prompts "https://github.com/mithun50/ragbot/blob/main/app/prompts.py"
click node_store "https://github.com/mithun50/ragbot/blob/main/app/index.py"
click node_analytics "https://github.com/mithun50/ragbot/blob/main/app/analytics.py"
click node_llm "https://github.com/mithun50/ragbot/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_frontend,node_api,node_user toneBlue
class node_ingest,node_parsing,node_chunking,node_summarize toneAmber
class node_qa_flow,node_prompts,node_openrouter toneMint
class node_store,node_analytics toneRose
class node_llm toneIndigo
```

## Components

### User Interface

- [Web Frontend](https://github.com/mithun50/ragbot/blob/main/static/app.js): `static/app.js`
- [FastAPI Routes](https://github.com/mithun50/ragbot/blob/main/app/main.py): `app/main.py`

### Document Ingestion

- [Background Ingestion](https://github.com/mithun50/ragbot/blob/main/app/ingest.py): `app/ingest.py`
- [Document Parsing](https://github.com/mithun50/ragbot/blob/main/app/parsing.py): `app/parsing.py`
- [Page Chunking](https://github.com/mithun50/ragbot/blob/main/app/chunking.py): `app/chunking.py`
- [Document Summaries](https://github.com/mithun50/ragbot/blob/main/app/summarize.py): `app/summarize.py`

### Question Answering

- [Grounded QA](https://github.com/mithun50/ragbot/blob/main/app/qa.py): `app/qa.py`
- [Grounding Prompts](https://github.com/mithun50/ragbot/blob/main/app/prompts.py): `app/prompts.py`

### Index and Analytics

- [BM25 Document Store](https://github.com/mithun50/ragbot/blob/main/app/index.py): `app/index.py`
- [Question Analytics](https://github.com/mithun50/ragbot/blob/main/app/analytics.py): `app/analytics.py`

### Model Integration

- [Model Client](https://github.com/mithun50/ragbot/blob/main/app/llm.py): `app/llm.py`

### Other components

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

## Connections

- User → Web Frontend: uses (evidence: `README.md`)
- Web Frontend → FastAPI Routes: calls API (evidence: `README.md`)
- FastAPI Routes → Background Ingestion: starts ingestion (evidence: `app/main.py`)
- FastAPI Routes → BM25 Document Store: manages documents (evidence: `app/main.py`)
- FastAPI Routes → Grounded QA: asks question (evidence: `app/main.py`)
- FastAPI Routes → Question Analytics: serves analytics (evidence: `app/main.py`)
- Background Ingestion → Document Parsing: iterates pages (evidence: `app/ingest.py`)
- Background Ingestion → Page Chunking: chunks pages (evidence: `app/ingest.py`)
- Background Ingestion → BM25 Document Store: adds chunks (evidence: `app/ingest.py`)
- Background Ingestion → Document Summaries: builds summary (evidence: `app/ingest.py`)
- Document Summaries → BM25 Document Store: reads chunks (evidence: `app/summarize.py`)
- Document Summaries → Model Client: requests summary (evidence: `app/summarize.py`)
- Grounded QA → BM25 Document Store: retrieves passages (evidence: `app/qa.py`)
- Grounded QA → Grounding Prompts: formats context (evidence: `app/qa.py`)
- Grounded QA → Model Client: streams answer (evidence: `app/qa.py`)
- Grounded QA → Question Analytics: records question (evidence: `app/qa.py`)
- Question Analytics → BM25 Document Store: reads document stats (evidence: `app/analytics.py`)
- Model Client → OpenRouter: sends model requests (evidence: `README.md`)
