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.

**🚨 IMPORTANT: Check REBUILD_PLAN.md for current status and Phase 3 roadmap before making any changes.**

## Development Commands

```bash
# Development
npm run dev          # Start development server at localhost:5173
npm run build        # Type check and build for production  
npm run preview      # Preview production build locally

# Code Quality
npm run lint         # Run ESLint on codebase
npm run lint:fix     # Run ESLint with auto-fix
npm run typecheck    # Run TypeScript type checking
npm run quality      # Run all quality checks (typecheck + lint + format:check)
npm run quality:fix  # Run all quality fixes (typecheck + lint:fix + format)

# Testing
npm run test         # Run Playwright end-to-end 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 screenshots
npm run test:smoke   # Run smoke tests for critical paths
npm run test:auth    # Run authentication flow tests
npm run test:theme   # Run theme switching tests
npm run test:responsive # Run responsive design tests
npm run test:components # Run component interaction tests

# Formatting
npm run format       # Format code with Prettier
npm run format:check # Check code formatting
```

## Tech Stack

### Core Technologies
- **React 18** with TypeScript for strict typing and modern patterns
- **Vite** for lightning-fast development builds and HMR
- **Tailwind CSS** with comprehensive design token system
- **React Router v6** for client-side routing with protected routes
- **Zustand** for lightweight, scalable state management

### UI/Animation Libraries
- **Framer Motion** for smooth animations and micro-interactions
- **Lucide React** for consistent, scalable SVG icons
- **React Hook Form** with Zod validation for type-safe forms
- **Date-fns** for date manipulation and formatting

### Development Tools
- **TypeScript** with strict configuration and path aliases
- **ESLint** with comprehensive React/TypeScript/accessibility rules
- **Prettier** with Tailwind plugin for code formatting
- **Playwright** for end-to-end testing with visual regression

## Architecture

### Design Token System
Comprehensive CSS custom property system supporting:
- **Dual Theme Support**: Automatic light/dark mode with system preference detection
- **Semantic Colors**: Background, text, border, and accent colors with proper contrast ratios
- **Typography Scale**: Consistent font sizes, weights, and line heights
- **Spacing System**: 8px grid-based spacing tokens
- **Glass Effects**: Backdrop blur and transparency utilities
- **Animation Tokens**: Consistent timing functions and keyframes

### Component Architecture
- **Atomic Design**: Reusable primitives (Button, Input) composed into complex organisms
- **Token-Based Styling**: All components use design tokens for consistent theming
- **TypeScript Interfaces**: Strict typing for props, state, and component APIs
- **Error Boundaries**: Graceful error handling at component and route levels
- **Accessibility First**: WCAG AA compliance built into all components

### Route Structure
```
/ or /dashboard     - Protected dashboard with event overview
/events            - Event management interface (events:read permission)
/tickets           - Ticket management (tickets:read permission)
/customers         - Customer management (customers:read permission) 
/analytics         - Analytics dashboard (analytics:read permission)
/settings          - User account settings
/admin/*           - Admin panel (admin role required)
/login             - Authentication portal
/home              - Public homepage
/showcase          - Design system showcase
/docs              - Theme documentation
```

### Mock Authentication System
Role-based access control with three tiers:
- **User**: Basic event access and ticket purchasing
- **Admin**: Event management and organization features
- **Super Admin**: Full platform administration

## File Structure

