shopcall/CLAUDE.md

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)

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

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

# 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

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