# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ShopCall.ai is a dual-repository application for AI-powered calling system integrated with e-commerce platforms. The project consists of:

- **shopcall.ai-main**: React/Vite frontend application with TypeScript
- **shopcall.ai-backend-main**: Express.js backend API

## Repository Structure

```
/data/shopcall/
├── shopcall.ai-main/          # Frontend application
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── context/       # React context providers (AuthContext)
│   │   │   └── ui/            # shadcn-ui component library
│   │   ├── pages/             # Route pages (Dashboard, Login, CallLogs, etc.)
│   │   ├── hooks/             # Custom React hooks
│   │   ├── lib/               # Utility functions
│   │   └── App.tsx            # Main application with routing
│   └── package.json
└── shopcall.ai-backend-main/  # Backend API
    ├── api/
    │   └── index.js           # Main Express server (950 lines)
    ├── public/                # Static files
    └── package.json
```

## Development Commands

### Frontend (shopcall.ai-main)
```bash
cd shopcall.ai-main
npm install              # Install dependencies
npm run dev              # Start dev server on port 8080
npm run build            # Production build
npm run build:dev        # Development build
npm run lint             # Run ESLint
npm run preview          # Preview production build
```

### Backend (shopcall.ai-backend-main)
```bash
cd shopcall.ai-backend-main
npm install              # Install dependencies
npm start                # Start server (node api/index)
```

## Technology Stack

### Frontend
- **Framework**: React 18 with Vite
- **Language**: TypeScript
- **UI Library**: shadcn-ui with Radix UI primitives
- **Styling**: Tailwind CSS
- **Routing**: React Router v6
- **State Management**: React Query (@tanstack/react-query)
- **Form Handling**: React Hook Form with Zod validation
- **Theme**: next-themes for dark mode support

### Backend
- **Framework**: Express.js v5
- **Language**: JavaScript (Node.js)
- **Database**: Supabase (PostgreSQL with auth)
- **Email**: Nodemailer (Gmail)
- **CORS**: Enabled for cross-origin requests

## Architecture

### Frontend Architecture

**Authentication Flow**:
- AuthContext provider (`src/components/context/AuthContext.tsx`) manages global auth state
- Token stored in localStorage as `session_data`
- PrivateRoute component protects authenticated routes
- Auth validation checks session token via `/auth/check` endpoint

**Routing Structure**:
```
/ (Index)               → Landing page
/signup                 → User registration
/login                  → User login
/otp                    → OTP verification
/dashboard (protected)  → Main dashboard
/call-logs (protected)  → Call history
/analytics (protected)  → Analytics dashboard
/webshops (protected)   → E-commerce integrations
/phone-numbers (protected) → Phone number management
/ai-config (protected)  → AI configuration
/onboarding (protected) → User onboarding flow
/about, /privacy, /terms → Public pages
```

**Component Organization**:
- Page components in `src/pages/` handle routing
- Content components (e.g., `DashboardContent.tsx`) contain page logic
- UI components in `src/components/ui/` are reusable shadcn components
- Context providers wrap the app in `App.tsx`

### Backend Architecture

**Single Server File**: All API logic is in `api/index.js` (~950 lines)

**Core Middleware**:
- CORS enabled globally
- Raw body parser for `/gdpr` webhooks
- JSON/urlencoded parsers for other routes
- `securedSession` middleware validates Supabase auth tokens

**Authentication Endpoints**:
- `POST /auth/signup` - Step 1: Store user data, generate and send OTP
- `POST /auth/signup/verify` - Step 2: Verify OTP and create Supabase user
- `POST /auth/signup/resend-otp` - Resend OTP email
- `POST /auth/login` - Email/password login via Supabase
- `POST /auth/logout` - Sign out
- `GET /auth/check` - Validate bearer token

