E-Commerce AI App

A modern, full-stack e-commerce application for a premium furniture store featuring an integrated AI shopping assistant, real-time content management, and robust order processing. This project is built to demonstrate modern web development practices using the latest React and Next.js features.

🌟 Features

• Storefront & Product Discovery: Browse products with server-side filtering (category, material, color, price, search).
• AI Shopping Assistant: Integrated Google Gemini-powered chatbot that can search products, answer questions, and fetch an authenticated user's order history.
• Admin Dashboard: Comprehensive dashboard with AI-generated business insights, inventory management, and order tracking.
• Content Management: Powered by Sanity Studio for managing products, categories, orders, and customers with live preview and real-time content updates.
• Secure Authentication: User authentication and session management handled by Clerk.
• Checkout & Payments: PCI-compliant checkout flow with Stripe, including webhook integration for order creation and inventory decrement.
• State Management: Persistent shopping cart and chat state managed using Zustand.

🛠️ Tech Stack

• Framework: Next.js 16 (App Router, Server Components, Server Actions)
• UI & Styling: React 19, Tailwind CSS v4, shadcn/ui
• Content Management: Sanity v4
• Authentication: Clerk
• Payments: Stripe
• AI Integration: @ai-sdk/google (Gemini)
• State Management: Zustand
• Testing: Vitest (Unit/Integration) & Playwright (E2E)
• Code Quality: Biome

🚀 Getting Started

Prerequisites

You will need Node.js installed, along with API keys for the following services:

• Sanity (Project ID, Dataset, Admin Tokens)
• Clerk (Publishable and Secret Keys)
• Stripe (Publishable Key, Secret Key, Webhook Secret)
• Google AI Studio (Gemini API Key)

Installation

1. Clone the repository and install dependencies:

   npm install

   or yarn install / pnpm install / bun install

2. Set up your environment variables. Create a .env.local file in the root directory and add the following:

   # Clerk Auth
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
   CLERK_SECRET_KEY=your_clerk_secret_key
   
   # Sanity
   NEXT_PUBLIC_SANITY_PROJECT_ID=your_sanity_project_id
   NEXT_PUBLIC_SANITY_DATASET=production
   SANITY_API_WRITE_TOKEN=your_sanity_write_token
   
   # Stripe
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key
   STRIPE_SECRET_KEY=your_stripe_secret_key
   STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
   
   # AI / Gemini
   GOOGLE_GENERATIVE_AI_API_KEY=your_gemini_api_key

3. Run the development server:

   npm run dev

4. Open http://localhost:3000 to view the storefront, or http://localhost:3000/studio to access Sanity Studio.

📂 Project Structure

• app/: Next.js App Router containing standard storefront routes, /admin, and /studio.
• components/: Reusable UI components including base building blocks (shadcn/ui) and application-specific components.
• lib/: Business utility logic, AI agent definitions, configuration, and state stores.
• sanity/: Sanity schema definitions, client settings, and custom Studio structure.
• e2e/: Playwright end-to-end tests.
• docs/: Additional documentation.

📜 Available Scripts

• npm run dev: Starts the development server.
• npm run build: Builds the app for production.
• npm run lint: Lints the codebase using Biome.
• npm run format: Formats code via Biome.
• npm run typegen: Generates TypeScript interfaces from the Sanity schema.
• npm run test: Runs unit and integration tests using Vitest.
• npm run test:e2e: Runs E2E tests via Playwright.

🧪 Testing

This application contains a robust testing suite consisting of three tiers:

• Unit Tests (npm run test:unit): Tests individual utilities, generic functions, and our Zustand store.
• Integration Tests (npm run test:integration): Tests checkout flows and Stripe webhooks via Vitest.
• E2E Tests (npm run test:e2e): Verifies major user journeys in a real browser using Playwright.