# phuchuwu/cellphones_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/phuchuwu/cellphones_chatbot
- Repository: https://github.com/phuchuwu/cellphones_chatbot

## Overview

##### Project type and purpose
- This is a full-stack web application (CellphoneS Chatbot) that uses a Retrieval-Augmented Generation (RAG) pattern to power a customer-support chatbot.
- Purpose: scrape product/policy/FAQ data from CellphoneS, index it via FAISS + Sentence Transformers, query it at runtime, augment LLM (via Groq API) responses, and expose a web chat UI.

##### File structure
- Top-level:
- app.py: Flask server & API endpoints
- rag_pipeline.py: Orchestrates RAG (search + LLM call)
- crawldata/: Selenium scripts to scrape CellphoneS website
- data/: scraped JSON artifacts
- embeddings/: FAISS index + metadata
- utils/: chunking & embedding helpers
- frontend/: static web UI (HTML/CSS/JS)
- Config & deps:
- requirements.txt, .env (Groq API key), .gitignore
- Patterns:
- One monolithic backend with clear separation:
– Data ingestion layer (crawldata + utils)
– Indexing layer (utils.embedding + rag_pipeline building index)
– Serving layer (Flask + rag_pipeline query)
- RAG pattern: split → embed → index → search → LLM

##### README for additional insights
Frontend ↔ Flask Backend ↔ LLM + FAISS RAG
- Technology stack: Python 3.10+, Flask, Selenium, Sentence Transformers, FAISS, Groq LLM, scikit-learn, pickle, CORS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Web UI Layer
    subgraph "Web UI (HTML/CSS/JS)"
        direction TB
        UI_HTML["index.html"]:::ui
        UI_CSS["style.css"]:::ui
        UI_JS["script.js"]:::ui
    end

    %% Backend Layer
    subgraph "Flask Backend"
        direction TB
        API["API Layer (app.py)"]:::backend
        RAG["RAG Pipeline (rag_pipeline.py)"]:::backend
    end

    %% Data Storage
    subgraph "Vector Store & Metadata"
        direction TB
        FAISS["faiss_index.bin"]:::data
        META["metadata.pkl"]:::data
    end

    subgraph "Scraped Data Store"
        direction TB
        FAQ["faq.json"]:::data
        POLICY["policy_dataset.json"]:::data
        PRODUCT["product_details.json"]:::data
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        CHUNK["chunking.py"]:::util
        EMB["embedding.py"]:::util
    end

    %% Scraper Workers
    subgraph "Scraper Workers (Selenium)"
        direction TB
        SCR1["crawl_description.py"]:::util
        SCR2["crawl_faq.py"]:::util
        SCR3["crawl_name_and_url.py"]:::util
        SCR4["crawl_policy.py"]:::util
        SCR5["crawl_spec_and_variant.py"]:::util
    end

    %% External Service
    LLM["Groq API (LLM Service)"]:::external

    %% User Flow
    UI_JS -->|"POST /chat\nHTTP/JSON"| API
    UI_JS -.->|CORS| API
    API -->|"invoke RAG"| RAG
    RAG -->|"vector search"| FAISS
    RAG -->|"load metadata"| META
    RAG -->|"LLM call"| LLM
    LLM -->|"response"| RAG
    RAG -->|"answer with citations"| API
    API -->|"JSON response"| UI_JS

    %% Offline Ingestion Flow
    SCR1 --> FAQ
    SCR2 --> FAQ
    SCR3 --> PRODUCT
    SCR4 --> POLICY
    SCR5 --> PRODUCT
    FAQ --> CHUNK
    POLICY --> CHUNK
    PRODUCT --> CHUNK
    CHUNK --> EMB
    EMB --> FAISS

    %% Click Events
    click UI_HTML "https://github.com/phuchuwu/cellphones_chatbot/blob/main/frontend/index.html"
    click UI_CSS "https://github.com/phuchuwu/cellphones_chatbot/blob/main/frontend/style.css"
    click UI_JS "https://github.com/phuchuwu/cellphones_chatbot/blob/main/frontend/script.js"
    click API "https://github.com/phuchuwu/cellphones_chatbot/blob/main/app.py"
    click RAG "https://github.com/phuchuwu/cellphones_chatbot/blob/main/rag_pipeline.py"
    click FAISS "https://github.com/phuchuwu/cellphones_chatbot/blob/main/embeddings/faiss_index.bin"
    click META "https://github.com/phuchuwu/cellphones_chatbot/blob/main/embeddings/metadata.pkl"
    click FAQ "https://github.com/phuchuwu/cellphones_chatbot/blob/main/data/faq.json"
    click POLICY "https://github.com/phuchuwu/cellphones_chatbot/blob/main/data/policy_dataset.json"
    click PRODUCT "https://github.com/phuchuwu/cellphones_chatbot/blob/main/data/product_details.json"
    click SCR1 "https://github.com/phuchuwu/cellphones_chatbot/blob/main/crawldata/crawl_description.py"
    click SCR2 "https://github.com/phuchuwu/cellphones_chatbot/blob/main/crawldata/crawl_faq.py"
    click SCR3 "https://github.com/phuchuwu/cellphones_chatbot/blob/main/crawldata/crawl_name_and_url.py"
    click SCR4 "https://github.com/phuchuwu/cellphones_chatbot/blob/main/crawldata/crawl_policy.py"
    click SCR5 "https://github.com/phuchuwu/cellphones_chatbot/blob/main/crawldata/crawl_spec_and_variant.py"
    click CHUNK "https://github.com/phuchuwu/cellphones_chatbot/blob/main/utils/chunking.py"
    click EMB "https://github.com/phuchuwu/cellphones_chatbot/blob/main/utils/embedding.py"

    %% Styles
    classDef ui fill:#DCEFFF,stroke:#0366d6;
    classDef backend fill:#D5E8D4,stroke:#82B366;
    classDef data fill:#F8CECC,stroke:#B85450;
    classDef util fill:#FFF2CC,stroke:#D6B656;
    classDef external fill:#E1D5E7,stroke:#9673A6;
```
