# jaikumarpaswan/health-navigator architecture

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

- Interactive diagram: https://gitdiagram.com/jaikumarpaswan/health-navigator
- Repository: https://github.com/jaikumarpaswan/health-navigator

## Overview

AI Personal Health Navigator is an India-focused, safety-first health assistant. A user submits a question or lab report through Gradio; the orchestrator applies pre-query safety checks, classifies intent, dispatches specialist work, validates outputs, assembles a response, and saves conversation state. The main domain branches cover symptom analysis and follow-up research, nearby care discovery, government scheme guidance, report explanation, and medication information. Scheme guidance uses an indexed document store; research and care discovery use external services. The graph and README document these capabilities, but several agent implementations and the full UI handler were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`src/orchestrator/graph.py`](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/orchestrator/graph.py) (Health graph), [`src/gateway/litellm_config.py`](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/gateway/litellm_config.py) (LLM gateway), [`src/agents/research_agent.py`](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/research_agent.py) (Medical research), [`src/agents/doctor_finder.py`](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/doctor_finder.py) (Doctor finder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_ui["Gradio chat<br/>[main.py]"]
end

subgraph group_orchestration["Orchestration &amp; Safety"]
  node_graph["Health graph<br/>[graph.py]"]
  node_state["Shared state<br/>[state.py]"]
  node_guardrails["Medical guardrails"]
end

subgraph group_specialists["Health Specialists"]
  node_symptom["Symptom analyst<br/>[symptom_analyst.py]"]
  node_research["Medical research<br/>[research_agent.py]"]
  node_finder["Doctor finder<br/>[doctor_finder.py]"]
  node_scheme["Scheme navigator"]
  node_report["Report explainer"]
  node_medication["Medication info"]
end

subgraph group_knowledge["Knowledge &amp; Memory"]
  node_documents["Health PDFs"]
  node_ingest["PDF ingestion<br/>[ingest.py]"]
  node_vectors[("Scheme index")]
  node_memory[("Session store<br/>[session_store.py]")]
  node_sqlite[("SQLite database")]
end

subgraph group_integrations["External Services"]
  node_gateway["LLM gateway<br/>[litellm_config.py]"]
  node_providers{{"LLM providers"}}
  node_tavily{{"Tavily search"}}
  node_osm{{"OpenStreetMap"}}
end

node_user(("Health seeker"))

node_user -->|"submits query"| node_ui
node_ui -->|"sends interaction"| node_graph
node_graph -->|"updates state"| node_state
node_graph -->|"checks safety"| node_guardrails
node_graph -->|"dispatches intent"| node_symptom
node_graph -->|"dispatches intent"| node_research
node_graph -->|"dispatches intent"| node_finder
node_graph -->|"dispatches intent"| node_scheme
node_graph -->|"dispatches intent"| node_report
node_graph -->|"dispatches intent"| node_medication
node_symptom -->|"requests research"| node_research
node_research -->|"provides care context"| node_finder
node_research -->|"searches sources"| node_tavily
node_finder -->|"queries facilities"| node_osm
node_scheme -->|"retrieves guidance"| node_vectors
node_documents -->|"supplies source PDFs"| node_ingest
node_ingest -->|"builds index"| node_vectors
node_symptom -->|"requests model output"| node_gateway
node_research -->|"requests model output"| node_gateway
node_finder -->|"requests model output"| node_gateway
node_scheme -->|"requests model output"| node_gateway
node_report -->|"requests model output"| node_gateway
node_medication -->|"requests model output"| node_gateway
node_gateway -->|"routes model calls"| node_providers
node_graph -->|"saves session"| node_memory
node_memory -->|"reads and writes"| node_sqlite
node_graph -->|"returns response"| node_ui

click node_ui "https://github.com/jaikumarpaswan/health-navigator/blob/main/app/main.py"
click node_graph "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/orchestrator/graph.py"
click node_state "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/orchestrator/state.py"
click node_guardrails "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/guardrails/medical_guardrails.py"
click node_symptom "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/symptom_analyst.py"
click node_research "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/research_agent.py"
click node_finder "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/doctor_finder.py"
click node_scheme "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/scheme_navigator.py"
click node_report "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/report_explainer.py"
click node_medication "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/medication_agent.py"
click node_gateway "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/gateway/litellm_config.py"
click node_documents "https://github.com/jaikumarpaswan/health-navigator/tree/main/src/data/documents"
click node_ingest "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/rag/ingest.py"
click node_vectors "https://github.com/jaikumarpaswan/health-navigator/tree/main/src/data"
click node_memory "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/memory/session_store.py"
click node_sqlite "https://github.com/jaikumarpaswan/health-navigator/blob/main/src/data/health_navigator.db"

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_ui toneBlue
class node_graph,node_state,node_guardrails toneAmber
class node_symptom,node_research,node_finder,node_scheme,node_report,node_medication toneMint
class node_documents,node_ingest,node_vectors,node_memory,node_sqlite toneRose
class node_gateway,node_providers,node_tavily,node_osm,node_user toneIndigo
```

## Components

### User Experience

- [Gradio chat](https://github.com/jaikumarpaswan/health-navigator/blob/main/app/main.py): `app/main.py`

### Orchestration & Safety

- [Health graph](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/orchestrator/graph.py): `src/orchestrator/graph.py`
- [Shared state](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/orchestrator/state.py): `src/orchestrator/state.py`
- [Medical guardrails](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/guardrails/medical_guardrails.py): `src/guardrails/medical_guardrails.py`

### Health Specialists

- [Symptom analyst](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/symptom_analyst.py): `src/agents/symptom_analyst.py`
- [Medical research](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/research_agent.py): `src/agents/research_agent.py`
- [Doctor finder](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/doctor_finder.py): `src/agents/doctor_finder.py`
- [Scheme navigator](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/scheme_navigator.py): `src/agents/scheme_navigator.py`
- [Report explainer](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/report_explainer.py): `src/agents/report_explainer.py`
- [Medication info](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/agents/medication_agent.py): `src/agents/medication_agent.py`

### Knowledge & Memory

- [Health PDFs](https://github.com/jaikumarpaswan/health-navigator/tree/main/src/data/documents): `src/data/documents`
- [PDF ingestion](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/rag/ingest.py): `src/rag/ingest.py`
- [Scheme index](https://github.com/jaikumarpaswan/health-navigator/tree/main/src/data): `src/data`
- [Session store](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/memory/session_store.py): `src/memory/session_store.py`
- [SQLite database](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/data/health_navigator.db): `src/data/health_navigator.db`

### External Services

- [LLM gateway](https://github.com/jaikumarpaswan/health-navigator/blob/main/src/gateway/litellm_config.py): `src/gateway/litellm_config.py`
- **LLM providers**
- **Tavily search**
- **OpenStreetMap**

### Other components

- **Health seeker**

## Connections

- Health seeker → Gradio chat: submits query
- Gradio chat → Health graph: sends interaction
- Health graph → Shared state: updates state
- Health graph → Medical guardrails: checks safety
- Health graph → Symptom analyst: dispatches intent
- Health graph → Medical research: dispatches intent
- Health graph → Doctor finder: dispatches intent
- Health graph → Scheme navigator: dispatches intent
- Health graph → Report explainer: dispatches intent
- Health graph → Medication info: dispatches intent
- Symptom analyst → Medical research: requests research
- Medical research → Doctor finder: provides care context
- Medical research → Tavily search: searches sources
- Doctor finder → OpenStreetMap: queries facilities
- Scheme navigator → Scheme index: retrieves guidance
- Health PDFs → PDF ingestion: supplies source PDFs
- PDF ingestion → Scheme index: builds index
- Symptom analyst → LLM gateway: requests model output
- Medical research → LLM gateway: requests model output
- Doctor finder → LLM gateway: requests model output
- Scheme navigator → LLM gateway: requests model output
- Report explainer → LLM gateway: requests model output
- Medication info → LLM gateway: requests model output
- LLM gateway → LLM providers: routes model calls
- Health graph → Session store: saves session
- Session store → SQLite database: reads and writes
- Health graph → Gradio chat: returns response