# akashpaul2030/ecommerce_chatbot_recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/akashpaul2030/ecommerce_chatbot_recommendation
- Repository: https://github.com/akashpaul2030/ecommerce_chatbot_recommendation

## Overview

##### Project type and purpose
- This is a full-stack e-commerce recommendation system that combines a React frontend with a Python/FastAPI backend.
- It implements a Retrieval-Augmented Generation (RAG) pipeline to allow users to search for products in natural language and get semantically matched results.

##### File structure
- Top-level “frontend” and “backend” folders indicate a clear separation of concerns:
- frontend/… – React application with modular components, pages, and an API service layer (api.js).
- backend/… – Python package organized into subpackages:
- data/ – product data ingestion and processing
- database/ – vector store abstraction for embeddings
- rag/ – embedding generation and retrieval logic
- api/ – FastAPI application and route definitions
- utils/ – query parsing utilities
- Configuration files at the root (config.py, requirements.txt, setup.py) and docker assets (Dockerfile.* and docker-compose.dev.yml) support containerized development and deployment.

##### README for additional insights
- The README confirms a layered architecture:
- Data Processing Layer
- Vector Database
- RAG Engine (embeddings + retriever)
- RESTful API
- Frontend details: React components, state management, responsive design.

a. Main components
1. User (Browser/Mobile)
2. React Frontend
– UI Components (ChatInterface, ProductCard, SearchFilters)
– API Service (api.js)
3. Backend API (FastAPI/Uvicorn)
4. Data Processing Layer (data_processor, product_catalog)
5. Vector Store (vector_store.py – could be FAISS, Melvus, etc.)
6. RAG Engine
– Embedding Service (embeddings.py)
– Retriever (retriever.py)
7. Database / Persistent Storage (original TSV or SQL/NoSQL store)
8. External LLM or Vector DB (e.g., Melvus, OpenAI API)
9. Configuration & Deployment (config.py, Docker, docker-compose)
b. Relationships and interactions
- User → React UI → *GET /products* or *POST /query* → FastAPI endpoints
- FastAPI → QueryParser → DataProcessor → EmbeddingService → VectorStore → Retriever → returns ranked product IDs → FastAPI → React UI → User
- React UI also fetches filtering options from *GET /filters*
- DataProcessor ingests raw product data into the VectorStore on startup or via batch jobs
- Docker Compose orchestrates Frontend and Backend containers, with environment configs pointing to each other
c. Architectural patterns & design principles
- Layered architecture (presentation, application/API, domain/data, infrastructure)
- Separation of concerns (frontend vs. backend, data ingestion vs. retrieval)
- Pipeline pattern in RAG (text → embeddings → vector search → LLM augmentation)
- Modular React components for reusability and maintainability
d. Key technologies, frameworks, and libraries
- Frontend: React, JSX, CSS modules, npm
- Backend: Python 3.8+, FastAPI, Uvicorn
- Embeddings: scikit-learn TF-IDF or sentence-transformers (optional), Melvus integration
- Vector DB: custom VectorStore abstraction (with possible backends like FAISS, Pinecone, Qdrant)
- Containerization: Docker, Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        User["User (Browser/Mobile)"]:::external
        ReactApp["React Frontend Application"]:::frontend
        ChatInterface["ChatInterface Component"]:::frontend
        ProductCard["ProductCard Component"]:::frontend
        SearchFilters["SearchFilters Component"]:::frontend
        APIService["API Service Layer (api.js)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        subgraph "API Layer"
            FastAPIApp["FastAPI App (app.py)"]:::backend
            FastAPIRoutes["API Routes (routes.py)"]:::backend
        end
        subgraph "Business Logic"
            QueryParser["Query Parsing Utility"]:::backend
            EmbeddingService["Embedding Service"]:::backend
            Retriever["Retriever Service"]:::backend
        end
        subgraph "Data Layer"
            DataProcessor["Data Processor"]:::datalayer
            ProductCatalog["Product Catalog"]:::datalayer
            VectorStore["Vector Store Abstraction"]:::datalayer
            PersistentStorage["Persistent Storage (SQL/NoSQL)"]:::datalayer
        end
    end

    %% External Dependencies
    ExternalLLM["External LLM / Melvus"]:::external
    DockerCompose["Docker Compose"]:::infra
    Config["Configuration (config.py)"]:::infra
    DockerBackend["Dockerfile.backend.dev"]:::infra
    DockerFrontend["Dockerfile.frontend.dev"]:::infra

    %% Flow Connections
    User -->|uses UI| ReactApp
    ReactApp -->|renders| ChatInterface
    ReactApp -->|renders| ProductCard
    ReactApp -->|renders| SearchFilters
    ReactApp -->|calls| APIService
    APIService -->|GET /products, POST /query| FastAPIRoutes
    FastAPIRoutes -->|handled by| FastAPIApp
    FastAPIApp -->|parse query| QueryParser
    QueryParser -->|process| DataProcessor
    DataProcessor -->|load catalog| ProductCatalog
    ProductCatalog -->|ingest embeddings| VectorStore
    FastAPIApp -->|embed text| EmbeddingService
    EmbeddingService -->|"search"| VectorStore
    VectorStore -->|retrieve IDs| Retriever
    Retriever -->|return results| FastAPIApp
    FastAPIApp -->|response| APIService
    APIService -->|return data| ReactApp
    ReactApp -->|display results| User

    %% Optionally fetch filters
    ReactApp -->|GET /filters| FastAPIRoutes

    %% External LLM
    EmbeddingService -->|optionally uses| ExternalLLM
    VectorStore -->|backend store| ExternalLLM

    %% Deployment
    DockerCompose -->|orchestrates| ReactApp
    DockerCompose -->|orchestrates| FastAPIApp
    DockerCompose -->|uses| Config
    DockerCompose -->|builds| DockerBackend
    DockerCompose -->|builds| DockerFrontend

    %% Click Events
    click ReactApp "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/tree/main/frontend/src"
    click ChatInterface "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/frontend/src/components/ChatInterface.jsx"
    click ProductCard "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/frontend/src/components/ProductCard.jsx"
    click SearchFilters "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/frontend/src/components/SearchFilters.jsx"
    click APIService "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/frontend/src/services/api.js"
    click FastAPIApp "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/api/app.py"
    click FastAPIRoutes "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/api/routes.py"
    click DataProcessor "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/data/data_processor.py"
    click ProductCatalog "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/data/product_catalog.py"
    click VectorStore "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/database/vector_store.py"
    click EmbeddingService "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/rag/embeddings.py"
    click Retriever "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/rag/retriever.py"
    click QueryParser "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/backend/utils/query_parser.py"
    click Config "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/config.py"
    click DockerCompose "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/docker-compose.dev.yml"
    click DockerBackend "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/Dockerfile.backend.dev"
    click DockerFrontend "https://github.com/akashpaul2030/ecommerce_chatbot_recommendation/blob/main/Dockerfile.frontend.dev"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datalayer fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
