# innocent-zero/healthassistantchatbot architecture

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

- Interactive diagram: https://gitdiagram.com/innocent-zero/healthassistantchatbot
- Repository: https://github.com/innocent-zero/healthassistantchatbot

## Overview

1. **High-level shape**
   - This repo is a two-part system: a **browser UI** in `frontend/` and a **Python backend API** in `backend/`.
   - The backend orchestrates two domains: **disease information / triage** and **mental health support**.

2. **Frontend boundary**
   - The frontend is a **static client** made of `index.html`, `frontend.js`, and `styles.css`.
   - It handles user interaction, mode selection, text entry, and voice capture. The README describes React, but the tree here looks like a plain browser app rather than a React componentized source tree.

3. **Backend entrypoint and API layer**
   - `backend/main.py` is the application entrypoint and likely exposes the REST endpoints consumed by the browser.
   - This layer is responsible for request routing, response assembly, and audio transcription endpoints such as the one referenced in the README (`/api/transcribe`).

4. **Disease-assistant subsystem**
   - `disease_predictor.py` loads and uses the persisted ML model in `models/disease_model.pkl`.
   - `rag_engine.py` provides retrieval-augmented responses using the local vector store under `chroma_db/` plus the CSV datasets in `data/`.
   - `safety_checker.py` adds emergency / critical-symptom detection before or alongside the normal response.
   - `ai_handler.py` appears to combine prediction, retrieval, and safety into a user-facing health response.

5. **Mental-health subsystem**
   - `mental_health_detector.py` analyzes emotional state or sentiment from user input.
   - `mental_health_support.py` maps detected state to coping guidance, support resources, and crisis handling.
   - `mood_tracker.py` persists or computes mood trends over time.
   - `mental_health_ai_handler.py` assembles the conversational response for this mode.

6. **Data and persistence layer**
   - The repo includes an embedded **ChromaDB** store in `chroma_db/`, used as the retrieval knowledge base.
   - The disease model is an offline artifact in `models/disease_model.pkl`, suggesting the core classifier is not trained at runtime.
   - Training and testing data live in `data/Training.csv` and `data/Testing.csv`, which feed the disease model and/or related symptom logic.

7. **Voice input pipeline**
   - The README describes a two-tier transcription flow:
     - **Browser-side Web Speech API** for direct transcription when supported.
     - **Server-side fallback** using MediaRecorder → backend upload → FFmpeg conversion → speech recognition.
   - This makes audio handling a distinct backend concern rather than just a UI feature.

8. **External service dependency**
   - The backend likely integrates with an external LLM provider via the environment variable mentioned in `sample.env` and README text (`GROQ API key`).
   - Google Speech Recognition is also part of the fallback transcription path, so network access matters for voice input and possibly for AI generation.

9. **Safety and crisis handling**
   - Safety is a first-class cross-cutting concern, not just a UI warning.
   - `safety_checker.py` and the mental-health modules likely intercept high-risk language and route users to urgent guidance or crisis resources instead of normal conversational output.

10. **Operational scripts and packaging**
   - `run.sh` and `frontend.sh` are convenience launch scripts.
   - `backend/requirements.txt` and `backend/setup.py` define the Python environment.
   - `test_main.py` suggests at least one integration or smoke-test path for the backend entrypoint.

11. **Runtime and deployment implications**
   - The backend is Python-based and depends on local machine assets: FFmpeg, the model pickle, and the embedded vector DB.
   - The frontend runs in the browser and talks to the backend over HTTP, so the main runtime boundary is **browser client ↔ API server ↔ local ML/data assets / external AI services**.

12. **How to draw the architecture**
   - Put the **browser UI** on one side.
   - Put a central **backend API** box in the middle.
   - Inside the backend, split into **Health/Disease** and **Mental Health** processing lanes, with a shared **voice transcription** path and **safety layer**.
   - On the data side, show **ChromaDB + CSV knowledge base + pickled model** as local stores, and show **external AI / speech services** as outbound dependencies.

