# unnatiagarwal02/pubmed-rag-assistant architecture

> Architecture diagram of the GitHub repository unnatiagarwal02/pubmed-rag-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unnatiagarwal02/pubmed-rag-assistant
- Repository: https://github.com/unnatiagarwal02/pubmed-rag-assistant

## Overview

PubMed RAG Assistant collects brain-tumor MRI research abstracts, prepares and indexes them, then answers questions from retrieved passages with PMID citations and optional support checks. The main path is user → web UI/API → retrieval and answer generation → guardrail verdict. A separate corpus-refresh path fetches PubMed records and rebuilds the vector index. The README documents the UI and metadata endpoints; the frontend implementation was not sampled, so its internal behavior is not expanded here.

Main entry points: [`pubmed_rag/api.py`](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/api.py) (FastAPI service), [`pubmed_rag/rag.py`](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/rag.py) (Retrieve and answer), [`frontend/index.html`](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/frontend/index.html) (Web UI), [`pubmed_rag/index.py`](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/index.py) (Build index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Corpus acquisition"]
  node_fetch["Fetch records<br/>[fetch.py]"]
  node_raw["Abstract records<br/>[abstracts.jsonl]"]
end

subgraph group_indexing["Preparation and indexing"]
  node_chunk["Clean and chunk<br/>[chunk.py]"]
  node_index["Build index<br/>[index.py]"]
  node_chroma[("Chroma collection<br/>[index.py]")]
end

subgraph group_answering["Answer and verification"]
  node_rag["Retrieve and answer<br/>[rag.py]"]
  node_guardrail["Support checks<br/>[guardrail.py]"]
end

subgraph group_interface["User interface"]
  node_api["FastAPI service<br/>[api.py]"]
  node_ui["Web UI<br/>[index.html]"]
end

node_researcher(("Questioner"))
node_pubmed{{"PubMed E-utilities"}}
node_groq{{"Groq LLM"}}

node_researcher -->|"asks"| node_ui
node_ui -->|"submits question"| node_api
node_api -->|"serves"| node_ui
node_api -->|"requests answer"| node_rag
node_rag -->|"retrieves passages"| node_chroma
node_rag -->|"generates answer"| node_groq
node_api -->|"checks result"| node_guardrail
node_guardrail -->|"judges claims"| node_groq
node_pubmed -->|"supplies records"| node_fetch
node_fetch -->|"writes JSONL"| node_raw
node_chunk -->|"reads records"| node_raw
node_index -->|"cleans and chunks"| node_chunk
node_index -->|"embeds and stores"| node_chroma

click node_fetch "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/fetch.py"
click node_raw "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/data/raw/abstracts.jsonl"
click node_chunk "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/chunk.py"
click node_index "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/index.py"
click node_chroma "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/index.py"
click node_rag "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/rag.py"
click node_guardrail "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/guardrail.py"
click node_api "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/api.py"
click node_ui "https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/frontend/index.html"

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_fetch,node_raw toneBlue
class node_chunk,node_index,node_chroma toneAmber
class node_rag,node_guardrail toneMint
class node_api,node_ui toneRose
class node_researcher,node_pubmed,node_groq toneIndigo
```

## Components

### Corpus acquisition

- [Fetch records](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/fetch.py): `pubmed_rag/fetch.py`
- [Abstract records](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/data/raw/abstracts.jsonl): `data/raw/abstracts.jsonl`

### Preparation and indexing

- [Clean and chunk](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/chunk.py): `pubmed_rag/chunk.py`
- [Build index](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/index.py): `pubmed_rag/index.py`
- [Chroma collection](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/index.py): `pubmed_rag/index.py`

### Answer and verification

- [Retrieve and answer](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/rag.py): `pubmed_rag/rag.py`
- [Support checks](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/guardrail.py): `pubmed_rag/guardrail.py`

### User interface

- [FastAPI service](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/pubmed_rag/api.py): `pubmed_rag/api.py`
- [Web UI](https://github.com/unnatiagarwal02/pubmed-rag-assistant/blob/main/frontend/index.html): `frontend/index.html`

### Other components

- **Questioner**
- **PubMed E-utilities**
- **Groq LLM**

## Connections

- Questioner → Web UI: asks
- Web UI → FastAPI service: submits question
- FastAPI service → Web UI: serves
- FastAPI service → Retrieve and answer: requests answer
- Retrieve and answer → Chroma collection: retrieves passages
- Retrieve and answer → Groq LLM: generates answer
- FastAPI service → Support checks: checks result
- Support checks → Groq LLM: judges claims
- PubMed E-utilities → Fetch records: supplies records
- Fetch records → Abstract records: writes JSONL
- Clean and chunk → Abstract records: reads records
- Build index → Clean and chunk: cleans and chunks
- Build index → Chroma collection: embeds and stores