# choeyunbeom/arxiv_rag_system architecture

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

- Interactive diagram: https://gitdiagram.com/choeyunbeom/arxiv_rag_system
- Repository: https://github.com/choeyunbeom/arxiv_rag_system

## Overview

This is an arXiv-paper question-answering product: users submit a question through the Streamlit interface or API, retrieve and rerank relevant paper chunks, then receive a grounded answer with citations and latency information. A separate ingestion workflow collects papers, parses PDFs, chunks text, and indexes it for retrieval. The repository also includes benchmark evaluation, synthetic Q&A generation, LoRA fine-tuning, and embedding-space visualization. Relationships for sampled runtime code are based on excerpts and the SOURCE INDEX; ingestion and some UI capabilities are documented in the README, while their implementation details were not sampled.

Main entry points: [`src/api/core/rag_chain.py`](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/rag_chain.py) (RAG orchestrator), [`src/api/core/hybrid_retriever.py`](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/hybrid_retriever.py) (Hybrid retrieval), [`src/evaluation/evaluate.py`](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/evaluation/evaluate.py) (RAG evaluation), [`src/api/main.py`](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Paper ingestion"]
  node_crawler["arXiv crawler<br/>[arxiv_crawler.py]"]
  node_parser["PDF parser<br/>[pdf_parser.py]"]
  node_chunker["Text chunker<br/>[chunker.py]"]
  node_indexer["Corpus indexer<br/>[indexer.py]"]
end

subgraph group_serving["Query service"]
  node_api["FastAPI app<br/>[main.py]"]
  node_query["Query endpoints<br/>[query.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_retrieval["Retrieval and generation"]
  node_rag["RAG orchestrator<br/>[rag_chain.py]"]
  node_retriever["Hybrid retrieval"]
  node_prompts["Answer prompts<br/>[prompts.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_experiments["ML experiments"]
  node_evaluation["RAG evaluation<br/>[evaluate.py]"]
  node_evaldata["Benchmark dataset<br/>[eval_dataset.py]"]
  node_qa["Synthetic Q&amp;A"]
  node_finetuning["LoRA training"]
end

subgraph group_presentation["User experience"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_visualization["Embedding visualization<br/>[precompute_umap.py]"]
end

node_user(("Question asker"))
node_ollama{{"Ollama service"}}
node_chroma[("ChromaDB")]

node_user -->|"asks through"| node_streamlit
node_streamlit -->|"submits query"| node_api
node_api -->|"mounts router"| node_query
node_api -->|"mounts router"| node_health
node_query -->|"runs query"| node_rag
node_query -->|"validates and returns"| node_schemas
node_rag -->|"retrieves chunks"| node_retriever
node_rag -->|"generates answer"| node_llm
node_rag -->|"uses templates"| node_prompts
node_retriever -->|"searches vectors"| node_chroma
node_retriever -->|"embeds query"| node_ollama
node_llm -->|"generates text"| node_ollama
node_crawler -.->|"provides PDFs"| node_parser
node_parser -.->|"produces parsed text"| node_chunker
node_chunker -.->|"provides chunks"| node_indexer
node_indexer -.->|"indexes corpus"| node_chroma
node_evaluation -->|"benchmarks with"| node_evaldata
node_evaluation -->|"measures retrieval"| node_retriever
node_evaluation -->|"measures answers"| node_rag
node_qa -->|"generates examples"| node_ollama
node_qa -.->|"prepares training data"| node_finetuning
node_streamlit -.->|"uses precomputed map"| node_visualization

click node_streamlit "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/ui/app.py"
click node_api "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/main.py"
click node_query "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/routers/query.py"
click node_health "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/routers/health.py"
click node_schemas "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/models/schemas.py"
click node_rag "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/rag_chain.py"
click node_retriever "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/hybrid_retriever.py"
click node_prompts "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/prompts.py"
click node_llm "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/llm_client.py"
click node_crawler "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/ingestion/arxiv_crawler.py"
click node_parser "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/ingestion/pdf_parser.py"
click node_chunker "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/chunker.py"
click node_indexer "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/ingestion/indexer.py"
click node_evaluation "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/evaluation/evaluate.py"
click node_evaldata "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/evaluation/eval_dataset.py"
click node_qa "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/finetuning/generate_qa_dataset.py"
click node_finetuning "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/finetuning/finetune_lora.ipynb"
click node_visualization "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/scripts/precompute_umap.py"
click node_config "https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/config.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_crawler,node_parser,node_chunker,node_indexer toneBlue
class node_api,node_query,node_health,node_schemas,node_config,node_chroma toneAmber
class node_rag,node_retriever,node_prompts,node_llm toneMint
class node_evaluation,node_evaldata,node_qa,node_finetuning toneRose
class node_streamlit,node_visualization,node_user,node_ollama toneIndigo
```

## Components

### Paper ingestion

- [arXiv crawler](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/ingestion/arxiv_crawler.py): `src/ingestion/arxiv_crawler.py`
- [PDF parser](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/ingestion/pdf_parser.py): `src/ingestion/pdf_parser.py`
- [Text chunker](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/chunker.py): `src/api/core/chunker.py`
- [Corpus indexer](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/ingestion/indexer.py): `src/ingestion/indexer.py`

### Query service

- [FastAPI app](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/main.py): `src/api/main.py`
- [Query endpoints](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/routers/query.py): `src/api/routers/query.py`
- [Health endpoint](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/routers/health.py): `src/api/routers/health.py`
- [API schemas](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/models/schemas.py): `src/api/models/schemas.py`
- [Runtime settings](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/config.py): `src/api/core/config.py`

### Retrieval and generation

- [RAG orchestrator](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/rag_chain.py): `src/api/core/rag_chain.py`
- [Hybrid retrieval](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/hybrid_retriever.py): `src/api/core/hybrid_retriever.py`
- [Answer prompts](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/prompts.py): `src/api/core/prompts.py`
- [LLM client](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/api/core/llm_client.py): `src/api/core/llm_client.py`

### ML experiments

- [RAG evaluation](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/evaluation/evaluate.py): `src/evaluation/evaluate.py`
- [Benchmark dataset](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/evaluation/eval_dataset.py): `src/evaluation/eval_dataset.py`
- [Synthetic Q&A](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/finetuning/generate_qa_dataset.py): `src/finetuning/generate_qa_dataset.py`
- [LoRA training](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/src/finetuning/finetune_lora.ipynb): `src/finetuning/finetune_lora.ipynb`

### User experience

- [Streamlit UI](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/ui/app.py): `ui/app.py`
- [Embedding visualization](https://github.com/choeyunbeom/arxiv_rag_system/blob/main/scripts/precompute_umap.py): `scripts/precompute_umap.py`

### Other components

- **Question asker**
- **Ollama service**
- **ChromaDB**

## Connections

- Question asker → Streamlit UI: asks through (evidence: `README.md`)
- Streamlit UI → FastAPI app: submits query (evidence: `README.md`)
- FastAPI app → Query endpoints: mounts router (evidence: `src/api/main.py`)
- FastAPI app → Health endpoint: mounts router (evidence: `src/api/main.py`)
- Query endpoints → RAG orchestrator: runs query (evidence: `src/api/routers/query.py`)
- Query endpoints → API schemas: validates and returns (evidence: `src/api/routers/query.py`)
- RAG orchestrator → Hybrid retrieval: retrieves chunks (evidence: `src/api/core/rag_chain.py`)
- RAG orchestrator → LLM client: generates answer (evidence: `src/api/core/rag_chain.py`)
- RAG orchestrator → Answer prompts: uses templates (evidence: `src/api/core/rag_chain.py`)
- Hybrid retrieval → ChromaDB: searches vectors (evidence: `src/api/core/hybrid_retriever.py`)
- Hybrid retrieval → Ollama service: embeds query (evidence: `src/api/core/hybrid_retriever.py`)
- LLM client → Ollama service: generates text (evidence: `src/api/core/llm_client.py`)
- arXiv crawler → PDF parser: provides PDFs (evidence: `README.md`)
- PDF parser → Text chunker: produces parsed text (evidence: `README.md`)
- Text chunker → Corpus indexer: provides chunks (evidence: `README.md`)
- Corpus indexer → ChromaDB: indexes corpus (evidence: `README.md`)
- RAG evaluation → Benchmark dataset: benchmarks with (evidence: `src/evaluation/evaluate.py`)
- RAG evaluation → Hybrid retrieval: measures retrieval (evidence: `src/evaluation/evaluate.py`)
- RAG evaluation → RAG orchestrator: measures answers (evidence: `src/evaluation/evaluate.py`)
- Synthetic Q&A → Ollama service: generates examples (evidence: `src/finetuning/generate_qa_dataset.py`)
- Synthetic Q&A → LoRA training: prepares training data (evidence: `README.md`)
- Streamlit UI → Embedding visualization: uses precomputed map (evidence: `README.md`)