# jatin-12-2002/e-commerce_chatbot architecture

> Architecture diagram of the GitHub repository jatin-12-2002/e-commerce_chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jatin-12-2002/e-commerce_chatbot
- Repository: https://github.com/jatin-12-2002/e-commerce_chatbot

## Overview

1. **Overall shape**
   - This repo is a **Flask-based chatbot application** wrapped around a **RAG pipeline**. The browser talks to Flask, Flask orchestrates retrieval plus LLM generation, and the answer is rendered back into a chat UI.

2. **User-facing layer**
   - `templates/chat.html` defines the single-page chat experience.
   - `static/script.js` handles client-side interaction and likely polling for task completion.
   - `static/style.css` provides the presentation layer.
   - `app.py` serves this UI and exposes the backend chat endpoints.

3. **Core backend entrypoint**
   - `app.py` is the main runtime boundary for the application.
   - It is the likely place where Flask routes, session/chat handling, and async task submission are wired together.
   - Based on the README, it also likely integrates the background worker flow used to avoid long LLM response timeouts.

4. **RAG domain package**
   - The `ecommbot/` package contains the chatbot’s actual retrieval-generation logic.
   - `model.py` centralizes model and embedding setup.
   - `retrieval_generation.py` likely builds the retrieval chain and answer generation flow.
   - `data_converter.py` and `ingest.py` handle turning raw dataset rows into retrievable documents and loading them into the vector store.

5. **Data ingestion path**
   - The source dataset is `data/flipkart_product_review.csv`.
   - Reviews, ratings, summaries, and product titles are converted into document-like records with metadata.
   - Those documents are then ingested into the vector database for semantic search.

6. **Vector retrieval layer**
   - The README identifies **AstraDB** as the vector store.
   - Embeddings come from **sentence-transformers/all-mpnet-base-v2**.
   - The retrieval subsystem uses semantic similarity to pull relevant product reviews before generation.

7. **LLM generation layer**
   - The README says the generator model is **LLaMA 3.1 8B via Ollama**.
   - This is the synthesis step after retrieval: retrieved review context is passed to the model to produce the final response.
   - The architecture is therefore not just a raw chatbot; it is a **retrieval-augmented answerer grounded in product reviews**.

8. **Conversation state**
   - The project uses a **history-aware RAG** approach.
   - Chat history is part of the request context so follow-up questions can reference prior turns.
   - This makes the boundary between stateless web requests and stateful conversation management important in the diagram.

9. **Asynchronous execution path**
   - The README describes **Redis + Celery** for long-running inference.
   - The architecture is: browser submits a query, Flask enqueues work, a Celery worker performs retrieval + LLM inference, and the browser polls for the result.
   - This is a key runtime boundary because it decouples UI responsiveness from model latency.

10. **External services**
   - **AstraDB** stores and serves vector embeddings.
   - **Ollama** hosts the local LLaMA runtime.
   - **Redis** acts as the broker for background tasks.
   - These are the main non-local dependencies that materially shape the system diagram.

11. **Build and packaging**
   - `setup.py`, `requirements.txt`, and `ecommbot/__init__.py` indicate a Python package layout rather than a monolithic script.
   - `notebook/research.ipynb` is exploratory and supports development, but it is not part of the production request flow.

12. **Deployment boundary**
   - The README describes running the app with **Gunicorn** and optionally placing **Nginx** in front on AWS EC2.
   - In production, traffic flows from the browser to Nginx, then to Gunicorn/Flask, then to the async worker or retrieval stack.

13. **End-to-end data flow**
   - Offline: CSV dataset → document conversion → embedding creation → AstraDB vector indexing.
   - Online: user question → Flask endpoint → retrieval from AstraDB → LLaMA generation via Ollama → response returned to chat UI.
   - If long-running, the online path goes through Celery/Redis before the response reaches the frontend.

