# hastimal/gemini-healthcare-agentic-platform architecture

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

- Interactive diagram: https://gitdiagram.com/hastimal/gemini-healthcare-agentic-platform
- Repository: https://github.com/hastimal/gemini-healthcare-agentic-platform

## Overview

This is an agentic healthcare research and discovery platform. A user question is planned into searches, handled by research agents and MCP-backed healthcare sources, then ranked and turned into an evidence-grounded answer with citations and limitations. The graph also preserves the documented model-portability and evaluation capabilities. Most agent and grounding implementations were not sampled, so workflow links below rely on the README’s explicit architecture; unsampled internals are represented at their exact directory paths.

Main entry points: [`agents/workflows/healthcare_workflow.py`](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/workflows/healthcare_workflow.py) (Healthcare workflow), [`mcp_services/clients/healthcare.py`](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/clients/healthcare.py) (Healthcare MCP client), [`agents/healthcare_research/agent.py`](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/healthcare_research/agent.py) (Healthcare Research Agent), [`llm/model_factory.py`](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/llm/model_factory.py) (Gemini and Gemma)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_streamlit["Research demo<br/>[streamlit_app.py]"]
end

subgraph group_agents["Agent Workflow"]
  node_planner["Search Planner Agent<br/>[agent.py]"]
  node_fanout["Query fan-out<br/>[query_fanout.py]"]
  node_research["Healthcare Research Agent<br/>[agent.py]"]
  node_workflow["Healthcare workflow"]
end

subgraph group_retrieval["Search and Evidence"]
  node_mcphealth["Healthcare MCP client<br/>[healthcare.py]"]
  node_searchmcp["Search MCP tools<br/>[tools.py]"]
  node_pubmedmcp["Research MCP tools<br/>[tools.py]"]
  node_fhirserver["FHIR MCP tools<br/>[tools.py]"]
  node_provider["NPPES provider search<br/>[client.py]"]
  node_pubmed["PubMed search<br/>[client.py]"]
  node_fhir["FHIR R4 connector<br/>[client.py]"]
  node_searchresults["Evidence retrieval<br/>[retrieval.py]"]
end

subgraph group_answer["Grounded Answering"]
  node_ranking["Evidence ranking<br/>[ranking.py]"]
  node_answeragent["Evidence &amp; Answer Agent<br/>[agent.py]"]
  node_grounding["Grounded synthesis<br/>[answering.py]"]
  node_citations["Citations<br/>[citations.py]"]
end

subgraph group_platform["Models and Evaluation"]
  node_gemini["Gemini and Gemma<br/>[model_factory.py]"]
  node_evaluation["Deterministic evaluation<br/>[orchestrator.py]"]
  node_evalmetrics["Evaluation metrics"]
  node_reports["Evaluation reports<br/>[reporting.py]"]
end

node_user(("Healthcare user"))
node_result["Cited recommendations"]
node_externaldata(("Healthcare data services"))

node_user -->|"asks question"| node_streamlit
node_streamlit -->|"starts workflow"| node_workflow
node_workflow -->|"runs first"| node_planner
node_planner -->|"builds search plan"| node_fanout
node_workflow -->|"runs research"| node_research
node_research -->|"uses MCP retrieval"| node_mcphealth
node_mcphealth -.->|"dispatches search"| node_searchmcp
node_mcphealth -.->|"dispatches research"| node_pubmedmcp
node_mcphealth -.->|"dispatches FHIR"| node_fhirserver
node_searchmcp -.->|"retrieves providers"| node_provider
node_pubmedmcp -.->|"retrieves literature"| node_pubmed
node_fhirserver -->|"delegates searches"| node_fhir
node_provider -->|"queries NPPES"| node_externaldata
node_pubmed -->|"queries PubMed"| node_externaldata
node_fhir -->|"queries FHIR endpoint"| node_externaldata
node_research -.->|"retrieves evidence"| node_searchresults
node_workflow -->|"ranks evidence"| node_ranking
node_workflow -->|"invokes answer agent"| node_answeragent
node_answeragent -->|"grounds response"| node_grounding
node_grounding -->|"adds citations"| node_citations
node_grounding -->|"returns recommendations"| node_result
node_gemini -->|"powers agent"| node_planner
node_gemini -->|"powers agent"| node_research
node_gemini -->|"powers agent"| node_answeragent
node_workflow -->|"evaluated by"| node_evaluation
node_evaluation -->|"computes checks"| node_evalmetrics
node_evaluation -->|"produces results"| node_reports

