# malishilpa9119/health-care-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/malishilpa9119/health-care-chatbot
- Repository: https://github.com/malishilpa9119/health-care-chatbot

## Overview

#### Purpose and Runtime Entry Points
This repository is a document-grounded healthcare clinic chatbot. It answers clinic-policy and medical-document questions through a RAG workflow, while routing emergency, medication/dosage, and unsupported requests to safe responses.

- Web runtime: `app.py`
- Indexing/batch ingestion runtime: `store_index.py`
- Core application package: `src/`

#### Document Ingestion and Index Construction
Clinic and medical PDFs are the authoritative knowledge source. The indexing process loads PDFs, chunks their content, produces HuggingFace embeddings, and writes vectors to Pinecone. Re-indexing is required after document changes.

- Source corpus: `data/HealthFirst_Clinic_Info.pdf`, `data/Medical_book.pdf`
- Loading, splitting, and embedding utilities: `src/helper.py`
- Index build entry point: `store_index.py`

#### Retrieval Layer
The retrieval boundary converts a user question into grounded evidence from the vector store. It combines semantic Pinecone search with BM25 keyword retrieval, then applies cross-encoder re-ranking to prioritize the most relevant document chunks.

- Hybrid retrieval and re-ranking: `src/retriever.py`
- Retriever/tool implementation is consumed by the workflow: `src/agent.py`
- Persistent external retrieval service: Pinecone

#### LangGraph Conversation Workflow
The central control flow is a LangGraph agent pipeline:

1. Receive current user question plus multi-turn conversation context.
2. Apply safety guardrails.
3. Retrieve and rank document evidence when permitted.
4. Generate an answer constrained to retrieved content.
5. Use a fallback branch when evidence is absent or the request is unsafe/out of scope.

- Workflow nodes, routing, and agent state: `src/agent.py`
- Grounding and behavioral instructions: `src/prompt.py`

#### Generation, Safety, and Fallback Boundaries
Groq-hosted Llama 3.3 70B performs answer generation. Prompting and graph routing enforce the core product constraint: do not invent clinic or medical facts beyond supplied documents. Emergency and medication/dosage requests are safety boundaries rather than normal retrieval questions; unsupported requests receive a defined fallback.

- Agent orchestration and guardrail/fallback handling: `src/agent.py`
- System prompt contract: `src/prompt.py`
- External LLM provider: Groq; optional image-analysis provider: OpenAI

#### Flask Interface and Session Interaction
Flask exposes the chat application on the local web server and connects browser requests to the agent workflow. The HTML template provides the conversation interface, with static CSS for presentation. The application maintains multi-turn context so follow-up questions can depend on prior turns.

- HTTP application entry point: `app.py`
- Chat UI: `templates/chat.html`
- Client styling: `static/style.css`

#### Deployment and Dependencies
The runtime is Python, with container deployment support. Required credentials are environment-provided API keys for Pinecone and Groq; OpenAI is optional for image analysis. The architecture depends on LangChain/LangGraph for orchestration, Pinecone for vector persistence, HuggingFace embeddings for vectorization, and Flask for serving.

- Dependency declaration: `requirements.txt`
- Container runtime definition: `Dockerfile`
- Python runtime version declaration: `runtime.txt`

