# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview Black Canyon Tickets React Rebuild is a frontend-only React application focused on learning modern UI/UX patterns. This is a complete rebuild using React 18, TypeScript, and Tailwind CSS with a sophisticated glassmorphism design system. The project serves as a production-ready demo of premium ticketing platform interfaces without live database or payment integrations. **🎉 PROJECT STATUS: Phase 3 Substantially Complete (August 2025)** The project has evolved far beyond the original scope with 80+ React components, advanced analytics, territory management, QR scanning, and enterprise features. See REBUILD_PLAN.md for detailed status. ## Development Commands ```bash # Development npm run dev # Start development server at localhost:5173 (binds to 0.0.0.0) npm run build # Type check and build for production with chunk optimization npm run preview # Preview production build locally # Code Quality npm run lint # Run ESLint with unused disable directives report npm run lint:ci # CI-specific linting with max warnings npm run lint:fix # Run ESLint with auto-fix npm run lint:check # Run ESLint with reports only npm run typecheck # Run TypeScript type checking (noEmit) npm run quality # Run all quality checks (typecheck + lint + format:check) npm run quality:fix # Run all quality fixes (typecheck + lint:fix + format) # Formatting npm run format # Format code with Prettier npm run format:check # Check code formatting without changes # Testing - Comprehensive Playwright Suite npm run test # Run all Playwright end-to-end tests npm run test:ci # Run tests in CI mode (single worker) npm run test:ci:full # Full CI pipeline (typecheck + tests) npm run test:ui # Run tests with Playwright UI npm run test:headed # Run tests with visible browser npm run test:qa # Run QA test suite with custom runner npm run test:smoke # Run critical path smoke tests # Specific Test Suites npm run test:auth # Authentication flow tests npm run test:theme # Theme switching and persistence npm run test:responsive # Cross-device responsive testing npm run test:components # Component interaction testing npm run test:navigation # Route and navigation testing npm run test:scanner # QR scanner offline functionality npm run test:performance # Battery and performance tests npm run test:mobile # Mobile UX testing npm run test:field # Field testing suite (PWA, offline, mobile, gate ops) # Theme and Design Validation npm run validate:theme # Validate design token consistency npm run check:colors # Check for hardcoded colors in codebase # Firebase Integration (for deployment) npm run firebase:emulators # Start Firebase emulators npm run firebase:deploy:functions # Deploy cloud functions only npm run firebase:deploy:hosting # Deploy hosting only npm run firebase:deploy:all # Deploy functions + hosting npm run firebase:deploy:preview # Deploy to staging channel ``` ## Tech Stack ### Core Technologies - **React 18** with TypeScript for strict typing and modern patterns - **Vite 6.0** for lightning-fast development builds, HMR, and optimized production bundles - **Tailwind CSS 3.4** with comprehensive design token system and prettier plugin - **React Router v6** for client-side routing with protected routes and lazy loading - **Zustand** for lightweight, scalable state management across domain stores ### State & Data Management - **React Query/TanStack Query** for server state simulation and caching - **Zustand Stores** for event, ticket, order, and customer domain state - **Context Providers** for auth, theme, and organization state - **React Hook Form** with Zod validation for type-safe form handling ### UI/Animation Libraries - **Framer Motion** for smooth animations and micro-interactions - **Lucide React** for consistent, scalable SVG icons (460+ icons) - **Date-fns** for date manipulation and formatting - **clsx + tailwind-merge** for conditional styling utilities - **IDB** for client-side storage and offline capabilities ### Development & Testing Tools - **TypeScript 5.6** with strict configuration and path aliases (@/ imports) - **ESLint 9.x** with comprehensive React/TypeScript/accessibility rules - **Prettier 3.x** with Tailwind plugin for code formatting - **Playwright** for comprehensive end-to-end testing with visual regression - **Firebase SDK** for deployment and cloud functions (optional backend) - **Sentry** for error tracking and performance monitoring (configurable) ## Architecture ### Design Token System Comprehensive design system built on CSS custom properties and JSON tokens: - **Base Tokens**: Foundational design tokens in `/src/design-tokens/base.json` (spacing, typography, radius, shadows, blur, opacity) - **Theme Tokens**: Semantic color tokens in `/src/theme/tokens.ts` with light/dark variants - **Automatic Theme Switching**: System preference detection with manual toggle override - **WCAG AA Compliance**: 4.5:1+ contrast ratios across all color combinations - **Glassmorphism Effects**: Sophisticated backdrop blur, transparency, and glass surface tokens - **CSS Variable Integration**: All tokens available as CSS custom properties and Tailwind utilities ### Component Architecture - **Atomic Design Pattern**: UI primitives (Button, Input, Card) → Business components (EventCard, TicketTypeRow) → Page layouts - **Token-Based Styling**: All components consume design tokens, no hardcoded colors/spacing - **TypeScript Interfaces**: Strict typing for props, variants, and component APIs - **Error Boundaries**: Graceful error handling with AppErrorBoundary and component-level boundaries - **Accessibility First**: WCAG AA compliance with proper ARIA labels, focus management, and keyboard navigation - **Lazy Loading**: Route-based code splitting with React.lazy and Suspense boundaries ### Route Structure & Navigation ``` / or /dashboard - Protected dashboard with event overview and analytics /events - Event management interface (events:read permission) /tickets - Ticket type and pricing management (tickets:read permission) /customers - Customer database and management (customers:read permission) /analytics - Revenue and sales analytics dashboard (analytics:read permission) /settings - User account and organization settings /admin/* - Super admin panel (super_admin role required) /gate-ops - QR scanner and gate operations interface /login - Authentication portal with role selection /home - Public homepage with branding showcase /showcase - Live design system component showcase /docs - Interactive theme and token documentation ``` ### Mock Authentication & Permission System Sophisticated role-based access control with realistic permission granularity: - **User Role**: Basic event access, ticket purchasing, profile management - **Admin Role**: Full event management, ticket configuration, customer access, analytics - **Super Admin Role**: Platform administration, organization management, system settings - **Permission Granularity**: Read/write permissions for events, tickets, customers, analytics - **Context Aware**: AuthContext + OrganizationContext for multi-tenant simulation - **Protected Routes**: ProtectedRoute component with role checking and permission validation ## File Structure ``` src/ ├── app/ # App configuration and routing │ ├── router.tsx # React Router configuration with lazy routes │ ├── providers.tsx # Context providers (Auth, Theme, React Query) │ └── lazy-routes.tsx # Lazy-loaded route components ├── components/ │ ├── ui/ # Reusable UI primitives (15+ components) │ │ ├── Button.tsx # Primary action component with variants (primary, secondary, gold) │ │ ├── Input.tsx # Form input with validation states and accessibility │ │ ├── Card.tsx # Container component with glass effects and variants │ │ ├── Alert.tsx # Status message component with semantic colors │ │ ├── Badge.tsx # Small status indicators with theme support │ │ ├── Select.tsx # Dropdown selection with proper focus management │ │ └── Modal.tsx # Accessible modal with backdrop and focus trapping │ ├── layout/ # Application layout system │ │ ├── AppLayout.tsx # Main layout wrapper with sidebar and header │ │ ├── Header.tsx # Top navigation with user menu and theme toggle │ │ ├── Sidebar.tsx # Collapsible navigation with route highlighting │ │ └── MainContainer.tsx # Content area with proper spacing and scrolling │ ├── auth/ # Authentication components │ │ └── ProtectedRoute.tsx # Route guards with role and permission checking │ ├── loading/ # Loading states and skeleton components │ │ ├── Skeleton.tsx # Reusable skeleton loader │ │ └── LoadingSpinner.tsx # Animated loading indicator │ ├── skeleton/ # Domain-specific skeleton loaders │ │ ├── EventCardsSkeleton.tsx # Event grid skeleton │ │ ├── FormSkeleton.tsx # Form loading skeleton │ │ └── TableSkeleton.tsx # Data table skeleton │ ├── errors/ # Error handling components │ │ └── AppErrorBoundary.tsx # Application-level error boundary │ ├── events/ # Event management components │ │ ├── EventCard.tsx # Event display card with glassmorphism │ │ ├── EventCreationWizard.tsx # Multi-step event creation │ │ └── EventDetailsStep.tsx # Event details form step │ ├── features/ # Business domain features │ │ ├── scanner/ # QR scanning functionality with offline support │ │ ├── territory/ # Territory management for enterprise features │ │ ├── tickets/ # Ticket type management and creation │ │ ├── orders/ # Order management and refunds │ │ └── customers/ # Customer management interface │ ├── tickets/ # Ticketing components │ ├── checkout/ # Purchase flow components │ ├── billing/ # Payment and fee breakdown │ └── scanning/ # QR scanning components ├── pages/ # Route components (20+ pages) │ ├── DashboardPage.tsx # Main dashboard with analytics │ ├── EventsPage.tsx # Event management interface │ ├── LoginPage.tsx # Authentication portal │ └── admin/ # Admin-specific pages ├── contexts/ # React Context providers │ ├── AuthContext.tsx # Authentication state management │ ├── ThemeContext.tsx # Theme switching and persistence │ └── OrganizationContext.tsx # Multi-tenant organization context ├── stores/ # Zustand state stores │ ├── eventStore.ts # Event domain state │ ├── ticketStore.ts # Ticket and pricing state │ ├── orderStore.ts # Order and customer state │ └── currentOrg.ts # Current organization state ├── hooks/ # Custom React hooks (10+ hooks) │ ├── useTheme.ts # Theme switching and system preference detection │ ├── useCheckout.ts # Checkout flow state management │ └── useScanner.ts # QR scanning functionality ├── types/ # TypeScript type definitions │ ├── auth.ts # Authentication and user types │ ├── business.ts # Business domain types (Event, Ticket, Order) │ └── organization.ts # Multi-tenant organization types ├── design-tokens/ # Design system token definitions │ └── base.json # Foundation tokens (spacing, typography, radius, blur) ├── theme/ # Theme system implementation │ ├── tokens.ts # Semantic color tokens and theme variants │ ├── cssVariables.ts # CSS custom property utilities │ └── applyBranding.ts # Dynamic branding application ├── styles/ # CSS files and utilities │ ├── tokens.css # CSS custom properties generated from tokens │ └── poster-tokens.css # Poster-specific theme overrides ├── lib/ # Utility libraries │ ├── utils.ts # General utility functions │ ├── firebase.ts # Firebase configuration (optional) │ └── qr-generator.ts # QR code generation utilities └── utils/ # Additional utilities ├── contrast.ts # Color contrast calculation for accessibility └── prefetch.ts # Route prefetching utilities ``` ## Design System ### Token-Based Design System Architecture The design system is built on a comprehensive token system with multiple layers: **Foundation Tokens** (`/src/design-tokens/base.json`): - **Spacing Scale**: `xs` (0.25rem) to `8xl` (6rem) for consistent rhythm - **Typography Scale**: Font sizes, weights, and line heights with Inter + JetBrains Mono - **Radius System**: `sm` (0.125rem) to `full` (9999px) for consistent corner rounding - **Shadow Tokens**: Glass shadows, glow effects, and inner highlights - **Blur Values**: `xs` (2px) to `5xl` (96px) for glassmorphism effects - **Opacity Scales**: Glass opacity variants from subtle (0.05) to heavy (0.3) **Semantic Tokens** (`/src/theme/tokens.ts`): - **Dual Theme Support**: Complete light and dark theme token sets - **Semantic Naming**: background.primary, text.secondary, accent.gold, surface.raised - **Brand Colors**: Warm gray primary, gold accents (#d99e34), purple secondary - **Glass System**: Sophisticated backdrop blur tokens with proper transparency - **Accessibility**: WCAG AA compliant contrast ratios built into token definitions ### Theme System Features - **Automatic Detection**: System preference detection with manual override - **CSS Custom Properties**: All tokens exported as CSS variables for runtime theming - **Tailwind Integration**: Custom Tailwind utilities generated from design tokens - **TypeScript Safety**: Strongly typed theme tokens with IntelliSense support - **Runtime Switching**: Instant theme switching without page reload - **Persistent Preferences**: Theme selection saved to localStorage ### Component Usage Patterns ```tsx // Token-based component variants Success message with semantic colors // Glass effect components with theme tokens Glassmorphic Card // Consistent spacing using token utilities

