# foxder15/health-chatbot architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack Health Chatbot application.
- Purpose: Accept health-related queries via a Streamlit UI, dispatch them to a FastAPI backend, run a Retrieval-Augmented Generation (RAG) pipeline (using crewAI, custom embedding stores, and document preprocessing), and return generated answers.

##### File structure
- Top-level:
- app.py (Streamlit frontend entry point)
- src/apis/query_api.py (FastAPI backend entry point)
- src/RAG – modules for advanced RAG logic, embedding modification, preprocessing
- src/embedding – per-scenario vector stores and JSON doc/graph stores
- src/config – YAML definitions of agents and tasks
- crew.py – orchestration script
- db/ & src/default.sqlite / db/chroma.sqlite3 – persistent data stores
- document/ & public/ – sample corpora, chat histories, evaluation artifacts
- evaluation.ipynb & report.md – offline evaluation and reporting
- requirements.txt – dependencies (FastAPI, Streamlit, crewAI, Chroma, etc.)

##### README
- Confirms FastAPI for backend, Streamlit for frontend, crewAI for LLM orchestration
- Instructions to launch two processes:
- Uvicorn → src/apis/query_api:app
- streamlit run app.py

##### Diagramming the architecture
a. Main components
1. Frontend: Streamlit UI (app.py)
2. Backend: FastAPI Query API (query_api:app)
3. RAG Pipeline:
– Preprocessing module
– Embedding modules (src/embedding/…)
– Retrieval engine (Chroma DB / vector stores)
– LLM orchestrator (crewAI via crew.py)
4. Data Stores:
– Binary/document store in db/ and src/embedding/*
– SQLite databases (chroma.sqlite3, default.sqlite)
5. Configuration: YAML files for agents/tasks
6. External Services:
– crewAI LLM endpoint (cloud or local)
7. Evaluation: Jupyter notebook + report for offline testing

b. Relationships & interactions
- User → (HTTP over localhost:8501) → Streamlit UI
- Streamlit → (HTTP REST) → FastAPI Query API
- Query API → invokes RAG modules in-process
- Preprocessing → text & PDF loader → normalized docs
- Embedding module → produces vectors → stored/read from Chroma & JSON stores
- Retrieval → top-k matches → fed to LLM orchestrator
- LLM orchestrator (crew.py) → crewAI API → generates response
- Response flows back through FastAPI → Streamlit → User
- Evaluation pipeline reads same stores, runs offline tests

c. Architectural patterns & principles
- Separation of concerns: UI vs API vs RAG logic vs storage
- Modular RAG pipeline: preprocessing, embedding, retrieval stages
- Configuration-driven behavior: agents.yaml & tasks.yaml
- Persistence layer abstracted via vector stores and SQLite

d. Key technologies & libraries
- Frontend: Streamlit
- Backend: FastAPI, Uvicorn
- RAG: custom Python modules, Chroma vector DB
- Orchestration: crewAI, crew.py
- Data formats: .bin, .json, SQLite
- Configuration: YAML

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers defined implicitly by classes

    User["User"]:::user
    User -->|"HTTP POST: query"| Streamlit
    
    Streamlit["Streamlit UI\n(app.py)"]:::frontend
    click Streamlit "https://github.com/foxder15/health-chatbot/blob/master/app.py"
    Streamlit -->|"REST API: /query"| QueryAPI

    QueryAPI["FastAPI Query API\n(src/apis/query_api.py)"]:::backend
    click QueryAPI "https://github.com/foxder15/health-chatbot/blob/master/src/apis/query_api.py"
    QueryAPI -->|"raw text"| Preprocessing

    subgraph "RAG Pipeline" 
        direction TB
        Preprocessing["Preprocessing Module\n(src/RAG/preprocessing.py)"]:::rag
        click Preprocessing "https://github.com/foxder15/health-chatbot/blob/master/src/RAG/preprocessing.py"
        Preprocessing -->|"clean text"| EmbeddingMod

        EmbeddingMod["Embedding Modification\n(src/RAG/embedding_modify.py)"]:::rag
        click EmbeddingMod "https://github.com/foxder15/health-chatbot/blob/master/src/RAG/embedding_modify.py"
        EmbeddingMod -->|"vectors"| AdvancedRAG

        AdvancedRAG["Advanced RAG Logic\n(src/RAG/advanced_rag.py)"]:::rag
        click AdvancedRAG "https://github.com/foxder15/health-chatbot/blob/master/src/RAG/advanced_rag.py"
        AdvancedRAG -->|"prompt"| LLMOrch
    end

    subgraph "Orchestration"
        direction TB
        LLMOrch["LLM Orchestrator\n(crew.py)"]:::external
        click LLMOrch "https://github.com/foxder15/health-chatbot/blob/master/src/crew.py"
        LLMOrch -->|"LLM request"| ExternalLLM
        ExternalLLM["crewAI LLM Service"]:::external
        ExternalLLM -->|"generated answer"| LLMOrch
        LLMOrch -->|"response text"| QueryAPI
    end

    QueryAPI -->|"JSON response"| Streamlit
    Streamlit -->|"display"| User

    subgraph "Persistent Storage"
        direction TB
        subgraph "Embedding Stores" 
            direction TB
            AdvVecStore["Advance_Rag Stores"]:::storage
            click AdvVecStore "https://github.com/foxder15/health-chatbot/tree/master/src/embedding/Advance_Rag/"
            TestStore["Test Stores"]:::storage
            click TestStore "https://github.com/foxder15/health-chatbot/tree/master/src/embedding/Test/"
            EvalStore["Evaluation Stores"]:::storage
            click EvalStore "https://github.com/foxder15/health-chatbot/tree/master/src/embedding/evaluation/"
            PDFStore["PDF Stores"]:::storage
            click PDFStore "https://github.com/foxder15/health-chatbot/tree/master/src/embedding/pdf_3/"
            SentStore["Sentence Index Stores"]:::storage
            click SentStore "https://github.com/foxder15/health-chatbot/tree/master/src/embedding/sentence_index/"
        end
        BinStore["Binary Vector Files\n(db/0c08af0a-a331-4c3f-9f18-fb5b7e9311d1/)"]:::storage
        click BinStore "https://github.com/foxder15/health-chatbot/tree/master/db/0c08af0a-a331-4c3f-9f18-fb5b7e9311d1/"
        ChromaDB["Chroma SQLite\n(db/chroma.sqlite3)"]:::storage
        click ChromaDB "https://github.com/foxder15/health-chatbot/blob/master/db/chroma.sqlite3"
        DefaultDB["Default SQLite\n(src/default.sqlite)"]:::storage
        click DefaultDB "https://github.com/foxder15/health-chatbot/blob/master/src/default.sqlite"
    end

    EmbeddingMod --> AdvVecStore
    EmbeddingMod --> TestStore
    EmbeddingMod --> EvalStore
    EmbeddingMod --> PDFStore
    EmbeddingMod --> SentStore
    EmbeddingMod --> BinStore
    EmbeddingMod --> ChromaDB
    EmbeddingMod --> DefaultDB

    subgraph "Configuration"
        agents["agents.yaml"]:::config
        click agents "https://github.com/foxder15/health-chatbot/blob/master/src/config/agents.yaml"
        tasks["tasks.yaml"]:::config
        click tasks "https://github.com/foxder15/health-chatbot/blob/master/src/config/tasks.yaml"
    end
    agents --> Preprocessing
    tasks --> AdvancedRAG

    subgraph "Evaluation"
        EvalNotebook["evaluation.ipynb"]:::evaluation
        click EvalNotebook "https://github.com/foxder15/health-chatbot/blob/master/evaluation.ipynb"
        Report["report.md"]:::evaluation
        click Report "https://github.com/foxder15/health-chatbot/blob/master/report.md"
        EvalNotebook --> AdvVecStore
        EvalNotebook --> ChromaDB
        EvalNotebook --> Report
    end

    Public["Public Artifacts\n(public/)"]:::storage
    click Public "https://github.com/foxder15/health-chatbot/tree/master/public/"
    DocumentCorpus["Document Corpus\n(document/)"]:::storage
    click DocumentCorpus "https://github.com/foxder15/health-chatbot/tree/master/document/"

    Preprocessing --> DocumentCorpus
    Preprocessing --> Public

    %% Misc files
    Req["requirements.txt"]:::config
    Gitignore[".gitignore"]:::config
    Readme["Readme.md"]:::config
    click Req "https://github.com/foxder15/health-chatbot/blob/master/requirements.txt"
    click Gitignore "https://github.com/foxder15/health-chatbot/blob/master/.gitignore"
    click Readme "https://github.com/foxder15/health-chatbot/blob/master/Readme.md"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef rag fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef config fill:#F0E68C,stroke:#000,stroke-width:1px;
    classDef evaluation fill:#E6E6FA,stroke:#000,stroke-width:1px;
    classDef user fill:#FFFFFF,stroke:#000,stroke-width:1px;
```