Main entry points: [`app.py`](https://github.com/malishilpa9119/health-care-chatbot/blob/main/app.py) (Flask chat server), [`src/agent.py`](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py) (Grounded answer generation), [`src/retriever.py`](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/retriever.py) (Hybrid retrieval), [`store_index.py`](https://github.com/malishilpa9119/health-care-chatbot/blob/main/store_index.py) (Index build runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_flask["Flask chat server<br/>Python entry point<br/>[app.py]"]
  node_chat_ui["Chat interface<br/>HTML template<br/>[chat.html]"]
  node_styles["Client styles<br/>CSS<br/>[style.css]"]
end

subgraph group_workflow["Conversation workflow"]
  node_agent["LangGraph agent<br/>workflow orchestration<br/>[agent.py]"]
  node_guardrails{{"Safety routing<br/>workflow boundary<br/>[agent.py]"}}
  node_retriever["Hybrid retrieval<br/>retrieval layer<br/>[retriever.py]"]
  node_prompt["Grounding contract<br/>system prompt<br/>[prompt.py]"]
  node_generation["Grounded answer generation<br/>LLM invocation<br/>[agent.py]"]
end

subgraph group_indexing["Index construction"]
  node_indexer["Index build runtime<br/>Python entry point<br/>[store_index.py]"]
  node_corpus["Clinic and medical PDFs<br/>authoritative corpus"]
  node_ingestion["Load, chunk, embed<br/>ingestion utilities<br/>[helper.py]"]
end

subgraph group_external["External services"]
  node_pinecone[("Pinecone<br/>vector store")]
  node_groq{{"Groq Llama 3.3 70B<br/>LLM provider"}}
  node_openai{{"OpenAI image analysis<br/>optional provider"}}
end

node_container["Container deployment<br/>runtime packaging"]
node_dependencies["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
node_python_runtime["Python runtime version<br/>runtime declaration<br/>[runtime.txt]"]

node_chat_ui -->|"chat requests"| node_flask
node_styles -->|"styles"| node_chat_ui
node_flask -->|"question + conversation context"| node_agent
node_agent -->|"evaluate request"| node_guardrails
node_guardrails -->|"permitted question"| node_retriever
node_guardrails -.->|"safe fallback"| node_flask
node_retriever -->|"semantic search"| node_pinecone
node_retriever -->|"ranked evidence"| node_generation
node_prompt -->|"grounding instructions"| node_generation
node_generation -->|"generate answer"| node_groq
node_generation -->|"grounded response"| node_flask
node_indexer -->|"loads PDFs"| node_corpus
node_indexer -->|"uses"| node_ingestion
node_ingestion -->|"writes embeddings"| node_pinecone
node_container -.->|"runs"| node_flask
node_dependencies -.->|"provides libraries"| node_flask
node_python_runtime -.->|"pins runtime"| node_container
node_agent -.->|"optional image analysis"| node_openai

click node_flask "https://github.com/malishilpa9119/health-care-chatbot/blob/main/app.py"
click node_chat_ui "https://github.com/malishilpa9119/health-care-chatbot/blob/main/templates/chat.html"
click node_styles "https://github.com/malishilpa9119/health-care-chatbot/blob/main/static/style.css"
click node_agent "https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py"
click node_guardrails "https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py"
click node_retriever "https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/retriever.py"
click node_prompt "https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/prompt.py"
click node_generation "https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py"
click node_indexer "https://github.com/malishilpa9119/health-care-chatbot/blob/main/store_index.py"
click node_ingestion "https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/helper.py"
click node_container "https://github.com/malishilpa9119/health-care-chatbot/blob/main/Dockerfile"
click node_dependencies "https://github.com/malishilpa9119/health-care-chatbot/blob/main/requirements.txt"
click node_python_runtime "https://github.com/malishilpa9119/health-care-chatbot/blob/main/runtime.txt"

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_flask,node_chat_ui,node_styles toneBlue
class node_agent,node_guardrails,node_retriever,node_prompt,node_generation toneAmber
class node_indexer,node_corpus,node_ingestion toneMint
class node_pinecone,node_groq,node_openai toneRose
class node_container,node_dependencies,node_python_runtime toneNeutral
```

## Components

### Web interface

- [Flask chat server](https://github.com/malishilpa9119/health-care-chatbot/blob/main/app.py): Python entry point · Serves chat requests and maintains multi-turn context. · `app.py`
- [Chat interface](https://github.com/malishilpa9119/health-care-chatbot/blob/main/templates/chat.html): HTML template · `templates/chat.html`
- [Client styles](https://github.com/malishilpa9119/health-care-chatbot/blob/main/static/style.css): CSS · `static/style.css`

### Conversation workflow

- [LangGraph agent](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py): workflow orchestration · Owns state, routing, safety handling, and fallback responses. · `src/agent.py`
- [Safety routing](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py): workflow boundary · Routes emergency, dosage, unsafe, and unsupported requests away from normal answering. · `src/agent.py`
- [Hybrid retrieval](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/retriever.py): retrieval layer · Combines Pinecone semantic search, BM25, and cross-encoder reranking. · `src/retriever.py`
- [Grounding contract](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/prompt.py): system prompt · Constrains answers to supplied document evidence. · `src/prompt.py`
- [Grounded answer generation](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/agent.py): LLM invocation · `src/agent.py`

### Index construction

- [Index build runtime](https://github.com/malishilpa9119/health-care-chatbot/blob/main/store_index.py): Python entry point · Rebuilds the vector index after corpus changes. · `store_index.py`
- **Clinic and medical PDFs**: authoritative corpus
- [Load, chunk, embed](https://github.com/malishilpa9119/health-care-chatbot/blob/main/src/helper.py): ingestion utilities · Extracts PDF content, splits chunks, and creates HuggingFace embeddings. · `src/helper.py`

### External services

- **Pinecone**: vector store · Persists document vectors and serves semantic search.
- **Groq Llama 3.3 70B**: LLM provider
- **OpenAI image analysis**: optional provider

### Other components

- [Container deployment](https://github.com/malishilpa9119/health-care-chatbot/blob/main/Dockerfile): runtime packaging · `Dockerfile`
- [Python dependencies](https://github.com/malishilpa9119/health-care-chatbot/blob/main/requirements.txt): dependency manifest · `requirements.txt`
- [Python runtime version](https://github.com/malishilpa9119/health-care-chatbot/blob/main/runtime.txt): runtime declaration · `runtime.txt`

## Connections

- Chat interface → Flask chat server: chat requests
- Client styles → Chat interface: styles
- Flask chat server → LangGraph agent: question + conversation context
- LangGraph agent → Safety routing: evaluate request
- Safety routing → Hybrid retrieval: permitted question
- Safety routing → Flask chat server: safe fallback
- Hybrid retrieval → Pinecone: semantic search
- Hybrid retrieval → Grounded answer generation: ranked evidence
- Grounding contract → Grounded answer generation: grounding instructions
- Grounded answer generation → Groq Llama 3.3 70B: generate answer
- Grounded answer generation → Flask chat server: grounded response
- Index build runtime → Clinic and medical PDFs: loads PDFs
- Index build runtime → Load, chunk, embed: uses
- Load, chunk, embed → Pinecone: writes embeddings
- Container deployment → Flask chat server: runs
- Python dependencies → Flask chat server: provides libraries
- Python runtime version → Container deployment: pins runtime
- LangGraph agent → OpenAI image analysis: optional image analysis