Initial commit - Black Canyon Tickets whitelabel platform

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-08 12:31:31 -06:00
commit 997c129383
139 changed files with 60476 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,209 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Black Canyon Tickets is a self-service ticketing platform designed for upscale venues. The platform runs at `portal.blackcanyontickets.com` and serves high-end events like dance performances, weddings, and galas.
+
+## Development Commands
+
+All commands are run from the root directory:
+
+```bash
+# Development
+npm run dev          # Start development server at localhost:4321
+npm run start        # Alias for npm run dev
+
+# Building & Testing
+npm run build        # Type check and build for production
+npm run typecheck    # Run Astro type checking only
+npm run preview      # Preview production build locally
+
+# Database
+node setup-schema.js # Initialize database schema (run once)
+```
+
+## Tech Stack
+
+- **Frontend:** Astro 5.x with React islands for interactive components
+- **Styling:** Tailwind CSS 4.x with custom glassmorphism design system
+- **Database & Auth:** Supabase (PostgreSQL + Supabase Auth)
+- **Payments:** Stripe + Stripe Connect for automated payouts and platform fees
+- **QR Scanning:** Mobile-friendly browser-based scanner using HTML5 canvas
+- **Emails:** Resend for transactional emails
+- **Monitoring:** Sentry for error tracking and performance monitoring
+- **Hosting:** Self-hosted Node.js with standalone adapter
+
+## Architecture
+
+### Core Application Flow
+1. **Authentication**: Supabase Auth with organization-based access control
+2. **Event Management**: Multi-tenant system with Row Level Security (RLS)
+3. **Ticket Sales**: Inventory management with pessimistic locking
+4. **Payment Processing**: Stripe Connect for direct payouts to organizers
+5. **QR Scanning**: UUID-based tickets for secure door management
+
+### Key Routes
+- `/` - Homepage (public)
+- `/login` - Authentication portal
+- `/dashboard` - Event list and revenue summary (authenticated)
+- `/events/new` - Event creation form (authenticated)
+- `/events/[id]/manage` - Comprehensive event management with tabs (authenticated)
+- `/e/[slug]` - Public ticket checkout page (embeddable)
+- `/scan` - QR scanning interface for door staff (authenticated)
+- `/admin/` - Platform administration (admin only)
+
+### Database Schema (Core Tables)
+- `organizations`: Multi-tenant isolation with Stripe Connect accounts
+- `users`: Organization membership with role-based access
+- `events`: Event metadata with slugs and seating configuration
+- `ticket_types`: Pricing tiers with inventory tracking
+- `tickets`: Individual ticket records with UUIDs for QR codes
+- `presale_codes`: Time-limited access codes with usage tracking
+- `seating_maps`: Venue layouts for assigned seating events
+
+### Multi-Tenant Security
+- **Row Level Security (RLS)**: All tables filtered by organization_id
+- **Authentication**: Supabase Auth with organization context
+- **Admin Override**: Special admin role bypasses organization filtering
+- **API Security**: All API routes validate organization membership
+
+## Key Integrations
+
+### Supabase Configuration
+- **URL**: `https://zctjaivtfyfxokfaemek.supabase.co`
+- **Environment Variables**: `PUBLIC_SUPABASE_URL`, `PUBLIC_SUPABASE_ANON_KEY`
+- **Auth**: Built-in authentication with organization assignment
+- **Database**: PostgreSQL with migrations in `/supabase/migrations/`
+
+### Stripe Integration
+- **Connect**: Organizers onboard via Stripe Connect for direct payouts
+- **Platform Fees**: Automatically split from each transaction
+- **Webhooks**: Payment confirmation and dispute handling
+- **Environment**: Uses publishable/secret key pairs
+
+### Design System
+- **Theme**: Glassmorphism with dark gradients (see DESIGN_SYSTEM.md)
+- **Colors**: Blue/purple gradients with white text on dark backgrounds
+- **Layouts**: `Layout.astro` (public), `SecureLayout.astro` (authenticated)
+- **Animations**: CSS keyframes for fadeInUp, slideIn, and float effects
+
+## File Structure
+
+```
+src/
+├── components/          # Reusable UI components
+│   ├── Navigation.astro    # Main navigation with auth state
+│   ├── TicketCheckout.tsx  # React component for ticket purchasing
+│   └── ProtectedRoute.astro # Auth guard wrapper
+├── layouts/
+│   ├── Layout.astro        # Base layout with SEO and meta
+│   └── SecureLayout.astro  # Authenticated layout with glassmorphism
+├── lib/                    # Utility modules
+│   ├── supabase.ts        # Database client configuration
+│   ├── stripe.ts          # Payment processing utilities
+│   ├── auth.ts            # Authentication helpers
+│   ├── database.types.ts  # Generated TypeScript types
+│   └── validation.ts      # Form validation schemas
+├── middleware.ts           # Security headers and HTTPS redirect
+├── pages/
+│   ├── api/               # API endpoints
+│   │   ├── inventory/     # Ticket reservation and purchase
+│   │   ├── webhooks/      # External service callbacks
+│   │   └── admin/         # Admin-only endpoints
+│   ├── events/[id]/
+│   │   └── manage.astro   # Complex event management interface
+│   └── e/[slug].astro     # Public ticket sales page
+└── styles/
+    ├── global.css         # Global styles and imports
+    └── glassmorphism.css  # Design system utilities
+```
+
+## Development Patterns
+
+### Component Architecture
+- **Astro Components**: Server-rendered with minimal JavaScript
+- **React Islands**: Interactive components (forms, real-time updates)
+- **TypeScript**: Strict typing with generated database types
+- **Props Validation**: Zod schemas for API and form validation
+
+### State Management
+- **Server State**: Supabase real-time subscriptions
+- **Client State**: React hooks for interactive components
+- **Form State**: Native form handling with progressive enhancement
+- **Auth State**: Supabase auth context with organization data
+
+### API Design
+- **RESTful**: Standard HTTP methods with proper status codes
+- **Authentication**: Supabase JWT validation on all protected routes
+- **Error Handling**: Consistent error responses with user-friendly messages
+- **Rate Limiting**: Built-in protection against abuse
+
+## Security Implementation
+
+### Content Security Policy
+- **Strict CSP**: Defined in middleware.ts with Stripe and Supabase exceptions
+- **HTTPS**: Forced in production with HSTS headers
+- **XSS Protection**: Content type validation and frame options
+
+### Data Protection
+- **Row Level Security**: Database-level access control
+- **Input Validation**: Zod schemas for all user inputs
+- **SQL Injection**: Parameterized queries via Supabase client
+- **Secrets Management**: Environment variables for all sensitive data
+
+## Testing & Monitoring
+
+### Error Tracking
+- **Sentry**: Configured for both client and server-side errors
+- **Logging**: Winston for server-side logging to files
+- **Performance**: Sentry performance monitoring enabled
+
+### Environment Variables Required
+```bash
+# Supabase
+PUBLIC_SUPABASE_URL=https://zctjaivtfyfxokfaemek.supabase.co
+PUBLIC_SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+
+# Stripe
+STRIPE_PUBLISHABLE_KEY=pk_...
+STRIPE_SECRET_KEY=sk_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# Email
+RESEND_API_KEY=re_...
+
+# Monitoring
+SENTRY_DSN=https://...
+```
+
+## Common Development Tasks
+
+### Adding New Features
+1. **Database Changes**: Add migration to `/supabase/migrations/`
+2. **API Endpoints**: Create in `/src/pages/api/` with proper validation
+3. **UI Components**: Follow glassmorphism design system patterns
+4. **Types**: Update `database.types.ts` or regenerate from Supabase
+
+### Event Management System
+The `/events/[id]/manage.astro` page is the core of the platform:
+- **Tab-based Interface**: Tickets, Venue, Orders, Attendees, Analytics
+- **Real-time Updates**: Supabase subscriptions for live data
+- **Complex State**: Multiple modals and forms with validation
+- **Responsive Design**: Mobile-first with glassmorphism effects
+
+### QR Code System
+- **Generation**: UUID-based tickets prevent enumeration
+- **Scanning**: HTML5 camera API with canvas processing
+- **Validation**: Server-side verification with attendance tracking
+- **Security**: Tamper-proof tickets with database verification
+
+## Important Notes
+
+- **Mobile-First**: Scanner interface optimized for phone screens
+- **Performance**: Glassmorphism effects may impact mobile performance
+- **Accessibility**: WCAG AA compliance maintained throughout
+- **SEO**: Server-side rendering for public pages
+- **Multi-tenant**: All features must respect organization boundaries