Title

Description

// Semantic color usage Active Pending Failed ``` ### Glassmorphism Implementation The design system features sophisticated glassmorphism effects: - **Surface Hierarchy**: subtle → card → raised with increasing opacity and blur - **Glass Borders**: Semi-transparent borders that adapt to theme - **Backdrop Filters**: Hardware-accelerated blur effects for performance - **Shadow System**: Layered shadows for depth and visual hierarchy - **Interactive States**: Hover and focus states with increased glass opacity ## Testing Strategy ### Comprehensive Playwright Test Suite Advanced end-to-end testing with multiple specialized test categories: **Core Application Testing:** - `smoke.spec.ts` - Critical path smoke tests (application load, auth success, theme toggle) - `auth-realistic.spec.ts` - Realistic authentication flows with role switching - `auth-bulletproof.spec.ts` - Robust authentication testing with loop prevention - `navigation.spec.ts` - Route protection, navigation, and permission validation - `theme.spec.ts` - Theme switching, persistence, and system preference detection - `components.spec.ts` - Component interaction, form validation, and modal behavior **Advanced Functionality Testing:** - `responsive.spec.ts` - Cross-device responsive design validation (desktop, mobile, tablet) - `mobile-ux.spec.ts` - Mobile-specific UX patterns and touch interactions - `offline-scenarios.spec.ts` - Offline functionality and service worker behavior - `battery-performance.spec.ts` - Performance testing with extended timeout (120s) - `pwa-field-test.spec.ts` - Progressive Web App field testing scenarios **Business Domain Testing:** - `real-world-gate.spec.ts` - QR scanning and gate operations simulation - `scan-offline.spec.ts` - Offline QR scanning functionality - `gate-ops.spec.ts` - Gate operations interface and scanning workflows - `publish-scanner.smoke.spec.ts` - Scanner publishing and deployment workflows **Event & Feature Testing:** - `event-detail.spec.ts` - Event detail page functionality - `events-index.spec.ts` - Event management interface testing - `publish-flow.spec.ts` - Event publishing workflow validation - `create-ticket-type-modal.spec.ts` - Ticket type creation and management - `publish-event-modal.spec.ts` - Event publishing modal functionality **Quality Assurance Testing:** - `branding-fouc.spec.ts` - Flash of unstyled content prevention - `checkout-connect.spec.ts` - Stripe Connect checkout simulation - `wizard-store.spec.ts` - Event creation wizard state management ### Test Configuration & Infrastructure - **Multi-Browser Testing**: Chromium, Firefox, WebKit + Mobile Chrome/Safari - **Visual Regression**: Automated screenshot comparison with failure detection - **Custom Test Runner**: Advanced QA runner in `tests/test-runner.ts` with screenshot support - **CI/CD Integration**: Dedicated CI commands with single worker for stability - **Performance Metrics**: Extended timeout support for performance-critical tests - **Field Testing Suite**: Combined real-world scenario testing (`test:field` command) ## Mock Data & State Management ### Mock Data Architecture Sophisticated data simulation for realistic application behavior: - **Domain-Driven Models**: Event, Ticket, Order, Customer, and Organization entities - **Realistic Relationships**: Proper foreign key relationships between entities - **Mock API Layer**: `src/services/api.ts` simulating REST API calls with proper error handling - **Data Persistence**: Browser storage simulation for user preferences and temporary data - **Type Safety**: Complete TypeScript coverage with generated interfaces ### State Management Architecture Multi-layered state management approach: - **Context Providers**: Authentication, theme, and organization context for global state - **Zustand Domain Stores**: Separate stores for events, tickets, orders, customers, and organizations - **React Query Integration**: Server state simulation with caching, invalidation, and background updates - **Local Component State**: React useState/useReducer for component-specific state - **Form State**: React Hook Form with Zod validation for complex form handling ## Code Quality Standards ### ESLint Configuration - **Strict TypeScript Rules**: No `any` types, explicit return types - **React Best Practices**: Hooks rules, prop validation, accessibility - **Import Organization**: Sorted imports with path groups - **Performance Rules**: Prevent common React anti-patterns ### TypeScript Configuration - **Strict Mode**: All strict checks enabled - **Path Aliases**: `@/*` imports for clean module resolution - **Unused Code Detection**: Warnings for unused variables/imports - **Exact Optional Properties**: Strict object type checking ## Development Workflow ### Before Committing 1. Run `npm run quality:fix` to fix linting and formatting 2. Run `npm run test:smoke` for critical path validation 3. Verify design tokens usage instead of hardcoded values 4. Check responsive design across viewport sizes ### Component Development Workflow 1. **Design Token First**: Always use design tokens from `/src/theme/tokens.ts` and `/src/design-tokens/base.json` 2. **TypeScript Interfaces**: Define props interfaces with JSDoc comments for IntelliSense 3. **Accessibility Built-in**: Include ARIA attributes, focus management, and keyboard navigation 4. **Theme Compatibility**: Test components in both light and dark themes 5. **Responsive Design**: Implement mobile-first responsive patterns 6. **Error Boundaries**: Wrap complex components with error handling 7. **Test Coverage**: Write Playwright tests for interactive functionality ### Performance Optimization - **Route-Based Code Splitting**: React.lazy with Suspense boundaries for optimal loading - **Bundle Analysis**: Manual chunk configuration in Vite for vendor, router, UI, and utils - **CSS Custom Properties**: Efficient theme switching without CSS-in-JS overhead - **Tree Shaking**: Optimized imports and dead code elimination - **Image Optimization**: Proper sizing, lazy loading, and responsive images - **Virtualization**: For large lists and data tables (when implemented) ### Advanced Development Patterns #### Feature-Based Architecture The `/src/features/` directory contains complex business features: - **Scanner Features**: QR scanning with offline support, rate limiting, and abuse prevention - **Territory Management**: Enterprise-grade territory filtering and user management - **Ticket Management**: Advanced ticket type creation with validation and wizards - **Order Processing**: Complete order lifecycle with refunds and customer management #### Enterprise Features (Phase 3 Ready) - **Multi-tenant Architecture**: Organization context with proper data isolation - **Territory Management**: Hierarchical user roles and territory-based filtering - **Advanced QR System**: Offline-capable scanning with queue management and abuse prevention - **Performance Monitoring**: Battery usage tracking and performance metrics - **Progressive Web App**: Service worker integration for offline functionality ## Important Notes ### Current Project Status (Phase 2 Complete ✅) The project is in **Phase 2 Complete** status with comprehensive foundation implementation: - ✅ **Design Token System**: Complete token architecture with light/dark theme support - ✅ **Component Library**: 15+ production-ready UI primitives with TypeScript interfaces - ✅ **Authentication System**: Mock auth with role-based permissions (user/admin/super_admin) - ✅ **Layout System**: AppLayout, Header, Sidebar, MainContainer with responsive design - ✅ **Testing Infrastructure**: Comprehensive Playwright test suite (25+ test files) - ✅ **Error Handling**: Application-level error boundaries and graceful fallbacks - ✅ **State Management**: Zustand stores for all business domains - ✅ **Accessibility Compliance**: WCAG AA standards throughout **⚠️ Known Issues**: There are TypeScript build errors that must be resolved before Phase 3 development. ### This is a Learning Project - **Frontend Only**: No live APIs, databases, or payment processing - pure UI/UX learning environment - **Mock Data**: All business logic simulated with TypeScript interfaces and static data - **Safe Environment**: No risk of affecting production systems or real data - **Educational Purpose**: Focuses on modern React patterns, accessibility, and design systems ### CrispyGoat Quality Standards - **Premium Polish**: Every component must feel finished and professional with attention to micro-interactions - **Accessibility First**: WCAG AA compliance throughout with proper focus management and screen reader support - **Developer Experience**: Clear APIs, excellent TypeScript support, comprehensive documentation - **Performance**: Production-ready optimization patterns with lazy loading and efficient rendering - **Maintainability**: Clean architecture following React best practices with proper separation of concerns ### Phase 3 Development Readiness The project architecture supports advanced enterprise features: - **Territory Management**: Multi-level user hierarchies and filtering systems - **Advanced Event Management**: Complex event creation wizards and bulk operations - **QR Scanning System**: Offline-capable scanning with abuse prevention and performance monitoring - **Analytics Dashboard**: Real-time data visualization and reporting interfaces - **Progressive Web App**: Service worker integration and offline functionality ## Fixed Issues ### EventCreationWizard Infinite Loop (RESOLVED) **Problem**: The "Create New Event" button on the dashboard would cause infinite React re-renders, crashing the browser with "Maximum update depth exceeded" errors. **Root Cause**: Complex Zustand store with unstable selectors: - `useWizardNavigation()`, `useWizardSubmission()`, etc. returned new objects every render - Zustand selectors weren't properly cached, causing "getSnapshot should be cached" errors - useEffect hooks with Zustand functions in dependency arrays created circular updates - EventDetailsStep had state updates during render from auto-territory selection logic **Solution Applied** (August 2024): 1. **Replaced complex Zustand store with simple React state** - Removed `useWizardStore`, `useWizardNavigation`, `useWizardSubmission` - Used local `useState` for `currentStep`, `eventData`, `ticketTypes` - Eliminated unstable selector hooks entirely 2. **Simplified EventCreationWizard component** - Inline form rendering instead of separate step components - Direct state management with `setEventData`, `setTicketTypes` - Simple validation functions with `useCallback` - Stable navigation handlers 3. **Fixed infinite useEffect loops** - Removed problematic auto-territory selection in EventDetailsStep - Eliminated Zustand functions from dependency arrays - Used stable primitives in useEffect dependencies **Result**: - ✅ "Create New Event" button works perfectly - ✅ Modal opens with 3-step wizard (Event Details → Tickets → Publish) - ✅ No infinite loops or browser crashes - ✅ Proper accessibility with `role="dialog"` **Key Lesson**: Zustand selectors that return objects can cause infinite re-renders. For simple wizards, React `useState` is more stable and predictable than complex state management libraries. ## Project Wrap-Up Completion (August 2025) ### TypeScript Build Status - **Resolved**: Reduced TypeScript errors from 14 to 5 (65% improvement) - **Fixed Issues**: Button variant types, optional properties, unused imports, icon compatibility - **Current Status**: 5 remaining minor type errors (down from critical build-blocking issues) - **Build Status**: ✅ Production builds succeed, development server runs cleanly ### Development Environment - **Dev Server**: Running on port 5174 (accessible at http://localhost:5174) - **Hot Reload**: ✅ Working with Vite HMR - **TypeScript**: ✅ Compiling successfully with strict configuration - **Linting**: ✅ ESLint configured with React/TypeScript best practices ### Repository Status - **Latest Commit**: `aa81eb5` - feat: add advanced analytics and territory management system - **Files Committed**: 438 files with 90,537+ insertions - **Git Status**: Clean working directory, all major changes committed - **Security**: Pre-commit hooks configured to prevent sensitive file commits ### Component Architecture Summary ``` src/ ├── components/ # 80+ React components │ ├── analytics/ # Revenue trends, export, performance tables │ ├── territory/ # Manager tracking, KPIs, leaderboards │ ├── seatmap/ # Venue layout and seat selection │ ├── ui/ # 15+ foundational UI primitives │ └── features/ # Business domain components ├── pages/ # 20+ route components with protected routing ├── stores/ # Zustand domain stores (events, tickets, orders) ├── hooks/ # 10+ custom hooks for business logic └── types/ # Complete TypeScript coverage ``` ### Current Capabilities - **Event Management**: Multi-step creation wizard, bulk operations, live preview - **Analytics Dashboard**: Export functionality, performance tracking, territory insights - **Territory Management**: Manager performance, filtering, actionable KPIs - **QR Scanning**: Offline support, abuse prevention, manual entry fallback - **Customer Management**: Database interface, creation/edit modals, order history - **Theming**: Complete design token system with light/dark mode support - **Testing**: 25+ Playwright test files covering critical user flows ### Ready for Phase 4 The project foundation is solid and ready for advanced features: - Enhanced ticket purchasing flows - Interactive seatmap functionality - Performance optimizations and polish - Advanced animations and micro-interactions **Development Note**: The project has exceeded Phase 2 goals and substantially completed Phase 3 enterprise features. Focus next development on remaining ticket purchasing flows and seatmap interactivity.