blackcanyontickets/reactrebuild0825/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 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

# 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

// Token-based component variants
<Button variant="primary" size="lg">Primary Action</Button>
<Button variant="gold" size="md">Gold Accent Button</Button>
<Alert level="success">Success message with semantic colors</Alert>

// Glass effect components with theme tokens
<Card className="bg-surface-card backdrop-blur-lg border-glass-border">
  <Card.Header>Glassmorphic Card</Card.Header>
</Card>

// Consistent spacing using token utilities
<div className="space-y-md p-lg md:p-xl">
  <h1 className="text-4xl font-bold text-text-primary">Title</h1>
  <p className="text-base text-text-secondary">Description</p>
</div>

// Semantic color usage
<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="error">Failed</Badge>

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.