Smart E‑Commerce

An AI‑assisted e‑commerce demo with product browsing, cart and ordering flows, plus a real‑time chat assistant that can recommend products, answer questions, and help with order actions. The app is split into a Vite + React client and a Node.js + Express server backed by PostgreSQL with pgvector embeddings. The assistant is powered by LangChain and OpenAI.

User Experience

• Interactive Chat Assistant: A context-aware bot that acts as a sales associate. It can:
  • Recommend products based on natural language queries (e.g., "Show me gifts for a toddler").
  • Personalize suggestions based on your order history.
  • Answer specific questions about store policies (Shipping, Returns) using vector search.
  • Check order status and show line-item details.
  • Securely cancel orders through a multi-step verification flow.
• Dynamic UI: The chat pushes interactive product cards to the interface, not just text.
• Full E-Commerce Flow: Product browsing, detailed views, shopping cart management, and checkout.
• Real-Time Updates: Order status changes and chat responses stream in real-time via WebSockets.

Technical Highlights

• Hybrid Search Engine: Combines Vector Search (Cosine Similarity via pgvector) for semantic understanding and SQL Search (ILIKE) for keyword fallback.
• Agentic Workflow: Powered by LangGraph to manage conversation state and intelligently select tools.
• Secure Auth: Role-based authentication (Admin/User) using JWT and HTTP-only cookies.
• Database Management: Fully typed schema and migrations using Drizzle ORM.

---

Prerequisites

• Node.js 18+ and npm
• PostgreSQL 14+ with the pgvector extension
• An OpenAI API key

---

Environment Variables

Create a .env file in server/:

# Server
PORT=8080
NODE_ENV=development

# PostgreSQL (adjust to your database)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/smart_ecommerce

# Auth
JWT_SECRET=super-secret-string

# Admin bootstrap (bcrypt hash for your chosen admin password)
# Generate one with the command shown below in the Run section
ADMIN_HASH=$2a$10$ReplaceWithYourBcryptHash

# OpenAI
API_KEY=sk-...

Create a .env file in client/:

VITE_API_BASE_URL=http://localhost:8080

---

Database Setup (PostgreSQL)

1. Create a database (example shown):

CREATE DATABASE smart_ecommerce;

1. Enable pgvector in that database:

CREATE EXTENSION IF NOT EXISTS vector;

1. Apply Drizzle migrations (from server/):

cd server
npm install
npm run drizzle:push

1. Optional: Seed products/categories

• A sample file exists at server/products.sql. It references category IDs 5–9. Ensure your categories table contains matching rows or update the category_id values in the SQL to match your DB.
• You can import with psql or your favorite GUI:

# Example using psql (adjust connection/user/DB)
psql "postgresql://postgres:postgres@localhost:5432/smart_ecommerce" -f .\products.sql

1. Optional: Generate embeddings (requires API_KEY and existing rows):

# From server/
npm run seed:policy-embeddings
npm run seed:product-embeddings

---

Run The App (Windows PowerShell)

Install dependencies and start both server and client.

# 1) Install deps
cd server; npm install; cd ..
cd client; npm install; cd ..

# 2) Start the server (port 8080 by default)
cd server
npm run dev
# Keep this running

# 3) In a new terminal, start the client (Vite on 5173)
cd client
npm run dev

Client: http://localhost:5173

Admin Login (bootstrap)

On first server start, an admin account is created with email admin@local.com and the password hash from ADMIN_HASH. To generate a hash for a password of your choice (example: Admin@123), run in server/ after installing deps:

node -e "console.log(require('bcryptjs').hashSync('Admin@123', 10))"

Set the printed hash in server/.env as ADMIN_HASH, restart the server, then log in with:

• Email: admin@local.com
• Password: the plaintext you hashed (e.g., Admin@123)

---

Troubleshooting

• CORS/Network: Ensure VITE_API_BASE_URL matches your server URL and the server CORS list includes http://localhost:5173.
• DB Connection: Verify DATABASE_URL and that CREATE EXTENSION vector; ran in the correct database.
• Missing Admin: Re‑generate ADMIN_HASH, restart the server.
• OpenAI Errors: Confirm API_KEY is set and has access to the specified models.
• Embeddings: Run the seed scripts after products/documents exist.

---

Scripts Reference

• Server:
  • npm run dev — start server with ts-node + nodemon
  • npm run drizzle:push — apply migrations
  • npm run seed:policy-embeddings — embed policy documents
  • npm run seed:product-embeddings — embed products
• Client:
  • npm run dev — start Vite dev server
  • npm run build — production build
  • npm run preview — preview built client