CLAUDE.md

# CLAUDE.md

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

## Project Overview

**Volta.AI** is a Brazilian AI-powered digital loyalty platform that converts paper stamp cards to Apple Wallet/Google Pay, combined with intelligent marketing automation via WhatsApp campaigns. The platform targets Brazilian restaurants and high-end establishments, providing automated customer insights and campaign creation.

### Key Features
- Digital wallet loyalty cards (Apple Wallet/Google Pay)
- QR code customer enrollment
- AI-powered campaign suggestions using DeepSeek API
- WhatsApp Business API integration
- LGPD-compliant customer data management
- Brazilian market-specific features (PIX, Portuguese localization)

## Tech Stack
- **Frontend:** Next.js 15 with App Router, TypeScript, Tailwind CSS, shadcn/ui
- **Backend:** Supabase (PostgreSQL, Auth, Storage, Edge Functions)
- **AI:** DeepSeek API for text generation, FLUX.1 via fal.ai for image generation
- **Deployment:** Vercel
- **Repository:** https://github.com/pedrosantoshc/volta-ai.git

## Development Commands
```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Type checking
npx tsc --noEmit

# Linting
npm run lint

# Add shadcn/ui components
npx shadcn@latest add [component-name]
```

## Project Structure
```
src/
├── app/                    # Next.js 15 App Router
│   ├── globals.css        # Tailwind CSS styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx          # Home page
├── components/
│   └── ui/               # shadcn/ui components
│       ├── button.tsx
│       ├── card.tsx
│       ├── input.tsx
│       └── label.tsx
└── lib/
    └── utils.ts          # Utility functions
```

## Architecture Notes
- Mobile-first responsive design with progressive enhancement
- AI-first UX with prominent suggestions and one-click actions
- Row Level Security (RLS) for multi-tenant data isolation
- Brazilian localization throughout (Portuguese language, local business hours)
- LGPD compliance built into data models and user flows