```
src/
├── components/
│   ├── ui/                 # Reusable UI primitives
│   │   ├── Button.tsx      # Primary action component with variants
│   │   ├── Input.tsx       # Form input with validation states
│   │   ├── Card.tsx        # Container component with glass effects
│   │   ├── Alert.tsx       # Status message component
│   │   ├── Badge.tsx       # Small status indicators
│   │   └── Select.tsx      # Dropdown selection component
│   ├── layout/             # Layout and navigation
│   │   ├── AppLayout.tsx   # Main application layout wrapper
│   │   ├── Header.tsx      # Top navigation with user menu
│   │   ├── Sidebar.tsx     # Collapsible navigation sidebar
│   │   └── MainContainer.tsx # Content area with proper spacing
│   ├── auth/               # Authentication components
│   │   └── ProtectedRoute.tsx # Route guards with permission checks
│   ├── loading/            # Loading states and skeletons
│   ├── errors/             # Error boundaries and fallback UI
│   ├── events/             # Event-related components
│   ├── tickets/            # Ticketing and purchase components
│   ├── checkout/           # Purchase flow components
│   ├── billing/            # Payment and fee breakdown
│   └── scanning/           # QR scanning components
├── pages/                  # Route components
├── contexts/               # React Context providers
├── hooks/                  # Custom React hooks
├── types/                  # TypeScript type definitions
├── design-tokens/          # Design system token definitions
└── styles/                 # CSS files and utilities
```

## Design System

### Theme Configuration
The application supports automatic theme switching with:
- **CSS Custom Properties**: Token-based design system in `/src/design-tokens/`
- **Tailwind Integration**: All tokens available as Tailwind utilities
- **WCAG AA Compliance**: 4.5:1+ contrast ratios across all color combinations
- **Glass Effects**: Sophisticated backdrop blur and transparency patterns

### Component Usage Patterns
```tsx
// Design token-based styling
<Button variant="primary" size="lg" className="bg-primary-500 text-primary-text">
  Action Button
</Button>

// Glass effect utilities
<Card className="bg-glass-bg backdrop-blur-lg border-glass-border">
  <Card.Header>Glass Card</Card.Header>
</Card>

// Responsive spacing with tokens
<div className="p-lg md:p-xl space-y-md">
  Content with consistent spacing
</div>
```

## Testing Strategy

### Playwright Test Suite
Comprehensive coverage including:
- **Authentication Flows**: Login/logout with all user roles
- **Navigation Testing**: Route guards and permission checks
- **Component Interactions**: Form submissions and modal behaviors
- **Responsive Design**: Mobile and desktop viewport testing
- **Theme Switching**: Light/dark mode persistence
- **Visual Regression**: Automated screenshot comparisons

### Test Organization
- `smoke.spec.ts` - Critical path smoke tests
- `auth.spec.ts` - Authentication flow validation
- `navigation.spec.ts` - Route and navigation testing
- `theme.spec.ts` - Theme switching and persistence
- `responsive.spec.ts` - Cross-device responsive testing
- `components.spec.ts` - Component interaction testing

## Mock Data System

All data is simulated using TypeScript interfaces and static mock data:
- **No Database Connections**: Pure frontend learning environment
- **Realistic Data Structures**: Mirrors production BCT schemas
- **Type Safety**: Full TypeScript coverage for mock APIs
- **State Management**: Zustand stores for different data domains

## 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
1. Start with design tokens for colors, spacing, and typography
2. Implement TypeScript interfaces before implementation
3. Add proper accessibility attributes and ARIA labels
4. Test component with both light and dark themes
5. Write Playwright tests for interactive components

### Performance Considerations
- **Code Splitting**: Route-based lazy loading with React.lazy
- **Tree Shaking**: Optimized imports and bundle analysis
- **Design Token Efficiency**: CSS custom properties reduce bundle size
- **Image Optimization**: Proper sizing and lazy loading

## Important Notes

### This is a Learning Project
- **Frontend Only**: No live APIs, databases, or payment processing
- **Mock Authentication**: Simulated user sessions and permissions
- **Static Data**: All content served from TypeScript mock files
- **Safe Environment**: No risk of affecting production systems

### CrispyGoat Quality Standards
- **Premium Polish**: Every component must feel finished and professional
- **Accessibility First**: WCAG AA compliance throughout
- **Developer Experience**: Clear APIs, excellent TypeScript support
- **Performance**: Production-ready optimization patterns
- **Maintainability**: Clean architecture and comprehensive documentation