# ujjawalps/healthsavvy architecture

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

- Interactive diagram: https://gitdiagram.com/ujjawalps/healthsavvy
- Repository: https://github.com/ujjawalps/healthsavvy

## Overview

##### Project Type & Purpose
- Full-stack web application with a conversational AI chatbot.
- Purpose: let users enter symptom queries in natural language, run a vector-search + LLM pipeline over a medical PDF, and return contextual health guidance.

##### Main Components
a. Client (Browser)
- HTML/CSS/Vanilla JS (templates/chat.html + static/style.css)
- Renders chat interface, captures user input, displays responses.
b. Web Server (Flask Backend)
- app.py: HTTP endpoints (e.g., “/chat” route)
- template.py & render.yaml: deployment configuration on Render.
c. Business Logic & AI Pipeline
- src/prompt.py: prompt construction for LLM
- src/helper.py: utility functions (e.g., formatting, error handling)
d. Data Ingestion
- store_index.py: reads Data/Medical_book.pdf, uses LangChain to chunk + embed, pushes embeddings to Pinecone
e. Vector Store
- Pinecone (external service): stores and retrieves embeddings for similarity search
f. LLM Service
- OpenAI/Gemini API (external) for generating conversational responses
g. Configuration & Environment
- requirements.txt, setup.py, runtime.txt, .env for API keys

##### Relationships & Data Flow
1. User types message → Browser sends AJAX POST to Flask “/chat” endpoint
2. Flask handler (app.py) invokes src/prompt to build the LLM prompt
3. Handler calls Pinecone (via LangChain client) to retrieve top-k document embeddings relevant to the query
4. Retrieved context + user query sent to OpenAI/Gemini API
5. LLM response received → Flask returns JSON to front end
6. Browser JS updates chat UI

Separately, on startup or via a CLI command, store_index.py ingests the PDF into Pinecone.

##### Architectural Patterns & Design Principles
- MVC-like separation:
- View: templates + static assets
- Controller: Flask routes in app.py
- Model: Pinecone vector database + PDF as source data
- Modular code organization: all prompt- and helper-logic in src/
- API orchestration: chaining Pinecone + LLM calls using LangChain
- Externalization of configuration: requirements.txt, runtime.txt, render.yaml, .env

##### Final Checklist
- Clear component boundaries (Frontend, Backend, External Services, Data Source)
- Annotations for key files and technologies (Flask, LangChain, Pinecone, OpenAI/Gemini)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Browser UI)"
        direction TB
        ChatHTML["Chat Interface\n(templates/chat.html)"]:::frontend
        CSS["Stylesheet\n(static/style.css)"]:::frontend
    end

    subgraph "Backend (Flask App)"
        direction TB
        FlaskApp["Flask App\n(app.py)"]:::backend
        TemplateMod["Template Module\n(template.py)"]:::backend
        RenderCfg["Render Config\n(render.yaml)"]:::backend
        subgraph "AI Pipeline"
            direction TB
            Prompt["Prompt Builder\n(src/prompt.py)"]:::backend
            Helper["Helper Utils\n(src/helper.py)"]:::backend
        end
    end

    subgraph "Configuration & Environment"
        direction TB
        Req["requirements.txt"]:::config
        Setup["setup.py"]:::config
        Runtime["runtime.txt"]:::config
    end

    subgraph "Data Ingestion Pipeline"
        direction TB
        StoreIndex["Indexing Script\n(store_index.py)"]:::backend
        MedicalPDF["Medical PDF\n(Data/Medical_book.pdf)"]:::db
    end

    subgraph "External Services"
        direction TB
        Pinecone["Pinecone Vector Store"]:::external
        LLM["OpenAI/Gemini LLM API"]:::external
    end

    ChatHTML -->|"User Message"| FlaskApp
    CSS --> FlaskApp
    FlaskApp -->|"build prompt"| Prompt
    FlaskApp -->|"format/error utils"| Helper
    FlaskApp -->|"Similarity search"| Pinecone
    Pinecone --> FlaskApp
    FlaskApp -->|"Generate completion"| LLM
    LLM --> FlaskApp
    FlaskApp -->|"Chat response JSON"| ChatHTML

    StoreIndex -->|"reads PDF"| MedicalPDF
    StoreIndex -->|"push embeddings"| Pinecone

    classDef frontend fill:#A2DFFF,stroke:#333,stroke-width:1px;
    classDef backend fill:#FFDCA8,stroke:#333,stroke-width:1px;
    classDef external fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef db fill:#FFF59D,stroke:#333,stroke-width:1px;
    classDef config fill:#E1BEE7,stroke:#333,stroke-width:1px;

    click ChatHTML "https://github.com/ujjawalps/healthsavvy/blob/main/templates/chat.html"
    click CSS "https://github.com/ujjawalps/healthsavvy/blob/main/static/style.css"
    click FlaskApp "https://github.com/ujjawalps/healthsavvy/blob/main/app.py"
    click TemplateMod "https://github.com/ujjawalps/healthsavvy/blob/main/template.py"
    click RenderCfg "https://github.com/ujjawalps/healthsavvy/blob/main/render.yaml"
    click Prompt "https://github.com/ujjawalps/healthsavvy/blob/main/src/prompt.py"
    click Helper "https://github.com/ujjawalps/healthsavvy/blob/main/src/helper.py"
    click StoreIndex "https://github.com/ujjawalps/healthsavvy/blob/main/store_index.py"
    click MedicalPDF "https://github.com/ujjawalps/healthsavvy/blob/main/Data/Medical_book.pdf"
    click Req "https://github.com/ujjawalps/healthsavvy/blob/main/requirements.txt"
    click Setup "https://github.com/ujjawalps/healthsavvy/blob/main/setup.py"
    click Runtime "https://github.com/ujjawalps/healthsavvy/blob/main/runtime.txt"
```
