How innocent-zero/healthassistantchatbot works
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: mental_health_ai_handler.py Mental Health Orchestrator · main.py API Entry · ai_handler.py Health Orchestrator · disease_predictor.py Disease Predictor
Components 20
Frontend
Browser client and presentation layer
- Browser UI · Renders the chat interface and mode selection in the browser
frontend/index.html - Client Script · Handles user input, voice capture, and API calls
frontend/frontend.js - Styles · Visual styling for the browser interface
frontend/styles.css
Backend
Python API and domain logic
- API Entry · Starts the backend application and exposes HTTP routes
backend/main.py - Health Orchestrator · Combines prediction, retrieval, and safety for disease-related responses
backend/ai_handler.py - Disease Predictor · Loads the trained classifier and predicts likely conditions
backend/disease_predictor.py - RAG Engine · Builds grounded responses from local knowledge sources
backend/rag_engine.py - Safety Checker · Detects emergencies and critical symptom language
backend/safety_checker.py - Mental Health Orchestrator · Coordinates emotion detection, support guidance, and crisis handling
backend/mental_health_ai_handler.py - Mood Detector · Infers emotional state from user text
backend/mental_health_detector.py - Support Logic · Maps mental state to coping advice and resources
backend/mental_health_support.py - Mood Tracker · Tracks mood trends over time
backend/mood_tracker.py - Voice Pipeline · Fallback audio upload, conversion, and transcription path
Data
Local model and knowledge stores
- Disease Model · Persisted classifier used for symptom-based prediction
models/disease_model.pkl - Chroma Store · Embedded retrieval index for grounded health answers
chroma_db/chroma.sqlite3 - Training Data · Tabular symptom and diagnosis data used by the disease system
data/Training.csv - Testing Data · Held-out data for validation and evaluation
data/Testing.csv
External
Outbound services and runtime dependencies
- LLM Provider · External generative model used for conversational responses
- Speech Service · Browser or server-side speech recognition dependency
- FFmpeg · Audio conversion dependency used in server-side transcription
Connections 23
- 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