# rohit-p27/healthcare-ai-india architecture

> Architecture diagram of the GitHub repository rohit-p27/healthcare-ai-india, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohit-p27/healthcare-ai-india
- Repository: https://github.com/rohit-p27/healthcare-ai-india

## Overview

#### Purpose and Entry Points
AI Sarthi is an India-focused healthcare-governance intelligence platform: operational data, analytics, RAG, and agent workflows support budget, epidemic, supply, insurance, geographic, and district analysis. Runtime entry points are the FastAPI backend at `core_platform/backend/main.py` (with application setup in `core_platform/backend/app/main.py`), Next.js UI under `core_platform/frontend/app`, and CLI-oriented ETL/RAG packages via `core_platform/etl/__main__.py` and `core_platform/rag/__main__.py`.

#### User Interface and API Boundary
The Next.js/TypeScript frontend presents dashboards, geographic drilldowns, domain screens, and an AI copilot/query experience. Shared API access is centralized in `core_platform/frontend/lib/api.ts`; app routes include `core_platform/frontend/app/ask/page.tsx`, `core_platform/frontend/app/districts/page.tsx`, and `core_platform/frontend/app/knowledge-graph/page.tsx`. It communicates with versioned FastAPI routes rather than accessing data stores directly.

#### Backend Domain Services
FastAPI route handlers define the external contract and delegate domain logic to service modules. The central route composition is `core_platform/backend/api/v1/router.py`; representative boundaries are chat/orchestration (`core_platform/backend/api/v1/chat.py`, `core_platform/backend/api/v1/orchestrator.py`), RAG (`core_platform/backend/api/v1/rag.py`), and analytical domains such as budget, epidemic, insurance, supply, district, and geo. Services own application-level queries and calculations, e.g. `core_platform/backend/services/budget_service.py`, `core_platform/backend/services/epidemic_service.py`, and `core_platform/backend/services/rag_service.py`.

#### Persistent Data and Governance Model
The backend separates ORM persistence models from request/response schemas: `core_platform/backend/models` covers health, governance, coordination, geo, RAG, and analytic domains, while `core_platform/backend/schemas` is the API serialization boundary. Database initialization/session handling lives in `core_platform/backend/db/session.py`; Alembic migrations establish core schemas, district-profile fields, and pgvector support in `core_platform/backend/alembic/versions/0001_create_schemas_and_core_tables.py` through `0003_rag_pgvector.py`. SQLite database files are present for development; the intended production relational/vector target is PostgreSQL with pgvector.

#### Data Ingestion and Curated Marts
ETL converts source health/governance data into normalized, validated data products. The CLI orchestrates pipelines from `core_platform/etl/cli.py`; shared ingestion and normalization are in `core_platform/etl/common/ingestor.py` and `core_platform/etl/common/normalize.py`. Geographic identity is a cross-domain join boundary via `core_platform/etl/transform/geo_spine.py`; district profiles derive from it in `core_platform/etl/transform/district_profile.py`. Curated Parquet marts in `datasets/curated/mart_geo_spine_v1/data.parquet` and `datasets/curated/mart_district_profile_v1/data.parquet` feed operational loading and analytics.

#### AI, RAG, and Agent Control Flow
Natural-language requests enter API chat/orchestration, then the agentic gateway and orchestrator select specialized budget, epidemic, insurance, policy, research, or supply agents. Coordination and memory abstractions are in `core_platform/agents/core/orchestrator.py`, `core_platform/agents/core/memory.py`, and `core_platform/agents/workflows/agentic_gateway.py`. RAG ingestion loads documents, chunks, embeds, and indexes them; retrieval performs hybrid search, reranking, context construction, and citations via `core_platform/rag/indexing/embedder.py`, `core_platform/rag/retrieval/pipeline.py`, and `core_platform/rag/retrieval/hybrid_search.py`. The repository also contains Neo4j-oriented graph integration at `core_platform/knowledge_graph/connector.py` and ontology definitions at `core_platform/knowledge_graph/ontology.py`.