## Color Palette (from PRD)
- **Primary:** Purple gradient (#7c3aed to #a855f7) - AI/premium feel
- **Success:** Green (#16a34a) - positive metrics
- **Warning:** Amber (#d97706) - attention needed
- **Background:** Light gray (#f8fafc)

## Current Development Phase
**Phase 1B: Core Business Setup (MAJOR PROGRESS MADE)**

### Completed Tasks
✅ Next.js 15 project setup with TypeScript
✅ Tailwind CSS and shadcn/ui configuration  
✅ Supabase integration (database, auth, storage)
✅ Authentication system (login/signup with Google OAuth)
✅ Basic dashboard layout with navigation
✅ Loyalty card designer with real-time preview
✅ Database schema deployed with all tables
✅ API documentation (PassKit, DeepSeek, FAL.AI)
✅ Development rules and workflow established
✅ Environment variables configured with API keys

### Phase 1B Progress - Customer Management & LGPD Compliance
✅ **Customer Management System** - Full CRUD operations with advanced features
✅ **Excel Import System** - Dynamic template generation with loyalty card validation
✅ **LGPD Compliance Framework** - Complete consent tracking and validation
✅ **Bulk Operations** - Customer selection, bulk delete, CSV import/export
✅ **Customer Segmentation** - Active/inactive filters, search functionality
✅ **Conditional Logic** - Stamp validation against card limits, auto-completion
✅ **Action System** - Conditional button enabling based on consent status

## Complete Development Roadmap

### **Phase 1B: Core Business Setup (MAJOR PROGRESS MADE)**

#### **1. Business Onboarding Flow** ⏳ IN PROGRESS
**Goal**: Complete restaurant setup from signup to operational loyalty program

**Components to Build**:
- `/onboarding/step-1` - Enhanced business registration (name, address, CNPJ, owner details)
- `/onboarding/step-2` - Logo upload to Supabase Storage + business type selection
- `/onboarding/step-3` - AI settings (tone: amigável/profissional/casual, brand voice, colors)
- `/onboarding/step-4` - Team management (invite staff, assign roles: owner/manager/staff)
- `/onboarding/complete` - Progress summary + first loyalty card creation

**What This Accomplishes**:
- Gets restaurants fully operational in under 10 minutes
- Sets up AI personality for Brazilian Portuguese campaigns
- Enables team collaboration with role-based access
- Ensures LGPD compliance from the start

#### **2. Customer Enrollment System (MVP Heart)** ⏳ IN PROGRESS
**Goal**: Convert walk-in customers to digital loyalty program members

**Components to Build**:
- `/enroll/[cardId]` - Mobile-optimized public enrollment for QR scans
- `/dashboard/cartoes/[id]/formulario` - Dynamic form builder for custom questions
- ✅ LGPD consent collection system (data processing, WhatsApp marketing, email) - **COMPLETED**
- ✅ Customer data processing pipeline with validation and deduplication - **COMPLETED**
- Automatic digital wallet pass generation and distribution

**What This Accomplishes**:
- Achieves 60%+ customer enrollment rate (PRD target)
- ✅ Collects valuable customer data for AI insights - **COMPLETED**
- Enables all downstream marketing automation
- Creates seamless mobile-first customer experience

### **Phase 1C: Core Loyalty Operations**

#### **3. Customer Management System** ✅ **COMPLETED**
**Components Built**:
- ✅ `/dashboard/clientes` - Customer database with advanced search/filtering - **COMPLETED**
- ✅ Customer segmentation builder (Active, Clientes eventuais, search filters) - **COMPLETED**
- ⏳ Individual customer profile pages with complete interaction history - **PENDING**
- ✅ Bulk operations (Excel import/export, bulk delete, customer selection) - **COMPLETED**  
- ✅ LGPD-compliant consent tracking and validation - **COMPLETED**
- ✅ Conditional action system (buttons enabled based on consent) - **COMPLETED**

#### **4. Manual Stamp Attribution System**
**Components to Build**:
- `/dashboard/selos/adicionar` - Quick stamp addition interface for staff
- `/dashboard/selos/escaneamento` - QR code scanner for customer identification
- Bulk stamp operations for busy periods (add stamps to multiple customers)
- Complete audit trail (who added stamps, when, transaction history)
- Reward redemption tracking and notification system

### **Phase 1D: AI-Powered Insights**

#### **5. Basic AI Copilot Integration (DeepSeek API)**
**Components to Build**:
- AI insights dashboard showing customer behavior patterns
- Automated campaign suggestions: "47 clientes inativos - Campanha 'Sentimos sua falta'"
- Expected engagement predictions and revenue impact estimates
- One-click campaign creation from AI suggestions
- Performance tracking for AI-generated campaigns

**Key AI Features**:
- Inactive customer detection (15+ days since last visit)
- Frequent visitor identification and VIP upgrade suggestions
- Birthday campaign automation
- Completed card reward reminders

#### **6. WhatsApp Integration Foundation**
**Components to Build**:
- WhatsApp Business API provider integration (360Dialog, Twilio, or ChatAPI)
- Template message system for Brazilian compliance
- Automated notifications (stamp additions, rewards available, card completed)
- Manual campaign sending to customer segments
- Message delivery tracking and analytics dashboard

**Compliance Features**:
- 24-hour messaging window compliance
- Template message approval workflow
- Unsubscribe mechanisms in all campaigns
- Rate limiting to prevent spam

### **Phase 2A: Digital Wallet Integration**

#### **7. Apple Wallet PassKit Implementation**
**Components to Build**:
- PassKit certificate setup and management
- Dynamic pass generation with loyalty card data
- Real-time pass updates when stamps are added
- Pass distribution via enrollment flow
- Push notifications for pass changes

**Technical Requirements**:
- Apple Developer account and certificates
- PassKit Node.js SDK integration
- Pass signing and security implementation

#### **8. Google Pay Integration**
**Components to Build**:
- Google Pay API setup and authentication
- Pass generation for Android users
- Cross-platform wallet compatibility testing
- Unified pass management system

### **Phase 2B: Advanced AI Marketing**

#### **9. Advanced Campaign Generation**
**Components to Build**:
- Natural language campaign generation with brand voice matching
- Customer segmentation AI based on behavior patterns
- A/B testing suggestions for campaign optimization
- Dynamic content personalization per customer segment
- Campaign performance prediction models

#### **10. Visual Content Generation (FAL.AI FLUX)**
**Components to Build**:
- Promotional image generation for WhatsApp campaigns
- AI-powered loyalty card background design
- Seasonal campaign imagery (Festa Junina, Natal, Carnaval)
- Brand-consistent visual asset creation
- Social media ready content in multiple formats

#### **11. Advanced Analytics & ROI Tracking**
**Components to Build**:
- Revenue attribution modeling linking campaigns to visits
- Customer lifetime value calculations
- Loyalty program ROI measurement dashboard
- Predictive analytics for customer churn
- Comparative analysis (loyalty vs non-loyalty customers)

### **Phase 3: Enterprise & Scaling**

#### **12. POS System Integration**
**Components to Build**:
- Brazilian payment processor APIs (Stone, Cielo, GetNet)
- Real-time purchase tracking linked to loyalty cards
- Automatic stamp attribution based on spend thresholds
- Revenue correlation analysis and reporting

#### **13. Advanced Enterprise Features**
**Components to Build**:
- Multi-location support for restaurant chains
- Advanced role permissions and user hierarchies
- API for third-party integrations
- White-label solutions for payment processors
- Coalition loyalty programs (cross-brand partnerships)

### **Success Metrics (PRD Targets)**
- **Customer Acquisition**: 60%+ enrollment rate at participating venues
- **Engagement**: 25%+ WhatsApp campaign engagement rates
- **Performance**: 99.5%+ uptime, <200ms dashboard response times
- **ROI**: 15:1 return on AI-generated campaigns
- **Business Growth**: R$ 100K+ ARR within 12 months

### **IMMEDIATE NEXT PRIORITIES (Current Focus)**

#### **High Priority - Core MVP Completion**
1. **Customer Enrollment Flow** - Complete the public-facing customer registration
   - `/enroll/[cardId]` - Mobile-optimized enrollment page for QR scans
   - Dynamic form builder for custom business questions
   - Integration with existing LGPD consent system

2. **Individual Customer Actions** - Replace placeholder alerts with real functionality
   - Customer detail pages (`/dashboard/clientes/[id]`) 
   - Manual stamp addition interface
   - Loyalty card status management

3. **Digital Wallet Integration** - Core value proposition
   - Apple Wallet PassKit implementation
   - Google Pay Pass generation and distribution
   - Real-time pass updates when stamps are added

#### **Medium Priority - Business Operations**
4. **Enhanced Onboarding Flow** - Complete business setup experience
   - Multi-step onboarding with logo upload
   - AI personality configuration for campaigns
   - Team member invitation and role management

5. **Manual Stamp Attribution System** - Staff operational tools
   - QR code scanner for customer identification
   - Bulk stamp operations for busy periods
   - Complete audit trail and transaction history

#### **Future Phases - AI & Marketing**
6. **Basic AI Copilot Integration** - DeepSeek API
   - Customer behavior analysis and insights
   - Simple campaign suggestions based on patterns
   - One-click campaign creation

7. **WhatsApp Business API Integration** - Customer communication
   - Provider evaluation and selection
   - Automated notifications for stamps/rewards
   - Manual campaign sending to segments

## Technical Priorities
- **Mobile-first**: All features must work perfectly on mobile devices
- **Brazilian compliance**: LGPD, Portuguese language, local business practices
- **AI integration**: DeepSeek for campaigns, FAL.AI for imagery
- **Performance**: <200ms dashboard loads, <500ms API responses
- **Scalability**: Multi-tenant architecture with Row Level Security

## Development Approach
Following iterative development with UI/UX integrated throughout each phase rather than as a separate final step. WhatsApp integration planned as final implementation after API provider research.

## **STRATEGIC DEVELOPMENT PLAN - DECEMBER 2024**

### **GPT vs Current Progress Comparison**

After completing Phase 1B customer management and loyalty operations, here's how our current progress compares to the original GPT roadmap:

#### **✅ MAJOR ACCOMPLISHMENTS (Ahead of Schedule)**

**Customer Management System** - **FULLY COMPLETED**
- ✅ Advanced customer database with search, filtering, and bulk operations
- ✅ Excel import/export with dynamic template generation
- ✅ LGPD compliance framework with comprehensive consent tracking
- ✅ Customer segmentation (Active vs "Clientes eventuais") 
- ✅ Conditional action system based on consent status
- ✅ Bulk delete operations with customer selection
- **Status:** GPT plan estimated this as Phase 1C, we completed in Phase 1B

**Loyalty Card Operations** - **CORE FUNCTIONALITY COMPLETED**
- ✅ Business scoping utility (`getCurrentBusinessId`) - Fixed critical multi-tenant bug
- ✅ Customer detail pages with loyalty card progress visualization
- ✅ "Dar selo" API (`/api/stamps/add`) with business validation and auto-completion
- ✅ GiveStampDialog component for intuitive stamp attribution
- ✅ Manual stamp attribution pages (`/dashboard/selos/adicionar`)
- ✅ Wallet integration stubs ready for Phase 2 implementation
- **Status:** GPT plan had this spread across Phases 1B-1C, we consolidated effectively

**Technical Foundation** - **ROBUST AND SCALABLE**
- ✅ Next.js 15 with proper TypeScript configuration
- ✅ Supabase integration with Row Level Security
- ✅ Mobile-first responsive design
- ✅ Error handling and user feedback systems
- ✅ API route structure following RESTful patterns
- **Status:** Exceeded GPT plan expectations for technical quality

#### **🎯 CURRENT FOCUS AREAS (Next 4-6 Weeks)**

**1. Customer Enrollment System** - **HIGH PRIORITY**
- ✅ Public enrollment page (`/enroll/[cardId]`) - **COMPLETED**
- ✅ LGPD consent collection with comprehensive compliance - **COMPLETED**
- ✅ Custom form builder integration - **COMPLETED**
- ⏳ QR code scanning functionality with camera integration - **PENDING**
- ⏳ Real-time QR code generation and management - **PENDING**

**2. Digital Wallet Integration** - **CORE VALUE PROPOSITION**
- ⏳ Apple Wallet PassKit implementation with certificate setup
- ⏳ Google Pay Pass generation and distribution
- ⏳ Real-time pass updates when stamps are added
- ⏳ Pass signing and security implementation
- **Business Impact:** This is the primary differentiator vs competitors

**3. QR Code & Scanning System** - **OPERATIONAL EFFICIENCY**
- ✅ Manual QR input functionality - **COMPLETED**
- ⏳ Camera integration for live QR scanning - **PENDING** 
- ⏳ Customer identification and validation workflow - **PENDING**
- ✅ QR code scanning page structure - **COMPLETED**

#### **📋 REFINED NEXT STEPS (Priority Order)**

**Phase 1C Completion (January 2025)**

1. **QR Scanning Implementation** - **IMMEDIATE PRIORITY**
   - Complete camera integration for live QR code scanning
   - Implement QR code generation with customer card linking
   - Add QR validation and error handling
   - **Files:** `src/app/dashboard/selos/escaneamento/page.tsx`, QR generation utilities

2. **Digital Wallet Integration** - **CORE MVP FEATURE**
   - Apple Wallet PassKit certificate configuration
   - Pass generation API endpoints (`/api/wallet/pass/[customerCardId]`)
   - Google Pay Pass implementation
   - Real-time pass updates via webhooks
   - **Files:** `src/lib/wallet.ts`, Apple/Google Pay API integration

3. **Onboarding Flow Polish** - **USER EXPERIENCE**
   - Multi-step business setup with progress tracking
   - Logo upload to Supabase Storage integration
   - AI personality configuration (tone, brand voice)
   - Team member invitation system with role management

**Phase 2A (February-March 2025) - AI Integration**

4. **Basic AI Copilot** - **COMPETITIVE ADVANTAGE**
   - DeepSeek API integration for customer insights
   - Inactive customer detection (15+ days since last visit)
   - Simple campaign suggestions based on behavior patterns
   - One-click campaign creation interface
   - **Files:** `src/lib/ai-insights.ts`, dashboard components

5. **WhatsApp Business API** - **CUSTOMER COMMUNICATION**
   - Provider evaluation and selection (360Dialog vs Twilio vs ChatAPI)
   - Template message system for Brazilian compliance
   - Automated notifications for stamps/rewards
   - Manual campaign sending to customer segments
   - Message delivery tracking and analytics

**Phase 2B (April-May 2025) - Advanced Features**

6. **Advanced AI Marketing** - **DIFFERENTIATION**
   - FLUX.1 integration via fal.ai for promotional imagery
   - Natural language campaign generation with brand voice
   - A/B testing suggestions and optimization
   - Performance prediction models

7. **POS Integration Foundation** - **ROI TRACKING**
   - Brazilian payment processor API research (Stone, Cielo, GetNet)
   - Real-time purchase tracking linked to loyalty cards
   - Revenue attribution modeling for campaign ROI
   - Baseline vs performance comparison dashboard

#### **🏗️ ARCHITECTURAL DECISIONS**

**What We Got Right:**
- Business multi-tenancy with proper scoping prevents data leakage
- Component reusability (GiveStampDialog used across multiple pages)
- API design follows consistent patterns and error handling
- TypeScript interfaces properly model business logic
- Mobile-first approach ensures broad compatibility

**Technical Debt to Address:**
- Complete TypeScript `any` type elimination (currently in progress)
- Implement comprehensive RLS policy audit
- Add unit tests for critical business logic
- Optimize database queries for larger datasets
- Add proper logging and monitoring integration

#### **🎯 SUCCESS METRICS TRACKING**

**Completed Milestones:**
- ✅ Customer management system supports 1000+ customers per business
- ✅ LGPD compliance framework prevents legal issues
- ✅ Manual stamp attribution enables operational efficiency
- ✅ Customer segmentation allows targeted marketing

**Next Milestones:**
- 📱 60%+ customer enrollment rate via QR scanning
- 💳 Apple Wallet/Google Pay integration working end-to-end
- 🤖 AI insights provide actionable customer behavior analysis  
- 📈 WhatsApp campaigns achieve 25%+ engagement rates

#### **🔄 STRATEGIC PIVOTS FROM ORIGINAL PLAN**

**What Changed:**
1. **Customer Management Priority:** Moved from Phase 1C to 1B due to operational importance
2. **LGPD Compliance Depth:** Implemented more comprehensive framework than originally scoped
3. **Business Scoping:** Added robust multi-tenant architecture not in original plan
4. **Component Architecture:** Created more reusable components for operational efficiency

**Why These Changes Worked:**
- Earlier customer management completion enables better business validation
- Comprehensive LGPD compliance prevents future legal blockers
- Robust architecture supports scaling without major refactoring
- Operational tools (stamp attribution) provide immediate business value

#### **💡 KEY INSIGHTS FOR NEXT PHASE**

1. **QR Integration is Critical:** Digital wallet value depends on seamless QR scanning
2. **AI Must Be Practical:** Focus on actionable insights vs complex analytics
3. **WhatsApp Provider Research:** Brazilian compliance requirements are complex
4. **Mobile Experience:** All features must work perfectly on mobile devices
5. **Business Validation:** Each feature should solve real restaurant operational pain points

This strategic plan positions us ahead of the original GPT timeline while maintaining focus on core business value delivery.

## Development Rules & Documentation
**IMPORTANT**: Before implementing any feature, always follow these steps:

1. **Check PRD.md** - Understand feature requirements and business context
2. **Review API Documentation** - Check `/docs/` folder for relevant API docs:
   - `passkit-api.md` - Apple Wallet & Google Pay integration
   - `deepseek-api.md` - AI campaign generation and insights
   - `fal-ai-api.md` - FLUX.1 image generation for marketing
   - `development-rules.md` - Complete development workflow and standards
3. **Ask Questions** - When information is missing or unclear, ask before proceeding

### API Keys Configured
- ✅ **DeepSeek**: AI campaign generation and customer insights
- ✅ **FAL.AI**: FLUX.1 image generation for promotional content
- ✅ **Supabase**: Database, auth, and storage backend
- ⏳ **PassKit**: Digital wallet integration (to be configured)
- ⏳ **WhatsApp Business API**: Customer messaging (provider TBD)

## Development Rules & Guidelines

### Core Development Workflow
1. **Always check PRD first** (`docs/PRD.md`) for requirements and specifications
2. **Check API documentation** (`docs/passkit-api.md`, `docs/deepseek-api.md`, `docs/fal-ai-api.md`)
3. **Ask for clarification** if information is missing or unclear
4. **Never assume** API capabilities without checking documentation

### Available API Documentation
- **PassKit API** (`docs/passkit-api.md`) - Apple Wallet + Google Pay loyalty cards
- **DeepSeek API** (`docs/deepseek-api.md`) - AI campaign generation and customer insights
- **FAL.AI API** (`docs/fal-ai-api.md`) - FLUX image generation for promotional content
- **Development Rules** (`docs/development-rules.md`) - Complete development guidelines

### API Keys Configured
- ✅ DeepSeek AI: `sk-a1ebdaeadc6b44459940d3bc40fb6f36`
- ✅ FAL.AI FLUX: `791c05e6-beb4-4114-8036-64a52f39c6fa:4f5b9a7f03021af62598985027156208`
- ✅ Supabase: Real production credentials configured

## Important Notes
- Always maintain mobile-first approach
- Implement Portuguese localization from the start
- Ensure LGPD compliance in all data handling
- Use shadcn/ui components for consistent design
- Follow the established color palette for brand consistency
- **ALWAYS** check PRD and API documentation before implementing features
- **Never assume API capabilities** - Always check documentation first
- **Test integrations thoroughly** - Verify all API calls work correctly