# tomlin7/ecommerce-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/tomlin7/ecommerce-chatbot
- Repository: https://github.com/tomlin7/ecommerce-chatbot

## Overview

##### Project type and purpose
- This is a full-stack e-commerce application with a modern Next.js/React frontend (apps/web/) and a Flask-based REST API backend (server/).
- It integrates AI capabilities (Google Gemini via LangChain) and a vector search engine (Pinecone) for semantic product discovery and a conversational shopping assistant.

##### File structure
- apps/web/
– Next.js “app” directory organizes pages (cart, chat, login, products, profile, register).
– components/ holds reusable UI pieces (chat, products, layout, ui primitives).
– lib/ api.ts and utils.ts wrap REST calls and misc helpers.
– context/ AuthContext manages JWT authentication state.
– next.config.js, tailwind.config.ts, tsconfig.json, postcss.config.js—build & styling setups.
- server/
– app.py / run.py / start.sh bootstrap the Flask app under gunicorn.
– routes/ define REST endpoints (auth, cart, chat, like, product).
– services/ contain business logic (auth_service.py, cart_service.py, chat_service.py, like_service.py, product_service.py, vector_service.py).
– models/ define ORM classes (SQLAlchemy) for User, Product, Cart, ChatSession, Message, UserLike.
– migrations/ hold Alembic scripts for database schema evolution.
– utils/ database seeder and logger configuration.
– config.py holds environment-specific settings (.env.example provided).
- External integration points: Pinecone (vector database), Google AI Studio (Gemini), Sentence Transformers, LangChain orchestration.

