Home Explore Help
Sign In
fszontagh
/
shopcall
1
1
Fork 0
Files Issues 38 Pull Requests 0 Wiki
Tree: 9f4449040f
Branches Tags
shopcall
/
CLAUDE.md

CLAUDE.md 7.5 KB
History Raw

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)

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)

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)

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

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

Frontend (vercel.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"