click node_streamlit "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/ui/streamlit_app.py"
click node_planner "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/search_planner/agent.py"
click node_fanout "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/search/query_fanout.py"
click node_research "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/healthcare_research/agent.py"
click node_workflow "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/workflows/healthcare_workflow.py"
click node_mcphealth "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/clients/healthcare.py"
click node_searchmcp "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/search_server/tools.py"
click node_pubmedmcp "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/research_server/tools.py"
click node_fhirserver "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/fhir_server/tools.py"
click node_provider "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/connectors/provider_search/client.py"
click node_pubmed "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/connectors/pubmed/client.py"
click node_fhir "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/connectors/fhir/client.py"
click node_searchresults "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/search/retrieval.py"
click node_ranking "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/grounding/ranking.py"
click node_answeragent "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/evidence_answer/agent.py"
click node_grounding "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/grounding/answering.py"
click node_citations "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/grounding/citations.py"
click node_gemini "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/llm/model_factory.py"
click node_evaluation "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/evaluation/orchestrator.py"
click node_evalmetrics "https://github.com/hastimal/gemini-healthcare-agentic-platform/tree/main/evaluation/metrics"
click node_reports "https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/evaluation/reporting.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_streamlit,node_user toneBlue
class node_planner,node_fanout,node_research,node_workflow toneAmber
class node_mcphealth,node_searchmcp,node_pubmedmcp,node_fhirserver,node_provider,node_pubmed,node_fhir,node_searchresults toneMint
class node_ranking,node_answeragent,node_grounding,node_citations toneRose
class node_gemini,node_evaluation,node_evalmetrics,node_reports,node_result,node_externaldata toneIndigo
```

## Components

### User Experience

- [Research demo](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/ui/streamlit_app.py): `ui/streamlit_app.py`

### Agent Workflow

- [Search Planner Agent](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/search_planner/agent.py): `agents/search_planner/agent.py`
- [Query fan-out](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/search/query_fanout.py): `search/query_fanout.py`
- [Healthcare Research Agent](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/healthcare_research/agent.py): `agents/healthcare_research/agent.py`
- [Healthcare workflow](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/workflows/healthcare_workflow.py): `agents/workflows/healthcare_workflow.py`

### Search and Evidence

- [Healthcare MCP client](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/clients/healthcare.py): `mcp_services/clients/healthcare.py`
- [Search MCP tools](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/search_server/tools.py): `mcp_services/search_server/tools.py`
- [Research MCP tools](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/research_server/tools.py): `mcp_services/research_server/tools.py`
- [FHIR MCP tools](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/mcp_services/fhir_server/tools.py): `mcp_services/fhir_server/tools.py`
- [NPPES provider search](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/connectors/provider_search/client.py): `connectors/provider_search/client.py`
- [PubMed search](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/connectors/pubmed/client.py): `connectors/pubmed/client.py`
- [FHIR R4 connector](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/connectors/fhir/client.py): `connectors/fhir/client.py`
- [Evidence retrieval](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/search/retrieval.py): `search/retrieval.py`

### Grounded Answering

- [Evidence ranking](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/grounding/ranking.py): `grounding/ranking.py`
- [Evidence & Answer Agent](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/agents/evidence_answer/agent.py): `agents/evidence_answer/agent.py`
- [Grounded synthesis](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/grounding/answering.py): `grounding/answering.py`
- [Citations](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/grounding/citations.py): `grounding/citations.py`

### Models and Evaluation

- [Gemini and Gemma](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/llm/model_factory.py): `llm/model_factory.py`
- [Deterministic evaluation](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/evaluation/orchestrator.py): `evaluation/orchestrator.py`
- [Evaluation metrics](https://github.com/hastimal/gemini-healthcare-agentic-platform/tree/main/evaluation/metrics): `evaluation/metrics`
- [Evaluation reports](https://github.com/hastimal/gemini-healthcare-agentic-platform/blob/main/evaluation/reporting.py): `evaluation/reporting.py`

### Other components

- **Healthcare user**
- **Cited recommendations**
- **Healthcare data services**

## Connections

- Healthcare user → Research demo: asks question
- Research demo → Healthcare workflow: starts workflow
- Healthcare workflow → Search Planner Agent: runs first
- Search Planner Agent → Query fan-out: builds search plan (evidence: `search/query_fanout.py`)
- Healthcare workflow → Healthcare Research Agent: runs research
- Healthcare Research Agent → Healthcare MCP client: uses MCP retrieval
- Healthcare MCP client → Search MCP tools: dispatches search
- Healthcare MCP client → Research MCP tools: dispatches research
- Healthcare MCP client → FHIR MCP tools: dispatches FHIR
- Search MCP tools → NPPES provider search: retrieves providers
- Research MCP tools → PubMed search: retrieves literature
- FHIR MCP tools → FHIR R4 connector: delegates searches
- NPPES provider search → Healthcare data services: queries NPPES (evidence: `connectors/provider_search/client.py`)
- PubMed search → Healthcare data services: queries PubMed (evidence: `connectors/pubmed/client.py`)
- FHIR R4 connector → Healthcare data services: queries FHIR endpoint (evidence: `connectors/fhir/client.py`)
- Healthcare Research Agent → Evidence retrieval: retrieves evidence
- Healthcare workflow → Evidence ranking: ranks evidence
- Healthcare workflow → Evidence & Answer Agent: invokes answer agent
- Evidence & Answer Agent → Grounded synthesis: grounds response
- Grounded synthesis → Citations: adds citations
- Grounded synthesis → Cited recommendations: returns recommendations
- Gemini and Gemma → Search Planner Agent: powers agent
- Gemini and Gemma → Healthcare Research Agent: powers agent
- Gemini and Gemma → Evidence & Answer Agent: powers agent
- Healthcare workflow → Deterministic evaluation: evaluated by
- Deterministic evaluation → Evaluation metrics: computes checks
- Deterministic evaluation → Evaluation reports: produces results