# preethicoder/kitchenremedykid_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/preethicoder/kitchenremedykid_chatbot
- Repository: https://github.com/preethicoder/kitchenremedykid_chatbot

## Overview

##### Project Type and Purpose
- HomeCure-Kids is a full-stack web application:
- Frontend: React SPA providing a conversational UI.
- Backend: FastAPI service orchestrating AI retrieval, response generation, PDF creation, image generation, and email delivery.
- Purpose: Offer interactive, kitchen-based home remedy suggestions for kids using OpenAI/GPT, LangChain, FAISS, web-scraped sources, and downloadable/exportable assets (PDFs, visuals).

##### File Structure Highlights
- Top-level (Backend)
- main.py – FastAPI app and endpoint definitions.
- home_cure_kids.py – Core chat logic invoking LangChain, OpenAI, retrieval.
- retrieverFAISS.py – Builds/queries FAISS vector index.
- relevance_score.py – Scores the relevance of generated remedies.
- pdf_utils.py – Formats and exports remedy content to PDF.
- email_utils.py – Sends remedy PDFs via SMTP.
- visual.py – Generates step-by-step illustrations (DALL·E).
- faiss_index/ – Persisted FAISS index files.
- Frontend (homecure-frontend/)
- React source under src/: App.js, index.js, UI components.
- Public assets and manifest for PWA.
- Config & Tests
- see test_kitchen_remedy_chatbot.py for end-to-end tests.
- seen_urls.txt logs scraping history.

##### Key Architectural Components
a. Client (Browser/React SPA)
b. API Layer (FastAPI)
c. Retrieval Engine (LangChain + FAISS)
d. AI Services (OpenAI GPT for text, DALL·E for visuals)
e. Data & Storage
- Local FAISS index on disk
- Temporary/Generated PDFs
- Scraped content cache (seen_urls.txt)
f. Utility Services
- PDF export service (pdf_utils)
- Email service (email_utils)
- Relevance scorer (relevance_score)

##### Interactions & Data Flow
1) User sends symptom query via React UI.
2) Frontend issues HTTP POST → FastAPI endpoint (/chat).
3) FastAPI → retrieverFAISS: perform vector similarity search on FAISS index.
4) Retrieved docs + chat history fed into LangChain prompt → OpenAI GPT call.
5) GPT returns remedy text → FastAPI passes to relevance_score for quality check.
6) Optionally:
- visual.py requests DALL·E to generate step visuals.
- pdf_utils assembles text + visuals into PDF.
- email_utils sends PDF to user’s email.
7) Response (text + image URLs + PDF link) returned to React UI.

##### Architectural Patterns & Principles
- Layered Architecture: Clear separation of UI, API, business logic, and infrastructure.
- Modular Python services: Each utility (PDF, email, retrieval) encapsulated in its own module.
- Single-page Application (SPA) for responsive UX.
- Vector search + LLM chain for context-aware retrieval.
- Asynchronous I/O in FastAPI for non-blocking calls to OpenAI and email services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (React SPA)"
        direction TB
        App["App.js"]:::frontend
        IndexJS["index.js"]:::frontend
        PublicHTML["index.html"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (FastAPI)"
        direction TB
        FastAPI["main.py"]:::backend
    end

    %% Core AI Engine
    subgraph "Core AI Engine"
        direction TB
        ChatLogic["home_cure_kids.py"]:::backend
    end

    %% Retrieval Engine
    subgraph "Retrieval Engine"
        direction TB
        Retriever["retrieverFAISS.py"]:::backend
        subgraph "FAISS Index Storage"
            direction TB
            FAISS_IDX1["index.faiss"]:::datastore
            FAISS_IDX2["index.pkl"]:::datastore
        end
    end

    %% AI Services
    subgraph "AI Services"
        direction TB
        GPT["OpenAI GPT"]:::external
        DALLE["DALL·E"]:::external
        Visual["visual.py"]:::backend
    end

    %% Delivery Services
    subgraph "Delivery"
        direction TB
        PDFUtil["pdf_utils.py"]:::backend
        PDFOut["remedy.pdf"]:::datastore
        EmailUtil["email_utils.py"]:::backend
    end

    %% Utilities & Data Stores
    subgraph "Utilities & Data"
        direction TB
        Relevance["relevance_score.py"]:::backend
        Cache["seen_urls.txt"]:::datastore
    end

    %% Testing
    Test["test_kitchen_remedy_chatbot.py"]:::backend

    %% Data Flow
    App -->|"HTTP POST /chat"| FastAPI
    FastAPI -->|"invoke Retriever"| Retriever
    Retriever -->|"FAISS query"| FAISS_IDX1
    Retriever -->|"FAISS query"| FAISS_IDX2
    Retriever -->|"docs + history"| ChatLogic
    ChatLogic -->|"LLM prompt"| GPT
    ChatLogic -->|"visual request"| DALLE
    ChatLogic -->|"raw remedy text"| Relevance
    Relevance -->|"score pass/fail"| ChatLogic
    ChatLogic -->|"assemble visuals"| Visual
    ChatLogic -->|"generate PDF"| PDFUtil
    PDFUtil -->|"writes"| PDFOut
    ChatLogic -->|"send PDF"| EmailUtil
    EmailUtil -->|"SMTP"| EmailUtil
    ChatLogic -->|"cache URLs"| Cache
    FastAPI -->|"response"| App
    Test -->|"e2e test"| FastAPI

    %% Click Events
    click App "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/homecure-frontend/src/App.js"
    click IndexJS "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/homecure-frontend/src/index.js"
    click PublicHTML "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/homecure-frontend/public/index.html"
    click FastAPI "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/main.py"
    click ChatLogic "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/home_cure_kids.py"
    click Retriever "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/retrieverFAISS.py"
    click FAISS_IDX1 "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/faiss_index/index.faiss"
    click FAISS_IDX2 "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/faiss_index/index.pkl"
    click Visual "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/visual.py"
    click PDFUtil "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/pdf_utils.py"
    click PDFOut "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/pdfs/remedy.pdf"
    click EmailUtil "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/email_utils.py"
    click Relevance "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/relevance_score.py"
    click Cache "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/seen_urls.txt"
    click Test "https://github.com/preethicoder/kitchenremedykid_chatbot/blob/main/test_kitchen_remedy_chatbot.py"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,color:#0B5345;
    classDef backend fill:#A9DFBF,stroke:#196F3D,color:#0E6655;
    classDef external fill:#F9E79F,stroke:#B9770E,color:#7E5109;
    classDef datastore fill:#D5D8DC,stroke:#424949,color:#1B2631;
```
