# chandrugiri/healthcare-guide-ai architecture

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

- Interactive diagram: https://gitdiagram.com/chandrugiri/healthcare-guide-ai
- Repository: https://github.com/chandrugiri/healthcare-guide-ai

## Overview

Healthcare Guide AI is a source-grounded conversational healthcare information app. A user submits a question through the Next.js chat; FastAPI routes it to RAG orchestration, which handles greetings and medication-safety requests deterministically or retrieves evidence, generates a grounded answer, and returns backend-controlled citations. The repository also includes a corpus-ingestion path from PDF parsing through chunking, embedding, and vector storage. The README documents these capabilities; edges for unsampled frontend and ingestion internals rely on its descriptions or SOURCE INDEX references.

Main entry points: [`backend/app/scripts/ingest_corpus.py`](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/scripts/ingest_corpus.py) (Corpus ingestion), [`backend/app/api/routes/chat.py`](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/api/routes/chat.py) (Chat endpoint), [`backend/app/services/rag_service.py`](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/rag_service.py) (RAG orchestration), [`backend/app/services/retrieval_service.py`](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/retrieval_service.py) (Semantic retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Chat interface"]
  node_chat_ui["Chat interface<br/>[chat-shell.tsx]"]
  node_message_input["Message input<br/>[message-input.tsx]"]
  node_chat_api["Chat API client<br/>[chat-api.ts]"]
  node_message_view["Message and citations<br/>[chat-message.tsx]"]
  node_citations["Source citations"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_chat_models["Chat contracts<br/>[chat.py]"]
  node_health_route["Health endpoint<br/>[health.py]"]
end

subgraph group_rag["Retrieval and answers"]
  node_rag_service["RAG orchestration<br/>[rag_service.py]"]
  node_retrieval["Semantic retrieval"]
  node_embedding["Embedding service"]
  node_generation["Answer generation"]
  node_retrieval_model["Retrieved chunks<br/>[retrieval.py]"]
end

subgraph group_corpus["Corpus preparation"]
  node_ingestion["Corpus ingestion<br/>[ingest_corpus.py]"]
  node_pdf_parser["PDF parsing<br/>[pdf_parser.py]"]
  node_chunker["Text chunking<br/>[text_chunker.py]"]
  node_document_model["Document records<br/>[document.py]"]
end

subgraph group_state["Vector storage"]
  node_vector_store["Vector store adapter<br/>[vector_store.py]"]
  node_chroma[("Chroma database")]
end

node_user(("User"))
node_gemini["Gemini services"]

node_user -->|"asks"| node_chat_ui
node_chat_ui -->|"renders"| node_message_input
node_message_input -.->|"submits"| node_chat_api
node_chat_api -->|"POSTs chat"| node_fastapi
node_fastapi -->|"routes chat"| node_chat_route
node_chat_route -->|"invokes"| node_rag_service
node_chat_route -->|"validates response"| node_chat_models
node_rag_service -->|"retrieves evidence"| node_retrieval
node_rag_service -->|"generates answer"| node_generation
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches vectors"| node_vector_store
node_retrieval -->|"returns chunks"| node_retrieval_model
node_embedding -->|"requests embeddings"| node_gemini
node_generation -->|"requests generation"| node_gemini
node_ingestion -->|"parses PDFs"| node_pdf_parser
node_ingestion -->|"chunks pages"| node_chunker
node_ingestion -->|"embeds chunks"| node_embedding
node_ingestion -->|"stores vectors"| node_vector_store
node_pdf_parser -->|"produces pages"| node_document_model
node_chunker -->|"produces chunks"| node_document_model
node_vector_store -->|"reads and writes"| node_chroma
node_rag_service -->|"returns citations"| node_chat_models
node_chat_ui -->|"renders messages"| node_message_view
node_message_view -->|"renders sources"| node_citations
node_chat_route --> node_health_route

click node_chat_ui "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/chat-shell.tsx"
click node_message_input "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/message-input.tsx"
click node_chat_api "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/lib/chat-api.ts"
click node_message_view "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/chat-message.tsx"
click node_citations "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/source-citations.tsx"
click node_fastapi "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/main.py"
click node_chat_route "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/api/routes/chat.py"
click node_chat_models "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/models/chat.py"
click node_rag_service "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/rag_service.py"
click node_retrieval "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/retrieval_service.py"
click node_embedding "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/embedding_service.py"
click node_generation "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/generation_service.py"
click node_retrieval_model "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/models/retrieval.py"
click node_ingestion "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/scripts/ingest_corpus.py"
click node_pdf_parser "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/pdf_parser.py"
click node_chunker "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/text_chunker.py"
click node_document_model "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/models/document.py"
click node_vector_store "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/vector_store.py"
click node_health_route "https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/api/routes/health.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_chat_ui,node_message_input,node_chat_api,node_message_view,node_citations,node_user toneBlue
class node_fastapi,node_chat_route,node_chat_models,node_health_route toneAmber
class node_rag_service,node_retrieval,node_embedding,node_generation,node_retrieval_model toneMint
class node_ingestion,node_pdf_parser,node_chunker,node_document_model toneRose
class node_vector_store,node_chroma,node_gemini toneIndigo
```

## Components

### Chat interface

- [Chat interface](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/chat-shell.tsx): `frontend/src/components/chat/chat-shell.tsx`
- [Message input](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/message-input.tsx): `frontend/src/components/chat/message-input.tsx`
- [Chat API client](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/lib/chat-api.ts): `frontend/src/lib/chat-api.ts`
- [Message and citations](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/chat-message.tsx): `frontend/src/components/chat/chat-message.tsx`
- [Source citations](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/frontend/src/components/chat/source-citations.tsx): `frontend/src/components/chat/source-citations.tsx`

### API and orchestration

- [FastAPI app](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat endpoint](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/api/routes/chat.py): `backend/app/api/routes/chat.py`
- [Chat contracts](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/models/chat.py): `backend/app/models/chat.py`
- [Health endpoint](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/api/routes/health.py): `backend/app/api/routes/health.py`

### Retrieval and answers

- [RAG orchestration](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Semantic retrieval](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/retrieval_service.py): `backend/app/services/retrieval_service.py`
- [Embedding service](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Answer generation](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/generation_service.py): `backend/app/services/generation_service.py`
- [Retrieved chunks](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/models/retrieval.py): `backend/app/models/retrieval.py`

### Corpus preparation

- [Corpus ingestion](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/scripts/ingest_corpus.py): `backend/app/scripts/ingest_corpus.py`
- [PDF parsing](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/pdf_parser.py): `backend/app/services/pdf_parser.py`
- [Text chunking](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/text_chunker.py): `backend/app/services/text_chunker.py`
- [Document records](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/models/document.py): `backend/app/models/document.py`

### Vector storage

- [Vector store adapter](https://github.com/chandrugiri/healthcare-guide-ai/blob/main/backend/app/services/vector_store.py): `backend/app/services/vector_store.py`
- **Chroma database**

### Other components

- **User**
- **Gemini services**

## Connections

- User → Chat interface: asks (evidence: `README.md`)
- Chat interface → Message input: renders (evidence: `frontend/src/components/chat/chat-shell.tsx`)
- Message input → Chat API client: submits
- Chat API client → FastAPI app: POSTs chat (evidence: `README.md`)
- FastAPI app → Chat endpoint: routes chat (evidence: `backend/app/main.py`)
- Chat endpoint → RAG orchestration: invokes (evidence: `backend/app/api/routes/chat.py`)
- Chat endpoint → Chat contracts: validates response (evidence: `backend/app/api/routes/chat.py`)
- RAG orchestration → Semantic retrieval: retrieves evidence (evidence: `backend/app/services/rag_service.py`)
- RAG orchestration → Answer generation: generates answer (evidence: `backend/app/services/rag_service.py`)
- Semantic retrieval → Embedding service: embeds query (evidence: `backend/app/services/retrieval_service.py`)
- Semantic retrieval → Vector store adapter: searches vectors (evidence: `backend/app/services/retrieval_service.py`)
- Semantic retrieval → Retrieved chunks: returns chunks (evidence: `backend/app/services/retrieval_service.py`)
- Embedding service → Gemini services: requests embeddings (evidence: `backend/app/services/embedding_service.py`)
- Answer generation → Gemini services: requests generation (evidence: `backend/app/services/generation_service.py`)
- Corpus ingestion → PDF parsing: parses PDFs (evidence: `backend/app/scripts/ingest_corpus.py`)
- Corpus ingestion → Text chunking: chunks pages (evidence: `backend/app/scripts/ingest_corpus.py`)
- Corpus ingestion → Embedding service: embeds chunks (evidence: `backend/app/scripts/ingest_corpus.py`)
- Corpus ingestion → Vector store adapter: stores vectors (evidence: `backend/app/scripts/ingest_corpus.py`)
- PDF parsing → Document records: produces pages (evidence: `backend/app/services/pdf_parser.py`)
- Text chunking → Document records: produces chunks (evidence: `backend/app/services/text_chunker.py`)
- Vector store adapter → Chroma database: reads and writes (evidence: `README.md`)
- RAG orchestration → Chat contracts: returns citations (evidence: `backend/app/services/rag_service.py`)
- Chat interface → Message and citations: renders messages (evidence: `frontend/src/components/chat/chat-shell.tsx`)
- Message and citations → Source citations: renders sources (evidence: `frontend/src/components/chat/chat-message.tsx`)
- Chat endpoint → Health endpoint
