# CLAUDE.md

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

## Project Overview

ShopCall.ai is an AI-powered calling system integrated with e-commerce platforms. The project consists of:

- **shopcall.ai-main**: React/Vite frontend application with TypeScript
- **supabase**: Supabase Edge Functions for 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
└── supabase/                   # Supabase Edge Functions
    └── functions/              # Backend API functions
```

## 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
```

### Supabase Edge Functions
```bash
# Deploy Edge Functions
supabase functions deploy <function-name>

# Test locally
supabase functions serve
```

## 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
- **Platform**: Supabase Edge Functions (Deno)
- **Database**: Supabase (PostgreSQL with auth)
- **Authentication**: Supabase Auth

## 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 via Supabase client

**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

**Supabase Edge Functions**: Backend logic implemented as serverless Edge Functions

**Authentication**:
- Handled by Supabase Auth
- User management and session handling via Supabase client

**E-commerce Integrations**:
- Shopify OAuth flow
- WooCommerce OAuth flow
- ShopRenter integration
- Store credentials in Supabase `stores` table

### 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

### Frontend `.env` (shopcall.ai-main)
```bash
# Supabase Configuration
VITE_SUPABASE_URL=https://ztklqodcdjeqpsvhlpud.supabase.co
VITE_SUPABASE_ANON_KEY=<anon_key>

# Backend API Base URL (Supabase Edge Functions)
VITE_API_URL=https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1

# Frontend URL (for OAuth callbacks)
VITE_FRONTEND_URL=https://shopcall.ai
```

### Supabase Edge Functions `.env`
```bash
# OAuth Configuration
SHOPIFY_API_KEY=<shopify_api_key>
SHOPIFY_API_SECRET=<shopify_api_secret>
SHOPRENTER_CLIENT_ID=<shoprenter_client_id>
SHOPRENTER_CLIENT_SECRET=<shoprenter_client_secret>

# Email Configuration (if needed)
EMAIL_USER=<gmail_address>
EMAIL_PASSWORD=<gmail_app_password>

# Frontend URL
FRONTEND_URL=https://shopcall.ai
```

## Deployment

### Frontend
- **Build**: `npm run build` generates static files in `dist/`
- **Deployment**: Can be deployed to any static hosting service (Netlify, Vercel, GitHub Pages, etc.)
- SPA routing handled by React Router

### Supabase Edge Functions
- **Deployment**: Use `supabase functions deploy` command
- Edge Functions are deployed to Supabase infrastructure
- Automatically scaled and managed by Supabase

## Development Workflow

When making changes:

1. **Frontend Changes**: Work in `shopcall.ai-main/src/`
2. **Backend Changes**: Modify Supabase Edge Functions in `supabase/functions/`
3. **Auth Flow Changes**: Update AuthContext and Supabase Auth configuration
4. **New Protected Routes**: Add to App.tsx inside `<PrivateRoute>` wrapper
5. **New API Endpoints**: Create new Edge Functions in `supabase/functions/`

## Important Notes

- Backend is implemented as Supabase Edge Functions (serverless)
- Supabase handles user authentication, data storage, and API endpoints
- Frontend is a static React application that can be hosted anywhere
- All API calls go through Supabase Edge Functions
- OAuth flows store credentials in Supabase `stores` table

## Path Aliases

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

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