14. **What to draw as the main diagram boxes**
   - Frontend chat UI
   - Flask application/API
   - Celery worker + Redis broker
   - RAG pipeline package (`data_converter`, `ingest`, `retrieval_generation`, `model`)
   - AstraDB vector store
   - Ollama LLaMA inference runtime
   - CSV dataset as the offline source of truth

Main entry points: [`app.py`](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py) (Flask app), [`ecommbot/retrieval_generation.py`](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/retrieval_generation.py) (RAG chain), [`ecommbot/ingest.py`](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/ingest.py) (Ingest), [`templates/chat.html`](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/templates/chat.html) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_chat_ui["Chat UI<br/>template<br/>[chat.html]"]
  node_client_js["Client JS<br/>browser script<br/>[script.js]"]
  node_styles["Styles<br/>css<br/>[style.css]"]
end

subgraph group_backend["Backend"]
  node_flask_app["Flask app<br/>web app<br/>[app.py]"]
  node_chat_state(("Chat state<br/>conversation<br/>[app.py]"))
  node_task_queue["Task queue<br/>async jobs<br/>[app.py]"]
  node_celery_worker["Celery worker<br/>async worker"]
end

subgraph group_rag["RAG pipeline"]
  node_data_converter["Data converter<br/>ingest transform<br/>[data_converter.py]"]
  node_ingest["Ingest<br/>indexing<br/>[ingest.py]"]
  node_retrieval_gen["RAG chain<br/>retrieval+generation"]
  node_model_setup["Model setup<br/>embeddings/llm config<br/>[model.py]"]
  node_csv_data["Review CSV<br/>dataset"]
end

subgraph group_external["External services"]
  node_redis_broker[("Redis<br/>broker")]
  node_astra_db[("AstraDB<br/>vector store")]
  node_ollama_llm[("Ollama LLM<br/>local model host")]
  node_embed_model["Embeddings<br/>sentence-transformers"]
  node_gunicorn["Gunicorn<br/>wsgi server"]
  node_nginx["Nginx<br/>reverse proxy"]
end

node_client_js -->|"chat requests"| node_flask_app
node_chat_ui -->|"loads UI"| node_client_js
node_styles -->|"styles"| node_chat_ui
node_flask_app -->|"manages"| node_chat_state
node_flask_app -->|"enqueue"| node_task_queue
node_task_queue -->|"brokered by"| node_redis_broker
node_redis_broker -->|"delivers jobs"| node_celery_worker
node_celery_worker -->|"runs"| node_retrieval_gen
node_retrieval_gen -->|"uses"| node_model_setup
node_retrieval_gen -->|"retrieves from"| node_astra_db
node_retrieval_gen -->|"generates via"| node_ollama_llm
node_model_setup -->|"configures"| node_embed_model
node_data_converter -->|"reads"| node_csv_data
node_ingest -->|"prepares"| node_data_converter
node_ingest -->|"indexes"| node_astra_db
node_ingest -->|"embeds with"| node_embed_model
node_gunicorn -->|"serves"| node_flask_app
node_nginx -->|"proxies"| node_gunicorn
node_flask_app -->|"invokes"| node_retrieval_gen
node_flask_app -->|"delegates"| node_celery_worker

