Byteline — Conversational AI Shopping Assistant

A conversational commerce demo for laptops. Describe what you want in plain English — "show me laptops under $400 with 8GB RAM" — and a LangChain.js + OpenAI pipeline turns that into structured filters, queries a Postgres catalog, and returns matching product cards. Keep refining the conversation — "raise the budget to $600" — and the assistant merges new criteria into what's already been said.

Features

• Natural language product search by budget, RAM, storage, CPU/GPU, screen size, or brand
• Conversational filter refinement — only what you mention changes, the rest is preserved
• Cart & wishlist on top of the chat-driven results
• LangChain.js + OpenAI structured output (Zod function calling) for filter extraction, decoupled from reply generation
• Postgres-backed catalog, raw SQL, no ORM
• Stateless backend — cart, wishlist, and conversation history persist client-side only

Tech stack

Layer	Stack
Frontend	Vue 3, Pinia, Vite, vue-router
Backend	Node.js, Express, raw pg driver
AI / NLP	LangChain.js, OpenAI (function calling / structured output via Zod)
Database	PostgreSQL

Architecture

frontend/   Vue 3 SPA — chat UI, product grid, cart, wishlist (Pinia + localStorage)
backend/    Express API — routes → controllers → services → repositories
            LangChain.js pipeline for filter extraction/merge + reply generation
            Raw SQL against a Postgres "laptops" table

The backend is stateless: every chat request carries the shopper's current filter state, the backend merges in the new message and returns the full updated filter object, which the frontend persists and replays next turn. See CLAUDE.md, backend/CLAUDE.md, and frontend/CLAUDE.md for design rationale.

Getting started

Prerequisites

• Node.js 18+
• A local PostgreSQL instance
• An OpenAI API key

Setup

# 1. Create the database
createdb ecommerce_ai_native

# 2. Backend
cd backend
cp .env.example .env   # set OPENAI_API_KEY and your Postgres credentials
npm install
npm run db:setup       # applies schema and seeds ~45 sample laptops
npm run dev             # http://localhost:4000

# 3. Frontend (in a new terminal)
cd frontend
npm install
npm run dev             # http://localhost:5173

Open http://localhost:5173 and try:

"Show me laptops under $400 with 8GB RAM"

then follow up with:

"Let's raise the budget to $600"

API

Endpoint	Description
POST /api/chat	Send a message + prior filter state, get back a reply, merged filters, and matching laptops
GET /api/laptops	Browse/filter laptops directly via query params
GET /api/laptops/:id	Fetch a single laptop
GET /api/health	Health check

Roadmap

• Retrieval/grounding quality evaluation pipeline (LangChain evals)
• Broader electronics catalog beyond laptops

License

MIT