Main entry points: [`backend/mental_health_ai_handler.py`](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_ai_handler.py) (Mental Health Orchestrator), [`backend/main.py`](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/main.py) (API Entry), [`backend/ai_handler.py`](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/ai_handler.py) (Health Orchestrator), [`backend/disease_predictor.py`](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/disease_predictor.py) (Disease Predictor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_ui["Browser UI<br/>static client<br/>[index.html]"]
  node_client_script["Client Script<br/>ui logic<br/>[frontend.js]"]
  node_styles["Styles<br/>presentation<br/>[styles.css]"]
end

subgraph group_backend["Backend"]
  node_api_main["API Entry<br/>server entrypoint<br/>[main.py]"]
  node_health_router["Health Orchestrator<br/>response assembly<br/>[ai_handler.py]"]
  node_disease_predictor["Disease Predictor<br/>ml inference"]
  node_rag_engine["RAG Engine<br/>retrieval layer<br/>[rag_engine.py]"]
  node_safety_checker["Safety Checker<br/>risk filter<br/>[safety_checker.py]"]
  node_mental_router["Mental Health Orchestrator<br/>response assembly"]
  node_mood_detector["Mood Detector<br/>sentiment analysis"]
  node_support_logic["Support Logic<br/>guidance engine"]
  node_mood_tracker["Mood Tracker<br/>state store<br/>[mood_tracker.py]"]
  node_speech_path["Voice Pipeline<br/>transcription flow"]
end

subgraph group_data["Data"]
  node_disease_model[("Disease Model<br/>pickle artifact<br/>[disease_model.pkl]")]
  node_knowledge_base[("Chroma Store<br/>vector db<br/>[chroma.sqlite3]")]
  node_training_data["Training Data<br/>csv corpus<br/>[Training.csv]"]
  node_testing_data["Testing Data<br/>csv corpus<br/>[Testing.csv]"]
end

subgraph group_external["External"]
  node_llm_service(("LLM Provider<br/>external ai service"))
  node_speech_service(("Speech Service<br/>external speech api"))
  node_ffmpeg{{"FFmpeg<br/>media runtime"}}
end

node_browser_ui -->|"loads"| node_client_script
node_client_script -->|"HTTP requests"| node_api_main
node_client_script -.->|"browser speech"| node_speech_service
node_api_main -->|"routes"| node_health_router
node_api_main -->|"routes"| node_mental_router
node_api_main -->|"transcribe"| node_speech_path
node_health_router -->|"predicts"| node_disease_predictor
node_health_router -->|"grounds"| node_rag_engine
node_health_router -->|"screens"| node_safety_checker
node_health_router -.->|"generates"| node_llm_service
node_disease_predictor -->|"loads"| node_disease_model
node_disease_predictor -.->|"trained on"| node_training_data
node_disease_predictor -.->|"evaluated on"| node_testing_data
node_rag_engine -->|"queries"| node_knowledge_base
node_rag_engine -.->|"references"| node_training_data
node_mental_router -->|"analyzes"| node_mood_detector
node_mental_router -->|"advises"| node_support_logic
node_mental_router -->|"tracks"| node_mood_tracker
node_mental_router -->|"screens"| node_safety_checker
node_mental_router -.->|"generates"| node_llm_service
node_speech_path -->|"converts"| node_ffmpeg
node_speech_path -->|"transcribes"| node_speech_service
node_api_main -->|"responds to"| node_client_script

click node_browser_ui "https://github.com/innocent-zero/healthassistantchatbot/blob/main/frontend/index.html"
click node_client_script "https://github.com/innocent-zero/healthassistantchatbot/blob/main/frontend/frontend.js"
click node_styles "https://github.com/innocent-zero/healthassistantchatbot/blob/main/frontend/styles.css"
click node_api_main "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/main.py"
click node_health_router "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/ai_handler.py"
click node_disease_predictor "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/disease_predictor.py"
click node_rag_engine "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/rag_engine.py"
click node_safety_checker "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/safety_checker.py"
click node_mental_router "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_ai_handler.py"
click node_mood_detector "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_detector.py"
click node_support_logic "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_support.py"
click node_mood_tracker "https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mood_tracker.py"
click node_disease_model "https://github.com/innocent-zero/healthassistantchatbot/blob/main/models/disease_model.pkl"
click node_knowledge_base "https://github.com/innocent-zero/healthassistantchatbot/blob/main/chroma_db/chroma.sqlite3"
click node_training_data "https://github.com/innocent-zero/healthassistantchatbot/blob/main/data/Training.csv"
click node_testing_data "https://github.com/innocent-zero/healthassistantchatbot/blob/main/data/Testing.csv"

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_browser_ui,node_client_script,node_styles toneBlue
class node_api_main,node_health_router,node_disease_predictor,node_rag_engine,node_safety_checker,node_mental_router,node_mood_detector,node_support_logic,node_mood_tracker,node_speech_path toneAmber
class node_disease_model,node_knowledge_base,node_training_data,node_testing_data toneMint
class node_llm_service,node_speech_service,node_ffmpeg toneRose
```

## Components

### Frontend

Browser client and presentation layer

- [Browser UI](https://github.com/innocent-zero/healthassistantchatbot/blob/main/frontend/index.html): static client · Renders the chat interface and mode selection in the browser · `frontend/index.html`
- [Client Script](https://github.com/innocent-zero/healthassistantchatbot/blob/main/frontend/frontend.js): ui logic · Handles user input, voice capture, and API calls · `frontend/frontend.js`
- [Styles](https://github.com/innocent-zero/healthassistantchatbot/blob/main/frontend/styles.css): presentation · Visual styling for the browser interface · `frontend/styles.css`

### Backend

Python API and domain logic

- [API Entry](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/main.py): server entrypoint · Starts the backend application and exposes HTTP routes · `backend/main.py`
- [Health Orchestrator](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/ai_handler.py): response assembly · Combines prediction, retrieval, and safety for disease-related responses · `backend/ai_handler.py`
- [Disease Predictor](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/disease_predictor.py): ml inference · Loads the trained classifier and predicts likely conditions · `backend/disease_predictor.py`
- [RAG Engine](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/rag_engine.py): retrieval layer · Builds grounded responses from local knowledge sources · `backend/rag_engine.py`
- [Safety Checker](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/safety_checker.py): risk filter · Detects emergencies and critical symptom language · `backend/safety_checker.py`
- [Mental Health Orchestrator](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_ai_handler.py): response assembly · Coordinates emotion detection, support guidance, and crisis handling · `backend/mental_health_ai_handler.py`
- [Mood Detector](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_detector.py): sentiment analysis · Infers emotional state from user text · `backend/mental_health_detector.py`
- [Support Logic](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mental_health_support.py): guidance engine · Maps mental state to coping advice and resources · `backend/mental_health_support.py`
- [Mood Tracker](https://github.com/innocent-zero/healthassistantchatbot/blob/main/backend/mood_tracker.py): state store · Tracks mood trends over time · `backend/mood_tracker.py`
- **Voice Pipeline**: transcription flow · Fallback audio upload, conversion, and transcription path

### Data

Local model and knowledge stores

- [Disease Model](https://github.com/innocent-zero/healthassistantchatbot/blob/main/models/disease_model.pkl): pickle artifact · Persisted classifier used for symptom-based prediction · `models/disease_model.pkl`
- [Chroma Store](https://github.com/innocent-zero/healthassistantchatbot/blob/main/chroma_db/chroma.sqlite3): vector db · Embedded retrieval index for grounded health answers · `chroma_db/chroma.sqlite3`
- [Training Data](https://github.com/innocent-zero/healthassistantchatbot/blob/main/data/Training.csv): csv corpus · Tabular symptom and diagnosis data used by the disease system · `data/Training.csv`
- [Testing Data](https://github.com/innocent-zero/healthassistantchatbot/blob/main/data/Testing.csv): csv corpus · Held-out data for validation and evaluation · `data/Testing.csv`

### External

Outbound services and runtime dependencies

- **LLM Provider**: external ai service · External generative model used for conversational responses
- **Speech Service**: external speech api · Browser or server-side speech recognition dependency
- **FFmpeg**: media runtime · Audio conversion dependency used in server-side transcription

## Connections

- Browser UI → Client Script: loads · The page is driven by browser logic
- Client Script → API Entry: HTTP requests · Sends chat, mode, and transcription requests to the backend
- Client Script → Speech Service: browser speech · Uses Web Speech API when available
- API Entry → Health Orchestrator: routes · Dispatches disease-related requests
- API Entry → Mental Health Orchestrator: routes · Dispatches mental-health requests
- API Entry → Voice Pipeline: transcribe · Handles fallback audio transcription uploads
- Health Orchestrator → Disease Predictor: predicts · Runs symptom-based classification
- Health Orchestrator → RAG Engine: grounds · Fetches supporting medical context
- Health Orchestrator → Safety Checker: screens · Checks for urgent symptoms before normal response
- Health Orchestrator → LLM Provider: generates · May use an external LLM for final wording
- Disease Predictor → Disease Model: loads · Reads the persisted classifier artifact
- Disease Predictor → Training Data: trained on · Uses CSV symptom data as the model source
- Disease Predictor → Testing Data: evaluated on · Uses held-out CSV data for validation
- RAG Engine → Chroma Store: queries · Retrieves context from the embedded vector store
- RAG Engine → Training Data: references · May use CSV content as source material
- Mental Health Orchestrator → Mood Detector: analyzes · Detects emotional state from user text
- Mental Health Orchestrator → Support Logic: advises · Selects coping guidance and crisis resources
- Mental Health Orchestrator → Mood Tracker: tracks · Persists or aggregates mood history
- Mental Health Orchestrator → Safety Checker: screens · Escalates high-risk language to urgent guidance
- Mental Health Orchestrator → LLM Provider: generates · Can use an external LLM for conversational output
- Voice Pipeline → FFmpeg: converts · Transforms uploaded audio into a recognisable format
- Voice Pipeline → Speech Service: transcribes · Uses speech recognition after conversion
- API Entry → Client Script: responds to · Returns JSON consumed by the browser client