# rohithreddy39/mediq-rag architecture

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

- Interactive diagram: https://gitdiagram.com/rohithreddy39/mediq-rag
- Repository: https://github.com/rohithreddy39/mediq-rag

## Overview

MediQ is a Medicare-policy RAG assistant: administrators ask questions and receive answers grounded in retrieved policy passages, with source citations and safety checks. The documented workflow runs from PDF ingestion through chunking, tagging and embedding, into dense-plus-sparse retrieval, prompt construction, generation and response checks. The product also exposes a Streamlit chat UI and REST API, and includes an evaluation pipeline. Some UI and evaluation internals are unsampled, so their connections are limited to relationships shown in excerpts, the source index or README.

Main entry points: [`mediq/ingestion/pipeline.py`](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/pipeline.py) (Ingestion pipeline), [`mediq/evaluation/eval_runner.py`](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/eval_runner.py) (Evaluation runner), [`mediq/api/main.py`](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/api/main.py) (REST API), [`mediq/ui/app.py`](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ui/app.py) (Streamlit chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_config["Configuration<br/>[config.py]"]
  node_parser["PDF parser<br/>[pdf_parser.py]"]
  node_chunker["Text chunker<br/>[chunker.py]"]
  node_tagger["Metadata tagger<br/>[metadata_tagger.py]"]
  node_embedder["Embedder<br/>[embedder.py]"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_chunks["Processed chunks<br/>[chunks.json]"]
end

subgraph group_retrieve["Hybrid retrieval"]
  node_vector[("FAISS vector store<br/>[vector_store.py]")]
  node_bm25[("BM25 index<br/>[bm25_index.py]")]
  node_hybrid["Hybrid retriever"]
end

subgraph group_answer["Answer generation"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_prompt["Prompt builder<br/>[prompt_builder.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_api["REST API<br/>[main.py]"]
  node_ui["Streamlit chat UI<br/>[app.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation runner<br/>[eval_runner.py]"]
  node_scorers["Evaluation scorers<br/>[scorers.py]"]
  node_golden["Golden dataset"]
end

node_admin(("Administrator"))
node_pdfs["Medicare PDFs"]
node_openai{{"OpenAI API"}}

node_admin -->|"asks questions"| node_ui
node_admin -->|"submits queries"| node_api
node_pdfs -->|"provides documents"| node_pipeline
node_pipeline -->|"parses PDFs"| node_parser
node_pipeline -->|"chunks pages"| node_chunker
node_pipeline -->|"tags chunks"| node_tagger
node_pipeline -->|"embeds chunks"| node_embedder
node_pipeline -->|"writes processed data"| node_chunks
node_config -->|"configures paths"| node_pipeline
node_chunks -->|"loads chunks"| node_api
node_chunks -->|"loads chunks"| node_ui
node_api -->|"retrieves evidence"| node_hybrid
node_api -->|"builds prompt"| node_prompt
node_api -->|"generates answer"| node_llm
node_api -->|"checks safety"| node_guardrails
node_ui -->|"retrieves evidence"| node_hybrid
node_ui -->|"builds prompt"| node_prompt
node_ui -->|"generates answer"| node_llm
node_ui -->|"checks safety"| node_guardrails
node_hybrid -->|"searches dense"| node_vector
node_hybrid -->|"searches sparse"| node_bm25
node_hybrid -.->|"returns ranked chunks"| node_prompt
node_llm -->|"calls model"| node_openai
node_eval -->|"evaluates retrieval"| node_hybrid
node_eval -->|"builds test prompts"| node_prompt
node_eval -->|"generates test answers"| node_llm
node_eval -->|"checks scope"| node_guardrails
node_eval -->|"scores results"| node_scorers
node_eval -.->|"reads test cases"| node_golden

click node_config "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/config.py"
click node_parser "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/pdf_parser.py"
click node_chunker "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/chunker.py"
click node_tagger "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/metadata_tagger.py"
click node_embedder "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/embedder.py"
click node_pipeline "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/pipeline.py"
click node_chunks "https://github.com/rohithreddy39/mediq-rag/blob/main/data/processed/chunks.json"
click node_vector "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/retrieval/vector_store.py"
click node_bm25 "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/retrieval/bm25_index.py"
click node_hybrid "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/retrieval/hybrid_retriever.py"
click node_guardrails "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/generation/guardrails.py"
click node_prompt "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/generation/prompt_builder.py"
click node_llm "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/generation/llm_client.py"
click node_api "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/api/main.py"
click node_ui "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ui/app.py"
click node_eval "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/eval_runner.py"
click node_scorers "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/scorers.py"
click node_golden "https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/golden_dataset.json"

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_config,node_parser,node_chunker,node_tagger,node_embedder,node_pipeline,node_chunks toneBlue
class node_vector,node_bm25,node_hybrid toneAmber
class node_guardrails,node_prompt,node_llm,node_openai toneMint
class node_api,node_ui toneRose
class node_eval,node_scorers,node_golden,node_admin,node_pdfs toneIndigo
```

## Components

### Document ingestion

- [Configuration](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/config.py): `mediq/config.py`
- [PDF parser](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/pdf_parser.py): `mediq/ingestion/pdf_parser.py`
- [Text chunker](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/chunker.py): `mediq/ingestion/chunker.py`
- [Metadata tagger](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/metadata_tagger.py): `mediq/ingestion/metadata_tagger.py`
- [Embedder](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/embedder.py): `mediq/ingestion/embedder.py`
- [Ingestion pipeline](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ingestion/pipeline.py): `mediq/ingestion/pipeline.py`
- [Processed chunks](https://github.com/rohithreddy39/mediq-rag/blob/main/data/processed/chunks.json): `data/processed/chunks.json`

### Hybrid retrieval

- [FAISS vector store](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/retrieval/vector_store.py): `mediq/retrieval/vector_store.py`
- [BM25 index](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/retrieval/bm25_index.py): `mediq/retrieval/bm25_index.py`
- [Hybrid retriever](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/retrieval/hybrid_retriever.py): `mediq/retrieval/hybrid_retriever.py`

### Answer generation

- [Guardrails](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/generation/guardrails.py): `mediq/generation/guardrails.py`
- [Prompt builder](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/generation/prompt_builder.py): `mediq/generation/prompt_builder.py`
- [LLM client](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/generation/llm_client.py): `mediq/generation/llm_client.py`

### User interfaces

- [REST API](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/api/main.py): `mediq/api/main.py`
- [Streamlit chat UI](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/ui/app.py): `mediq/ui/app.py`

### Evaluation

- [Evaluation runner](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/eval_runner.py): `mediq/evaluation/eval_runner.py`
- [Evaluation scorers](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/scorers.py): `mediq/evaluation/scorers.py`
- [Golden dataset](https://github.com/rohithreddy39/mediq-rag/blob/main/mediq/evaluation/golden_dataset.json): `mediq/evaluation/golden_dataset.json`

### Other components

- **Administrator**
- **Medicare PDFs**
- **OpenAI API**

## Connections

- Administrator → Streamlit chat UI: asks questions (evidence: `README.md`)
- Administrator → REST API: submits queries (evidence: `README.md`)
- Medicare PDFs → Ingestion pipeline: provides documents (evidence: `README.md`)
- Ingestion pipeline → PDF parser: parses PDFs (evidence: `mediq/ingestion/pipeline.py`)
- Ingestion pipeline → Text chunker: chunks pages (evidence: `mediq/ingestion/pipeline.py`)
- Ingestion pipeline → Metadata tagger: tags chunks (evidence: `mediq/ingestion/pipeline.py`)
- Ingestion pipeline → Embedder: embeds chunks (evidence: `mediq/ingestion/pipeline.py`)
- Ingestion pipeline → Processed chunks: writes processed data (evidence: `README.md`)
- Configuration → Ingestion pipeline: configures paths (evidence: `mediq/config.py`)
- Processed chunks → REST API: loads chunks (evidence: `mediq/api/main.py`)
- Processed chunks → Streamlit chat UI: loads chunks (evidence: `mediq/ui/app.py`)
- REST API → Hybrid retriever: retrieves evidence (evidence: `mediq/api/main.py`)
- REST API → Prompt builder: builds prompt (evidence: `mediq/api/main.py`)
- REST API → LLM client: generates answer (evidence: `mediq/api/main.py`)
- REST API → Guardrails: checks safety (evidence: `mediq/api/main.py`)
- Streamlit chat UI → Hybrid retriever: retrieves evidence (evidence: `mediq/ui/app.py`)
- Streamlit chat UI → Prompt builder: builds prompt (evidence: `mediq/ui/app.py`)
- Streamlit chat UI → LLM client: generates answer (evidence: `mediq/ui/app.py`)
- Streamlit chat UI → Guardrails: checks safety (evidence: `mediq/ui/app.py`)
- Hybrid retriever → FAISS vector store: searches dense (evidence: `mediq/retrieval/hybrid_retriever.py`)
- Hybrid retriever → BM25 index: searches sparse (evidence: `mediq/retrieval/hybrid_retriever.py`)
- Hybrid retriever → Prompt builder: returns ranked chunks
- LLM client → OpenAI API: calls model (evidence: `mediq/generation/llm_client.py`)
- Evaluation runner → Hybrid retriever: evaluates retrieval (evidence: `mediq/evaluation/eval_runner.py`)
- Evaluation runner → Prompt builder: builds test prompts (evidence: `mediq/evaluation/eval_runner.py`)
- Evaluation runner → LLM client: generates test answers (evidence: `mediq/evaluation/eval_runner.py`)
- Evaluation runner → Guardrails: checks scope (evidence: `mediq/evaluation/eval_runner.py`)
- Evaluation runner → Evaluation scorers: scores results (evidence: `mediq/evaluation/eval_runner.py`)
- Evaluation runner → Golden dataset: reads test cases