click node_chat_ui "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/templates/chat.html"
click node_client_js "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/static/script.js"
click node_styles "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/static/style.css"
click node_flask_app "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py"
click node_chat_state "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py"
click node_task_queue "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py"
click node_data_converter "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/data_converter.py"
click node_ingest "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/ingest.py"
click node_retrieval_gen "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/retrieval_generation.py"
click node_model_setup "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/model.py"
click node_csv_data "https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/data/flipkart_product_review.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_ui,node_client_js,node_styles toneBlue
class node_flask_app,node_chat_state,node_task_queue,node_celery_worker toneAmber
class node_data_converter,node_ingest,node_retrieval_gen,node_model_setup,node_csv_data toneMint
class node_redis_broker,node_astra_db,node_ollama_llm,node_embed_model,node_gunicorn,node_nginx toneRose
```

## Components

### Frontend

Browser chat experience and client-side interaction.

- [Chat UI](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/templates/chat.html): template · Single-page chat interface rendered in the browser. · `templates/chat.html`
- [Client JS](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/static/script.js): browser script · Handles chat interactions and result polling. · `static/script.js`
- [Styles](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/static/style.css): css · Presentation layer for the chat interface. · `static/style.css`

### Backend

Flask app, async task flow, and orchestration boundaries.

- [Flask app](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py): web app · Main application entrypoint and HTTP route boundary. · `app.py`
- [Chat state](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py): conversation · Session and history-aware conversation context. · `app.py`
- [Task queue](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/app.py): async jobs · Background execution path for long-running inference requests. · `app.py`
- **Celery worker**: async worker · Runs retrieval and generation outside the request thread.

### RAG pipeline

Ingestion, retrieval, and generation components.

- [Data converter](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/data_converter.py): ingest transform · Turns CSV rows into retrievable document records. · `ecommbot/data_converter.py`
- [Ingest](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/ingest.py): indexing · Loads prepared documents into the vector store. · `ecommbot/ingest.py`
- [RAG chain](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/retrieval_generation.py): retrieval+generation · Builds retrieval and answer synthesis for chat queries. · `ecommbot/retrieval_generation.py`
- [Model setup](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/ecommbot/model.py): embeddings/llm config · Centralizes embedding and model initialization. · `ecommbot/model.py`
- [Review CSV](https://github.com/jatin-12-2002/e-commerce_chatbot/blob/main/data/flipkart_product_review.csv): dataset · Offline source data for product review grounding. · `data/flipkart_product_review.csv`

### External services

Runtime and infrastructure dependencies outside the repository.

- **Redis**: broker · Message broker for background task delivery.
- **AstraDB**: vector store · Stores embeddings and supports semantic retrieval.
- **Ollama LLM**: local model host · Serves the LLaMA 3.1 8B generation runtime.
- **Embeddings**: sentence-transformers · Semantic embedding model used for indexing and search.
- **Gunicorn**: wsgi server · Production process manager for the Flask app.
- **Nginx**: reverse proxy · Optional front door for production deployment.

## Connections

- Client JS → Flask app: chat requests · Sends user prompts and polls for completion.
- Chat UI → Client JS: loads UI · Browser page includes the interaction logic.
- Styles → Chat UI: styles · Provides presentation for the chat interface.
- Flask app → Chat state: manages · Stores and reads conversational context.
- Flask app → Task queue: enqueue · Submits long-running inference jobs when needed.
- Task queue → Redis: brokered by · Uses Redis for asynchronous job delivery.
- Redis → Celery worker: delivers jobs · Hands queued tasks to the worker process.
- Celery worker → RAG chain: runs · Executes retrieval-augmented answer generation.
- RAG chain → Model setup: uses · Consumes shared model and embedding initialization.
- RAG chain → AstraDB: retrieves from · Fetches semantically relevant review context.
- RAG chain → Ollama LLM: generates via · Calls the local LLaMA runtime for synthesis.
- Model setup → Embeddings: configures · Sets up the embedding model used for retrieval.
- Data converter → Review CSV: reads · Converts the review dataset into documents.
- Ingest → Data converter: prepares · Uses converted records for indexing.
- Ingest → AstraDB: indexes · Writes embeddings and metadata into the vector store.
- Ingest → Embeddings: embeds with · Creates vector representations during ingestion.
- Gunicorn → Flask app: serves · Runs the Flask application in production.
- Nginx → Gunicorn: proxies · Optional reverse proxy in front of the WSGI server.
- Flask app → RAG chain: invokes · Triggers the RAG pipeline for synchronous or async execution paths.
- Flask app → Celery worker: delegates · Hands off heavy work to the background worker flow.
