# varshith999/hms architecture

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

- Interactive diagram: https://gitdiagram.com/varshith999/hms
- Repository: https://github.com/varshith999/hms

## Overview

Clinical Graph RAG is a FastAPI healthcare discovery and receptionist service. The main workflow accepts a patient message, extracts basic demographics, embeds the full message, searches Neo4j for disease-linked clinical cases and doctors, then uses an LLM to compose a patient-facing explanation and disclaimer. Separate API routes validate and ingest batches, seed from bundled synthetic records, or reset and reseed the graph. The graph follows documented capabilities and sampled call ownership; request-time symptom extraction currently returns an empty list.

Main entry points: [`backend/app/main.py`](https://github.com/varshith999/hms/blob/main/backend/app/main.py) (FastAPI Gateway), [`backend/app/recommendation.py`](https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py) (RAG Orchestrator), [`backend/app/database.py`](https://github.com/varshith999/hms/blob/main/backend/app/database.py) (Neo4j Graph Service), [`backend/app/ingestion.py`](https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py) (Ingestion Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_gateway["FastAPI Gateway<br/>[main.py]"]
  node_schemas["Request And Response Models<br/>[models.py]"]
  node_health["Health Check<br/>[main.py]"]
end

subgraph group_rag["Recommendation"]
  node_orchestrator["RAG Orchestrator<br/>[recommendation.py]"]
  node_entity_extraction["Entity Extraction<br/>[recommendation.py]"]
  node_match_scoring["Doctor Scoring<br/>[recommendation.py]"]
end

subgraph group_ingest["Data Ingestion"]
  node_ingestion_engine["Ingestion Engine<br/>[ingestion.py]"]
  node_validation["Record Validation<br/>[ingestion.py]"]
  node_seed_records["Synthetic Patient Records<br/>[patients.json]"]
  node_ingestion_embeddings["Disease Embeddings<br/>[ingestion.py]"]
end

subgraph group_services["AI And Graph"]
  node_llm["LLM And Embeddings<br/>[llm.py]"]
  node_graph_service["Neo4j Graph Service<br/>[database.py]"]
end

node_client(("API Client"))
node_provider{{"OpenAI Or OpenRouter"}}
node_neo4j[("Neo4j AuraDB")]

node_client -->|"sends request"| node_gateway
node_gateway -->|"validates against"| node_schemas
node_gateway -->|"dispatches recommendation"| node_orchestrator
node_orchestrator -->|"extracts demographics"| node_entity_extraction
node_orchestrator -->|"embeds message"| node_llm
node_llm -.->|"requests embedding"| node_provider
node_orchestrator -->|"queries recommendations"| node_graph_service
node_graph_service -->|"searches graph"| node_neo4j
node_orchestrator -->|"scores matches"| node_match_scoring
node_orchestrator -->|"requests explanation"| node_llm
node_llm -.->|"requests completion"| node_provider
node_orchestrator -->|"returns recommendation"| node_gateway
node_gateway -->|"returns response"| node_client
node_gateway -->|"dispatches ingestion"| node_ingestion_engine
node_ingestion_engine -->|"validates records"| node_validation
node_validation -->|"returns normalized records"| node_ingestion_engine
node_ingestion_engine -->|"writes patient records"| node_graph_service
node_ingestion_engine -->|"generates disease vectors"| node_ingestion_embeddings
node_ingestion_embeddings -->|"requests embeddings"| node_llm
node_ingestion_embeddings -->|"stores disease vectors"| node_graph_service
node_ingestion_engine -->|"reads seed data"| node_seed_records
node_gateway -->|"dispatches health check"| node_health
node_health -->|"checks connectivity"| node_graph_service
node_graph_service -->|"verifies connection"| node_neo4j
node_gateway -->|"initializes schema"| node_graph_service

click node_gateway "https://github.com/varshith999/hms/blob/main/backend/app/main.py"
click node_schemas "https://github.com/varshith999/hms/blob/main/backend/app/models.py"
click node_orchestrator "https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py"
click node_entity_extraction "https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py"
click node_match_scoring "https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py"
click node_llm "https://github.com/varshith999/hms/blob/main/backend/app/llm.py"
click node_graph_service "https://github.com/varshith999/hms/blob/main/backend/app/database.py"
click node_ingestion_engine "https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py"
click node_validation "https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py"
click node_seed_records "https://github.com/varshith999/hms/blob/main/backend/synthetic_data/patients.json"
click node_ingestion_embeddings "https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py"
click node_health "https://github.com/varshith999/hms/blob/main/backend/app/main.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_gateway,node_schemas,node_health,node_client toneBlue
class node_orchestrator,node_entity_extraction,node_match_scoring,node_neo4j toneAmber
class node_ingestion_engine,node_validation,node_seed_records,node_ingestion_embeddings,node_provider toneMint
class node_llm,node_graph_service toneRose
```

## Components

### API

- [FastAPI Gateway](https://github.com/varshith999/hms/blob/main/backend/app/main.py): `backend/app/main.py`
- [Request And Response Models](https://github.com/varshith999/hms/blob/main/backend/app/models.py): `backend/app/models.py`
- [Health Check](https://github.com/varshith999/hms/blob/main/backend/app/main.py): `backend/app/main.py`

### Recommendation

- [RAG Orchestrator](https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py): `backend/app/recommendation.py`
- [Entity Extraction](https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py): `backend/app/recommendation.py`
- [Doctor Scoring](https://github.com/varshith999/hms/blob/main/backend/app/recommendation.py): `backend/app/recommendation.py`

### Data Ingestion

- [Ingestion Engine](https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py): `backend/app/ingestion.py`
- [Record Validation](https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py): `backend/app/ingestion.py`
- [Synthetic Patient Records](https://github.com/varshith999/hms/blob/main/backend/synthetic_data/patients.json): `backend/synthetic_data/patients.json`
- [Disease Embeddings](https://github.com/varshith999/hms/blob/main/backend/app/ingestion.py): `backend/app/ingestion.py`

### AI And Graph

- [LLM And Embeddings](https://github.com/varshith999/hms/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Neo4j Graph Service](https://github.com/varshith999/hms/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **API Client**
- **OpenAI Or OpenRouter**
- **Neo4j AuraDB**

## Connections

- API Client → FastAPI Gateway: sends request
- FastAPI Gateway → Request And Response Models: validates against
- FastAPI Gateway → RAG Orchestrator: dispatches recommendation
- RAG Orchestrator → Entity Extraction: extracts demographics
- RAG Orchestrator → LLM And Embeddings: embeds message
- LLM And Embeddings → OpenAI Or OpenRouter: requests embedding
- RAG Orchestrator → Neo4j Graph Service: queries recommendations
- Neo4j Graph Service → Neo4j AuraDB: searches graph
- RAG Orchestrator → Doctor Scoring: scores matches
- RAG Orchestrator → LLM And Embeddings: requests explanation
- LLM And Embeddings → OpenAI Or OpenRouter: requests completion
- RAG Orchestrator → FastAPI Gateway: returns recommendation
- FastAPI Gateway → API Client: returns response
- FastAPI Gateway → Ingestion Engine: dispatches ingestion
- Ingestion Engine → Record Validation: validates records
- Record Validation → Ingestion Engine: returns normalized records
- Ingestion Engine → Neo4j Graph Service: writes patient records
- Ingestion Engine → Disease Embeddings: generates disease vectors
- Disease Embeddings → LLM And Embeddings: requests embeddings
- Disease Embeddings → Neo4j Graph Service: stores disease vectors
- Ingestion Engine → Synthetic Patient Records: reads seed data
- FastAPI Gateway → Health Check: dispatches health check
- Health Check → Neo4j Graph Service: checks connectivity
- Neo4j Graph Service → Neo4j AuraDB: verifies connection
- FastAPI Gateway → Neo4j Graph Service: initializes schema