blackcanyontickets/CLAUDE.md

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:

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

# Stripe MCP (Model Context Protocol)
npm run mcp:stripe         # Start Stripe MCP server for AI integration
npm run mcp:stripe:debug   # Start MCP server with debugging interface

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
• MCP Server: AI-powered Stripe operations through Model Context Protocol

Stripe MCP (Model Context Protocol)

• Purpose: AI-powered interactions with Stripe API and knowledge base
• Tools: Customer management, payment processing, subscriptions, refunds
• Configuration: See MCP_SETUP.md for detailed setup instructions
• Commands: npm run mcp:stripe (production) or npm run mcp:stripe:debug (development)
• Integration: Works with Claude Desktop and other AI agents

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 System

• Centralized API Client: /src/lib/api-client.ts - Main client with authentication
• API Router: /src/lib/api-router.ts - Browser-friendly wrapper for common operations
• Authentication: Automatic session management and organization context
• Error Handling: Consistent error responses with user-friendly messages
• Usage: Use import { api } from '../lib/api-router' in components

API System Usage Examples:

// In Astro components (client-side scripts)
const { api } = await import('../lib/api-router');

// Load event stats
const stats = await api.loadEventStats(eventId);

// Load event details
const event = await api.loadEventDetails(eventId);

// Load complete event page data
const { event, stats, error } = await api.loadEventPage(eventId);

// Format currency and dates
const formattedPrice = api.formatCurrency(priceInCents);
const formattedDate = api.formatDate(dateString);

API Design

• RESTful: Standard HTTP methods with proper status codes
• Authentication: Automatic Supabase JWT validation on all API calls
• 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

# 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