# abdelrahmanmostafa33/healthcare-rag-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/abdelrahmanmostafa33/healthcare-rag-assistant
- Repository: https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant

## Overview

Healthcare RAG Assistant is an education-only web/API product: a user submits a health question, the shared pipeline applies safety and evidence checks, searches local health-source passages, then generates a cited answer or abstains. Supporting branches build and calibrate the local knowledge base and evaluate retrieval, answers, citations, and safety behavior. The excerpts show core runtime calls; the README documents major capabilities such as source ingestion and evaluation that are not fully sampled. The UI-to-API wiring and some pipeline details are not shown, so uncertain links are omitted.

Main entry points: [`src/pipeline.py`](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/pipeline.py) (RAG pipeline), [`src/provider_clients.py`](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/provider_clients.py) (Provider client setup), [`src/evaluation.py`](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/evaluation.py) (RAG evaluation), [`src/safety_check.py`](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/safety_check.py) (Safety triage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web interface"]
  node_api["Web API<br/>[app.py]"]
end

subgraph group_answering["Question answering"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_rules["Local safety rules<br/>[safety.py]"]
  node_triage["Safety triage<br/>[safety_check.py]"]
  node_retriever["Search and rerank<br/>[retriever.py]"]
  node_generator["Grounded generation<br/>[generator.py]"]
end

subgraph group_knowledge["Knowledge and calibration"]
  node_calibration["Evidence calibration<br/>[calibration.py]"]
  node_kb["Source processing and indexing<br/>[kb.py]"]
  node_index[("Local search index")]
  node_threshold["Calibrated cutoff"]
end

subgraph group_operations["Evaluation and providers"]
  node_evaluation["RAG evaluation<br/>[evaluation.py]"]
  node_metrics["Quality metrics<br/>[metrics.py]"]
  node_evaldata["Evaluation questions"]
end

subgraph group_shared["Shared runtime"]
  node_providers["Provider client setup"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_deadline["Request deadline<br/>[deadline.py]"]
  node_retry["Provider retries<br/>[retry.py]"]
end

node_user(("Question asker"))
node_health_sources["Health-source material"]
node_gemini["Gemini services"]
node_judge["LLM judge providers"]

node_user -->|"asks"| node_web
node_api -->|"runs"| node_pipeline
node_pipeline -->|"checks rules"| node_rules
node_pipeline -->|"triages unmatched"| node_triage
node_pipeline -->|"retrieves passages"| node_retriever
node_pipeline -->|"generates answer"| node_generator
node_retriever -->|"loads index"| node_kb
node_kb -->|"builds and loads"| node_index
node_health_sources -->|"provides source text"| node_kb
node_calibration -->|"scores questions"| node_retriever
node_calibration -->|"saves cutoff"| node_threshold
node_config -->|"validates cutoff"| node_threshold
node_pipeline -->|"checks calibration"| node_config
node_pipeline -->|"checks budget"| node_deadline
node_generator -->|"creates client"| node_providers
node_triage -->|"creates client"| node_providers
node_generator -->|"retries failures"| node_retry
node_triage -->|"retries failures"| node_retry
node_providers -->|"connects"| node_gemini
node_evaluation -->|"evaluates behavior"| node_pipeline
node_evaluation -->|"computes scores"| node_metrics
node_evaldata -->|"supplies questions"| node_evaluation
node_evaluation -->|"creates judge client"| node_providers
node_providers -.->|"connects optionally"| node_judge

click node_web "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/frontend"
click node_api "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/app.py"
click node_pipeline "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/pipeline.py"
click node_rules "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/safety.py"
click node_triage "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/safety_check.py"
click node_retriever "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/retriever.py"
click node_generator "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/generator.py"
click node_calibration "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/calibration.py"
click node_kb "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/kb.py"
click node_index "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/data/index"
click node_threshold "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/data/index"
click node_evaluation "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/evaluation.py"
click node_metrics "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/metrics.py"
click node_evaldata "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/data/eval"
click node_providers "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/provider_clients.py"
click node_config "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/config.py"
click node_deadline "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/deadline.py"
click node_retry "https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/retry.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_web,node_api toneBlue
class node_pipeline,node_rules,node_triage,node_retriever,node_generator toneAmber
class node_calibration,node_kb,node_index,node_threshold toneMint
class node_evaluation,node_metrics,node_evaldata toneRose
class node_providers,node_config,node_deadline,node_retry,node_user,node_health_sources,node_gemini,node_judge toneIndigo
```

## Components

### User experience

- [Web interface](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/frontend): `frontend`
- [Web API](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/app.py): `app.py`

### Question answering

- [RAG pipeline](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/pipeline.py): `src/pipeline.py`
- [Local safety rules](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/safety.py): `src/safety.py`
- [Safety triage](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/safety_check.py): `src/safety_check.py`
- [Search and rerank](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/retriever.py): `src/retriever.py`
- [Grounded generation](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/generator.py): `src/generator.py`

### Knowledge and calibration

- [Evidence calibration](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/calibration.py): `src/calibration.py`
- [Source processing and indexing](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/kb.py): `src/kb.py`
- [Local search index](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/data/index): `data/index`
- [Calibrated cutoff](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/data/index): `data/index`

### Evaluation and providers

- [RAG evaluation](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/evaluation.py): `src/evaluation.py`
- [Quality metrics](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/metrics.py): `src/metrics.py`
- [Evaluation questions](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/tree/main/data/eval): `data/eval`

### Shared runtime

- [Provider client setup](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/provider_clients.py): `src/provider_clients.py`
- [Runtime configuration](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/config.py): `src/config.py`
- [Request deadline](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/deadline.py): `src/deadline.py`
- [Provider retries](https://github.com/abdelrahmanmostafa33/healthcare-rag-assistant/blob/main/src/retry.py): `src/retry.py`

### Other components

- **Question asker**
- **Health-source material**
- **Gemini services**
- **LLM judge providers**

## Connections

- Question asker → Web interface: asks (evidence: `README.md`)
- Web API → RAG pipeline: runs (evidence: `app.py`)
- RAG pipeline → Local safety rules: checks rules (evidence: `src/pipeline.py`)
- RAG pipeline → Safety triage: triages unmatched (evidence: `src/pipeline.py`)
- RAG pipeline → Search and rerank: retrieves passages (evidence: `src/pipeline.py`)
- RAG pipeline → Grounded generation: generates answer (evidence: `README.md`)
- Search and rerank → Source processing and indexing: loads index (evidence: `src/retriever.py`)
- Source processing and indexing → Local search index: builds and loads (evidence: `README.md`)
- Health-source material → Source processing and indexing: provides source text (evidence: `README.md`)
- Evidence calibration → Search and rerank: scores questions (evidence: `src/calibration.py`)
- Evidence calibration → Calibrated cutoff: saves cutoff (evidence: `README.md`)
- Runtime configuration → Calibrated cutoff: validates cutoff (evidence: `src/config.py`)
- RAG pipeline → Runtime configuration: checks calibration (evidence: `src/pipeline.py`)
- RAG pipeline → Request deadline: checks budget (evidence: `src/pipeline.py`)
- Grounded generation → Provider client setup: creates client (evidence: `src/generator.py`)
- Safety triage → Provider client setup: creates client (evidence: `src/safety_check.py`)
- Grounded generation → Provider retries: retries failures (evidence: `src/generator.py`)
- Safety triage → Provider retries: retries failures (evidence: `src/safety_check.py`)
- Provider client setup → Gemini services: connects (evidence: `src/provider_clients.py`)
- RAG evaluation → RAG pipeline: evaluates behavior (evidence: `src/evaluation.py`)
- RAG evaluation → Quality metrics: computes scores (evidence: `src/metrics.py`)
- Evaluation questions → RAG evaluation: supplies questions (evidence: `README.md`)
- RAG evaluation → Provider client setup: creates judge client (evidence: `src/evaluation.py`)
- Provider client setup → LLM judge providers: connects optionally (evidence: `src/provider_clients.py`)