##### README for additional insights
- Tech stack summary confirms React/Next.js, Flask, JWT auth, Pinecone, LangChain, Google Gemini Flash 2.0, SQLite (dev), embedding engines.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        CLB(("Client / Browser")):::client
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        FE["Next.js / React\n(apps/web/)"]:::frontend
        Pages["Pages (cart, chat, login,\nproducts, profile, register)"]:::frontend
        Components["Reusable UI Components"]:::frontend
        AuthCtx["AuthContext (JWT state)"]:::frontend
        APIHelpers["API Helpers (api.ts)"]:::frontend
        Utils["Utility Functions (utils.ts)"]:::frontend
        ConfigFiles["Config & Build Files"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API"
        direction TB
        FlaskApp["Flask App\n(server/app.py)"]:::backend
        Runner["Gunicorn Runner\n(server/run.py)"]:::backend
        Startup["Startup Script\n(server/start.sh)"]:::backend
        Config["Config & Env\n(server/config.py\n.server/.env.example\ngunicorn.conf.py)"]:::backend
        subgraph "Routes (Controllers)"
            direction TB
            AuthRoutes["Auth Routes"]:::backend
            CartRoutes["Cart Routes"]:::backend
            ChatRoutes["Chat Routes"]:::backend
            LikeRoutes["Like Routes"]:::backend
            ProdRoutes["Product Routes"]:::backend
        end
        subgraph "Services (Business Logic)"
            direction TB
            AuthSvc["auth_service.py"]:::backend
            CartSvc["cart_service.py"]:::backend
            ChatSvc["chat_service.py"]:::backend
            LikeSvc["like_service.py"]:::backend
            ProdSvc["product_service.py"]:::backend
            VecSvc["vector_service.py"]:::backend
        end
        subgraph "Models (ORM)"
            direction TB
            UserModel["user.py"]:::backend
            ProductModel["product.py"]:::backend
            CartModel["cart.py"]:::backend
            ChatSessionModel["chat_session.py"]:::backend
            MessageModel["message.py"]:::backend
            UserLikeModel["user_like.py"]:::backend
        end
        subgraph "Utils & Scripts"
            direction TB
            Seeder["database_seeder.py"]:::backend
            LoggerCfg["logger_config.py"]:::backend
            IndexScript["index_all_products.py"]:::backend
        end
        subgraph "Migrations"
            direction TB
            AlembicCfg["alembic.ini/env.py\nscript.py.mako"]:::backend
            Versions["versions/*.py"]:::backend
        end
    end

    %% AI & Vector Services
    subgraph "AI & Search Services"
        direction TB
        LangChain["LangChain Orchestrator"]:::ai
        Gemini["Google Gemini Flash 2.0"]:::ai
        Pinecone["Pinecone Vector DB"]:::ai
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SQLDB["SQLite/Postgres\n(Database)"]:::data
    end

    %% Connections
    CLB -->|"1. HTTP(S) Requests"| FE
    FE -->|"2. REST API Calls\n(JWT Auth)"| FlaskApp
    FlaskApp -->|routes→services| AuthRoutes
    FlaskApp -->|routes→services| CartRoutes
    FlaskApp -->|routes→services| ChatRoutes
    FlaskApp -->|routes→services| LikeRoutes
    FlaskApp -->|routes→services| ProdRoutes

    AuthRoutes -->|calls| AuthSvc
    CartRoutes -->|calls| CartSvc
    ChatRoutes -->|calls| ChatSvc
    LikeRoutes -->|calls| LikeSvc
    ProdRoutes -->|calls| ProdSvc

    AuthSvc -->|ORM| UserModel
    CartSvc -->|ORM| CartModel
    ChatSvc -->|ORM| ChatSessionModel
    ChatSvc -->|LLM & Vector| LangChain
    LikeSvc -->|ORM| UserLikeModel
    ProdSvc -->|ORM| ProductModel
    ProdSvc -->|Vector Indexing| VecSvc

    VecSvc -->|Pinecone API| Pinecone
    LangChain -->|LLM Calls| Gemini

    %% Data persistence
    UserModel -->|CRUD| SQLDB
    ProductModel -->|CRUD| SQLDB
    CartModel -->|CRUD| SQLDB
    ChatSessionModel -->|CRUD| SQLDB
    MessageModel -->|CRUD| SQLDB
    UserLikeModel -->|CRUD| SQLDB
    AlembicCfg -->|migrations| Versions
    Versions -->|schema updates| SQLDB

    %% Click Events Frontend
    click FE "https://github.com/tomlin7/ecommerce-chatbot/tree/main/apps/web/"
    click Pages "https://github.com/tomlin7/ecommerce-chatbot/tree/main/apps/web/app/"
    click Components "https://github.com/tomlin7/ecommerce-chatbot/tree/main/apps/web/components/"
    click AuthCtx "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/context/AuthContext.tsx"
    click APIHelpers "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/lib/api.ts"
    click Utils "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/lib/utils.ts"
    click ConfigFiles "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/next.config.js"
    click ConfigFiles "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/tailwind.config.ts"
    click ConfigFiles "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/tsconfig.json"
    click ConfigFiles "https://github.com/tomlin7/ecommerce-chatbot/blob/main/apps/web/postcss.config.js"

    %% Click Events Backend
    click FlaskApp "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/app.py"
    click Runner "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/run.py"
    click Startup "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/start.sh"
    click Config "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/config.py"
    click Config "https://github.com/tomlin7/ecommerce-chatbot/blob/main/.env.example"
    click Config "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/gunicorn.conf.py"
    click AuthRoutes "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/routes/auth_routes.py"
    click CartRoutes "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/routes/cart_routes.py"
    click ChatRoutes "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/routes/chat_routes.py"
    click LikeRoutes "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/routes/like_routes.py"
    click ProdRoutes "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/routes/product_routes.py"
    click AuthSvc "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/services/auth_service.py"
    click CartSvc "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/services/cart_service.py"
    click ChatSvc "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/services/chat_service.py"
    click LikeSvc "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/services/like_service.py"
    click ProdSvc "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/services/product_service.py"
    click VecSvc "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/services/vector_service.py"
    click UserModel "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/models/user.py"
    click ProductModel "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/models/product.py"
    click CartModel "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/models/cart.py"
    click ChatSessionModel "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/models/chat_session.py"
    click MessageModel "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/models/message.py"
    click UserLikeModel "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/models/user_like.py"
    click Seeder "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/utils/database_seeder.py"
    click LoggerCfg "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/utils/logger_config.py"
    click IndexScript "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/scripts/index_all_products.py"
    click AlembicCfg "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/migrations/alembic.ini"
    click AlembicCfg "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/migrations/env.py"
    click AlembicCfg "https://github.com/tomlin7/ecommerce-chatbot/blob/main/server/migrations/script.py.mako"
    click Versions "https://github.com/tomlin7/ecommerce-chatbot/tree/main/server/migrations/versions/"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#b3d4fc,stroke:#333,stroke-width:1px
    classDef backend fill:#b2f7b2,stroke:#333,stroke-width:1px
    classDef ai fill:#ffd1a9,stroke:#333,stroke-width:1px
    classDef data fill:#e3c8ff,stroke:#333,stroke-width:1px
```