#### Analytics and Model Operations
Domain APIs/services expose predictive and anomaly-oriented functions described by the platform: epidemic detection, budget forecasting, and insurance analysis. MLOps primitives for features, registry, monitoring, and serving are isolated in `core_platform/mlops/feature_store.py`, `core_platform/mlops/registry.py`, and `core_platform/mlops/serving.py`. Healthcare SLM training assets are separate from serving infrastructure under `healthcare_slm/training`, including `healthcare_slm/training/llm/finetune_qlora.py`.

#### Deployment and External Dependencies
The main material runtimes are Python/FastAPI, Node.js/Next.js, PostgreSQL/pgvector, and optionally Neo4j for GraphRAG. Docker deployment artifacts are `deployment/Dockerfile.backend`, `deployment/Dockerfile.frontend`, and `deployment/docker-compose.yml`. External knowledge inputs are local policy, budget, and health PDFs/CSVs under `data/raw`; embedding/vector artifacts also exist in `vector_store/chroma.sqlite3`, indicating a local Chroma-style development vector store alongside the PostgreSQL vector migration path.

Main entry points: [`core_platform/backend/api/v1/router.py`](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/api/v1/router.py) (Versioned route contract), [`core_platform/agents/core/orchestrator.py`](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/agents/core/orchestrator.py) (Agent orchestration & memory), [`core_platform/backend/services/budget_service.py`](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/services/budget_service.py) (Domain services), [`core_platform/backend/db/session.py`](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/db/session.py) (PostgreSQL + pgvector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Experience"]
  node_frontend["Next.js dashboards &amp; copilot<br/>Next.js UI"]
  node_frontend_api["API client<br/>TypeScript client<br/>[api.ts]"]
end

subgraph group_api["Platform API"]
  node_fastapi_entry["FastAPI application<br/>Python API<br/>[main.py]"]
  node_v1_routes["Versioned route contract<br/>FastAPI router<br/>[router.py]"]
  node_domain_services["Domain services<br/>application services<br/>[budget_service.py]"]
  node_api_schemas["API schemas<br/>serialization boundary"]
  node_orm_models["ORM domain models<br/>persistence models"]
end

subgraph group_intelligence["Data &amp; AI Pipelines"]
  node_agent_gateway{{"Agent gateway<br/>agent workflow<br/>[agentic_gateway.py]"}}
  node_agent_orchestrator["Agent orchestration &amp; memory<br/>agent control<br/>[orchestrator.py]"]
  node_rag_retrieval["Hybrid RAG retrieval<br/>retrieval pipeline<br/>[pipeline.py]"]
  node_rag_embedding["RAG embedding &amp; indexing<br/>indexing pipeline<br/>[embedder.py]"]
  node_etl_cli["ETL orchestration<br/>CLI pipeline<br/>[cli.py]"]
  node_geo_spine["Geographic identity spine<br/>ETL transform<br/>[geo_spine.py]"]
  node_district_profiles["District profile mart<br/>curated Parquet<br/>[data.parquet]"]
  node_mlops_serving["Model serving<br/>MLOps serving<br/>[serving.py]"]
end

subgraph group_storage["Data Stores"]
  node_postgres[("PostgreSQL + pgvector<br/>relational/vector store<br/>[session.py]")]
  node_chroma[("Local Chroma vector store<br/>development vector store<br/>[chroma.sqlite3]")]
  node_neo4j[("Neo4j knowledge graph<br/>GraphRAG integration<br/>[connector.py]")]
  node_raw_sources["Policy, budget &amp; health sources<br/>raw files"]
end

node_frontend -->|"uses"| node_frontend_api
node_frontend_api -->|"versioned HTTP API"| node_fastapi_entry
node_fastapi_entry -->|"mounts"| node_v1_routes
node_v1_routes -->|"serializes"| node_api_schemas
node_v1_routes -->|"delegates"| node_domain_services
node_domain_services -->|"queries"| node_orm_models
node_orm_models -->|"persists"| node_postgres
node_v1_routes -->|"chat and orchestration"| node_agent_gateway
node_agent_gateway -->|"coordinates"| node_agent_orchestrator
node_agent_orchestrator -->|"requests evidence"| node_rag_retrieval
node_rag_retrieval -->|"searches vectors"| node_postgres
node_rag_retrieval -.->|"development retrieval"| node_chroma
node_agent_orchestrator -->|"uses domain analysis"| node_domain_services
node_domain_services -->|"invokes models"| node_mlops_serving
node_agent_orchestrator -.->|"optional GraphRAG"| node_neo4j
node_raw_sources -->|"ingests"| node_etl_cli
node_etl_cli -->|"normalizes and joins"| node_geo_spine
node_geo_spine -->|"derives"| node_district_profiles
node_district_profiles -->|"operational loading"| node_postgres
node_raw_sources -->|"documents"| node_rag_embedding
node_rag_embedding -->|"indexes embeddings"| node_postgres
node_rag_embedding -.->|"local index"| node_chroma

click node_frontend "https://github.com/rohit-p27/healthcare-ai-india/tree/main/core_platform/frontend/app"
click node_frontend_api "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/frontend/lib/api.ts"
click node_fastapi_entry "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/main.py"
click node_v1_routes "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/api/v1/router.py"
click node_domain_services "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/services/budget_service.py"
click node_api_schemas "https://github.com/rohit-p27/healthcare-ai-india/tree/main/core_platform/backend/schemas"
click node_orm_models "https://github.com/rohit-p27/healthcare-ai-india/tree/main/core_platform/backend/models"
click node_agent_gateway "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/agents/workflows/agentic_gateway.py"
click node_agent_orchestrator "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/agents/core/orchestrator.py"
click node_rag_retrieval "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/rag/retrieval/pipeline.py"
click node_rag_embedding "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/rag/indexing/embedder.py"
click node_etl_cli "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/etl/cli.py"
click node_geo_spine "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/etl/transform/geo_spine.py"
click node_district_profiles "https://github.com/rohit-p27/healthcare-ai-india/blob/main/datasets/curated/mart_district_profile_v1/data.parquet"
click node_mlops_serving "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/mlops/serving.py"
click node_postgres "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/db/session.py"
click node_chroma "https://github.com/rohit-p27/healthcare-ai-india/blob/main/vector_store/chroma.sqlite3"
click node_neo4j "https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/knowledge_graph/connector.py"
click node_raw_sources "https://github.com/rohit-p27/healthcare-ai-india/tree/main/data/raw"

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_frontend,node_frontend_api toneBlue
class node_fastapi_entry,node_v1_routes,node_domain_services,node_api_schemas,node_orm_models toneAmber
class node_agent_gateway,node_agent_orchestrator,node_rag_retrieval,node_rag_embedding,node_etl_cli,node_geo_spine,node_district_profiles,node_mlops_serving toneMint
class node_postgres,node_chroma,node_neo4j,node_raw_sources toneRose
```

## Components

### User Experience

- [Next.js dashboards & copilot](https://github.com/rohit-p27/healthcare-ai-india/tree/main/core_platform/frontend/app): Next.js UI · Domain dashboards, drilldowns, and AI query screens. · `core_platform/frontend/app`
- [API client](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/frontend/lib/api.ts): TypeScript client · `core_platform/frontend/lib/api.ts`

### Platform API

- [FastAPI application](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/main.py): Python API · `core_platform/backend/main.py`
- [Versioned route contract](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/api/v1/router.py): FastAPI router · Composes domain, chat, orchestration, and RAG endpoints. · `core_platform/backend/api/v1/router.py`
- [Domain services](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/services/budget_service.py): application services · Budget, epidemic, insurance, supply, district, geo, and RAG logic. · `core_platform/backend/services/budget_service.py`
- [API schemas](https://github.com/rohit-p27/healthcare-ai-india/tree/main/core_platform/backend/schemas): serialization boundary · `core_platform/backend/schemas`
- [ORM domain models](https://github.com/rohit-p27/healthcare-ai-india/tree/main/core_platform/backend/models): persistence models · `core_platform/backend/models`

### Data & AI Pipelines

- [Agent gateway](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/agents/workflows/agentic_gateway.py): agent workflow · Routes requests to specialized domain agents. · `core_platform/agents/workflows/agentic_gateway.py`
- [Agent orchestration & memory](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/agents/core/orchestrator.py): agent control · `core_platform/agents/core/orchestrator.py`
- [Hybrid RAG retrieval](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/rag/retrieval/pipeline.py): retrieval pipeline · Hybrid search, reranking, context assembly, and citations. · `core_platform/rag/retrieval/pipeline.py`
- [RAG embedding & indexing](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/rag/indexing/embedder.py): indexing pipeline · `core_platform/rag/indexing/embedder.py`
- [ETL orchestration](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/etl/cli.py): CLI pipeline · `core_platform/etl/cli.py`
- [Geographic identity spine](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/etl/transform/geo_spine.py): ETL transform · Cross-domain geographic join boundary. · `core_platform/etl/transform/geo_spine.py`
- [District profile mart](https://github.com/rohit-p27/healthcare-ai-india/blob/main/datasets/curated/mart_district_profile_v1/data.parquet): curated Parquet · `datasets/curated/mart_district_profile_v1/data.parquet`
- [Model serving](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/mlops/serving.py): MLOps serving · Serves predictive and anomaly-oriented model functions. · `core_platform/mlops/serving.py`

### Data Stores

- [PostgreSQL + pgvector](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/backend/db/session.py): relational/vector store · Production operational, analytic, and vector persistence target. · `core_platform/backend/db/session.py`
- [Local Chroma vector store](https://github.com/rohit-p27/healthcare-ai-india/blob/main/vector_store/chroma.sqlite3): development vector store · `vector_store/chroma.sqlite3`
- [Neo4j knowledge graph](https://github.com/rohit-p27/healthcare-ai-india/blob/main/core_platform/knowledge_graph/connector.py): GraphRAG integration · Optional graph store backed by ontology definitions. · `core_platform/knowledge_graph/connector.py`
- [Policy, budget & health sources](https://github.com/rohit-p27/healthcare-ai-india/tree/main/data/raw): raw files · `data/raw`

## Connections

- Next.js dashboards & copilot → API client: uses
- API client → FastAPI application: versioned HTTP API
- FastAPI application → Versioned route contract: mounts
- Versioned route contract → API schemas: serializes
- Versioned route contract → Domain services: delegates
- Domain services → ORM domain models: queries
- ORM domain models → PostgreSQL + pgvector: persists
- Versioned route contract → Agent gateway: chat and orchestration
- Agent gateway → Agent orchestration & memory: coordinates
- Agent orchestration & memory → Hybrid RAG retrieval: requests evidence
- Hybrid RAG retrieval → PostgreSQL + pgvector: searches vectors
- Hybrid RAG retrieval → Local Chroma vector store: development retrieval
- Agent orchestration & memory → Domain services: uses domain analysis
- Domain services → Model serving: invokes models
- Agent orchestration & memory → Neo4j knowledge graph: optional GraphRAG
- Policy, budget & health sources → ETL orchestration: ingests
- ETL orchestration → Geographic identity spine: normalizes and joins
- Geographic identity spine → District profile mart: derives
- District profile mart → PostgreSQL + pgvector: operational loading
- Policy, budget & health sources → RAG embedding & indexing: documents
- RAG embedding & indexing → PostgreSQL + pgvector: indexes embeddings
- RAG embedding & indexing → Local Chroma vector store: local index