AI Shopping Assistant

Overview

• Chat-first shopping helper that understands Romanian natural language queries and recommends niche products from small vendors.
• Two-tier app: Flask backend orchestrates Gemini-powered product curation and payment intents, while a Vite + React frontend offers chat, cart, and checkout flows.
• Persisted authentication backed by PostgreSQL plus in-memory per-user chat/product history for seamless session recovery.
• Stripe Elements checkout flow and SerpAPI powered search, wrapped with custom filtering to avoid big-box retailers.

Repository Layout

• ai-shopping-backend/ – Flask API for search, AI ranking, history, auth, and Stripe integration.
• ai-shopping-ui/ – React 19 + TypeScript single-page app with chat experience, cart, and auth pages.
• README.md – project guide (this file).

Tech Stack

• Frontend: React 19, TypeScript, Vite, React Router, Stripe Elements, Lucide icons.
• Backend: Flask, google-genai, SerpAPI, Stripe, psycopg2 for PostgreSQL access.
• AI & Search: Gemini 2.5 Flash for relevance scoring, SerpAPI for Google Shopping/Organic results.
• Payments: Stripe Payment Intents (RON).
• Database: PostgreSQL database accounts with table utilizatori for auth records.

Prerequisites

• Node.js 20+ and npm (or pnpm/yarn) for the UI.
• Python 3.10+ with pip for the backend.
• PostgreSQL instance reachable at localhost:5432 (configurable via code changes).
• Stripe account (publishable + secret keys) and Google Gemini + SerpAPI API keys.

Backend Setup (ai-shopping-backend)

1. Create and activate a virtual environment:

   python -m venv .venv
   .venv\Scripts\Activate.ps1

2. Install dependencies:

   pip install flask flask-cors requests stripe google-genai psycopg2-binary

3. Configure environment variables (PowerShell example):

   $env:GEMINI_API_KEY = "your-gemini-key"
   $env:SERPAPI_KEY = "your-serpapi-key"
   $env:STRIPE_SECRET_KEY = "sk_live_or_test"

   Replace the hard-coded keys in app.py with secure lookups (os.getenv) to avoid committing secrets.
4. Provision the PostgreSQL schema (run in psql connected to database accounts):

   CREATE TABLE IF NOT EXISTS utilizatori (
     id SERIAL PRIMARY KEY,
     nume TEXT NOT NULL,
     prenume TEXT NOT NULL,
     email TEXT UNIQUE NOT NULL,
     parola_hash TEXT NOT NULL,
     data_inregistrare TIMESTAMPTZ DEFAULT NOW()
   );

5. Start the API (defaults to port 5000):

   python app.py

Frontend Setup (ai-shopping-ui)

1. Install dependencies:

   npm install

2. Update the Stripe publishable key in src/pages/CartPage.tsx (value passed to loadStripe).
3. If the backend runs on a different host/port, adjust API_BASE constants in src/context/AuthContext.tsx and src/pages/ChatPage.tsx.
4. Run the development server on port 5173 by default:

   npm run dev

Key Environment Variables

Name	Used In	Purpose
GEMINI_API_KEY	Backend	Authenticates Gemini client for product scoring.
SERPAPI_KEY	Backend	Access token for Google search results via SerpAPI.
STRIPE_SECRET_KEY	Backend	Creates PaymentIntents for checkout.
STRIPE_PUBLISHABLE_KEY	Frontend	Powers Stripe Elements checkout widget.

Store secrets outside the repo (environment, .env, or secret manager). Never commit live keys.

API Surface (Backend)

• POST /search – body { query, daily_users?, total_products? }; returns curated products array and inferred business_size.
• POST /create-payment-intent – body { items }; returns Stripe client_secret for completing the payment.
• POST /history/save – persist chat/products in memory for a user_id.
• GET /history/get?user_id= – retrieve cached conversation history.
• POST /history/clear – remove cached history when a user logs out.
• POST /register – create a user in PostgreSQL (hashes password with Werkzeug).
• POST /login – authenticate user credentials.
• GET /users – admin-style listing of all registered users.

Frontend Highlights

• AuthContext wraps the app to manage login state via the backend and localStorage.
• ChatPage drives the conversational UI, persists history, and paginates AI-ranked products (4 cards/page, lazy loading batches of 12).
• CartContext manages client-side cart state and communicates with Stripe checkout.
• RequireAuth protects chat and cart routes, redirecting to /auth when needed.

Running the Full Stack

1. Boot the backend Flask server (ensure env vars are set beforehand).
2. Start the Vite dev server.
3. Visit http://localhost:5173 to use the app; chat calls http://localhost:5000 for search/auth/payment APIs.

Testing & Linting

• Frontend: npm run lint uses the ESLint configuration in eslint.config.js.
• Backend: Add pytest or Flask tests as needed (no suite included yet).

Troubleshooting

• Missing AI responses: confirm GEMINI_API_KEY and that the Gemini model is available in your project.
• Empty search results: check SerpAPI quota; review console logs for request errors.
• Stripe failures: verify both publishable and secret keys belong to the same Stripe account and that totals exceed Stripe minimum (~2 RON).
• Auth errors: ensure PostgreSQL credentials match the values in user_routes.py or externalize them to environment variables.

Next Steps

• Externalize all secrets into a .env loader.
• Add persistence for chat history (Redis or database) instead of in-memory cache.
• Implement unit/integration tests for auth, search, and payment flows.