**E-commerce Integration Endpoints**:
- `GET /auth/shopify` - Initialize Shopify OAuth flow
- `GET /auth/shopify/callback` - Handle Shopify OAuth callback
- `GET /auth/woocommerce` - Initialize WooCommerce OAuth (requires auth)
- `POST /auth/woocommerce/callback` - Handle WooCommerce credentials

**Webhook Endpoints** (GDPR compliance):
- `POST /gdpr/customers-data-request` - Customer data request
- `POST /gdpr/customers-redact` - Customer redaction
- `POST /gdpr/shop-redact` - Shop redaction
- HMAC verification via `verifyWebhook` middleware

**Other Endpoints**:
- `GET /health` - Health check

**Key Functions**:
- `generateOTP()` - Creates 6-digit OTP
- `sendOTPEmail(email, otp, userName)` - Sends styled verification email
- `normalizeShopUrl(shop)` - Cleans Shopify URLs
- `isValidShopUrl(shop)` - Validates Shopify domain format
- `processWebhook(req, res, topic)` - Async webhook processing

**State Management**:
- `pendingSignups` Map - Temporary storage for unverified signups (15 min TTL)
- `nonceStore` Map - OAuth state validation (10 min TTL)
- ⚠️ Production should use Redis/database instead of in-memory Maps

### Database Schema (Supabase)

**stores table**:
```
- user_id: UUID (FK to auth.users)
- platform_name: text (e.g., 'shopify', 'woocommerce')
- store_name: text
- store_url: text
- api_key: text
- api_secret: text
- scopes: text[]
- alt_data: jsonb (platform-specific data)
- phone_number: text
- package: text
```

## Environment Configuration

### Backend `.env` (shopcall.ai-backend-main)
```bash
SUPABASE_URL=https://ztklqodcdjeqpsvhlpud.supabase.co
SUPABASE_ANON_KEY=<anon_key>
SHOPIFY_API_KEY=<shopify_api_key>
SHOPIFY_API_SECRET=<shopify_api_secret>
EMAIL_USER=<gmail_address>
EMAIL_PASSWORD=<gmail_app_password>
NODE_ENV=production|development
```

### Frontend Environment
- No `.env` file in shopcall.ai-main
- Backend API URL hardcoded: `https://shopcall-ai-backend.vercel.app`
- Frontend URL hardcoded: `https://shopcall.ai`

## Deployment

Both applications deploy to Vercel:

**Backend** (`vercel.json`):
```json
{
  "version": 2,
  "rewrites": [{ "source": "/(.*)", "destination": "/api" }]
}
```
- All routes proxy to `/api/index.js`
- Deployed at: `https://shopcall-ai-backend.vercel.app`

**Frontend** (`vercel.json`):
```json
{
  "rewrites": [{ "source": "/(.*)", "destination": "/" }]
}
```
- SPA routing handled by React Router
- Deployed at: `https://shopcall.ai`

## Development Workflow

When making changes across both repositories:

1. **Backend Changes**: Modify `shopcall.ai-backend-main/api/index.js`
2. **Frontend Changes**: Work in `shopcall.ai-main/src/`
3. **Auth Flow Changes**: Update both AuthContext and backend `/auth/*` endpoints
4. **New Protected Routes**: Add to App.tsx inside `<PrivateRoute>` wrapper
5. **New API Endpoints**: Add to `api/index.js` with `securedSession` if auth required

## Important Notes

- All backend logic is in a single file (`api/index.js`)
- In-memory stores (`pendingSignups`, `nonceStore`) will reset on serverless function cold starts
- Frontend expects backend at `https://shopcall-ai-backend.vercel.app` (hardcoded)
- Supabase handles user authentication and data storage
- Email verification required for signup (OTP sent via Gmail)
- Shopify/WooCommerce OAuth flows store credentials in Supabase `stores` table

## Path Aliases

Frontend uses TypeScript path alias:
- `@/` → `./src/`

Example: `import { Button } from "@/components/ui/button"`