feat: add advanced analytics and territory management system

- Add comprehensive analytics components with export functionality - Implement territory management with manager performance tracking - Add seatmap components for venue layout management - Create customer management features with modal interface - Add advanced hooks for dashboard flags and territory data - Implement seat selection and venue management utilities - Add type definitions for ticketing and seatmap systems 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-26 09:25:10 -06:00
parent d5c3953888
commit aa81eb5adb
438 changed files with 90509 additions and 2787 deletions
--- a/reactrebuild0825/WHITELABEL.md
+++ b/reactrebuild0825/WHITELABEL.md
@@ -0,0 +1,330 @@
+# Whitelabel Branding & Domains System
+
+This document describes the comprehensive whitelabel system that allows organizations to customize their Black Canyon Tickets platform with their own branding and serve it on custom domains.
+
+## Overview
+
+The whitelabel system provides:
+
+1. **Host-based Organization Resolution** - Automatically detects organization from the current domain
+2. **Dynamic Theming** - Per-organization color themes applied at runtime without FOUC
+3. **Custom Domain Management** - Admin UI for adding and verifying custom domains
+4. **Branding Management** - Upload logos and customize color schemes with live preview
+5. **DNS Verification** - Secure domain ownership verification via TXT records
+
+## Architecture
+
+### Backend (Firebase Functions)
+
+#### Domain Resolution API
+- **Endpoint**: `GET /api/domains/resolve?host=tickets.acme.com`
+- **Purpose**: Resolves organization data from hostname
+- **Returns**: Organization ID, branding data, and domain list
+- **Fallback**: Supports subdomain pattern (e.g., `acme.bct.dev`)
+
+#### Domain Verification APIs
+- **Request Verification**: `POST /api/domains/request-verification`
+  - Generates DNS TXT record token
+  - Updates organization domain list
+  - Returns DNS configuration instructions
+  
+- **Verify Domain**: `POST /api/domains/verify`
+  - Checks DNS TXT record for verification token
+  - Updates domain status to verified
+  - Enables domain for live use
+
+#### Firestore Schema
+
+```typescript
+// Collection: organizations/{orgId}
+interface Organization {
+  id: string;
+  name: string;
+  slug: string;
+  branding: {
+    logoUrl?: string;
+    faviconUrl?: string;
+    theme: {
+      accent: string;        // e.g., '#F0C457'
+      bgCanvas: string;      // e.g., '#2B2D2F'
+      bgSurface: string;     // e.g., '#34373A'
+      textPrimary: string;   // e.g., '#F1F3F5'
+      textSecondary: string; // e.g., '#C9D0D4'
+    }
+  };
+  domains: Array<{
+    host: string;              // e.g., 'tickets.acme.com'
+    verified: boolean;
+    createdAt: string;
+    verifiedAt?: string;
+    verificationToken?: string; // DNS TXT record value
+  }>;
+}
+```
+
+### Frontend Architecture
+
+#### Organization Bootstrap System
+- **Early Resolution**: Runs before React mounts to prevent FOUC
+- **Theme Application**: Applies CSS custom properties immediately
+- **Logo/Favicon**: Updates page branding elements
+- **Store Integration**: Bridges bootstrap data to React state
+
+#### Theme System
+- **CSS Variables**: All colors mapped to custom properties
+- **Tailwind Integration**: Utilities consume CSS variables
+- **Live Preview**: Real-time theme changes during admin editing
+- **Accessibility**: Validates contrast ratios (WCAG AA)
+
+#### State Management
+- **Zustand Store**: Reactive organization data management
+- **Context Provider**: React integration and effect handling
+- **Subscriptions**: Automatic theme updates on organization changes
+
+## File Structure
+
+```
+src/
+├── stores/
+│   └── organizationStore.ts          # Zustand store for org data
+├── theme/
+│   ├── orgTheme.ts                   # Theme application utilities
+│   └── orgBootstrap.ts               # Early resolution system
+├── contexts/
+│   └── OrganizationContext.tsx       # React provider integration
+├── features/org/
+│   ├── BrandingSettings.tsx          # Logo/theme management UI
+│   └── DomainSettings.tsx            # Custom domain management UI
+└── tests/
+    └── whitelabel.spec.ts            # Comprehensive test suite
+
+functions/src/
+└── domains.ts                        # Cloud Functions for domain APIs
+```
+
+## Usage Guide
+
+### For Organizations
+
+#### Setting Up Branding
+1. Navigate to Organization → Branding in the user menu
+2. Upload your organization logo (PNG, JPG, SVG up to 2MB)
+3. Customize theme colors using color pickers
+4. Enable "Live Preview" to see changes in real-time
+5. Save changes to apply across all sessions
+
+#### Adding Custom Domains
+1. Navigate to Organization → Domains in the user menu
+2. Click "Add Custom Domain" and enter your domain (e.g., `tickets.acme.com`)
+3. Follow DNS configuration instructions:
+   - Add TXT record: `_bct-verification.tickets.acme.com`
+   - Set value to the provided verification token
+   - Wait for DNS propagation (up to 24 hours)
+4. Click "Check Verification" to validate DNS setup
+5. Once verified, your domain is ready for live use
+
+### For Developers
+
+#### Theme Development
+```typescript
+import { applyOrgTheme, generateThemeCSS } from '../theme/orgTheme';
+
+// Apply theme programmatically
+applyOrgTheme({
+  accent: '#FF6B35',
+  bgCanvas: '#1A1B1E',
+  bgSurface: '#2A2B2E',
+  textPrimary: '#FFFFFF',
+  textSecondary: '#B0B0B0',
+});
+
+// Generate CSS for external use
+const css = generateThemeCSS(theme);
+```
+
+#### Organization Data Access
+```typescript
+import { useCurrentOrganization } from '../contexts/OrganizationContext';
+import { useOrganizationStore } from '../stores/organizationStore';
+
+// In React components
+const { organization, isLoading, error } = useCurrentOrganization();
+
+// Direct store access
+const currentOrg = useOrganizationStore(state => state.currentOrg);
+```
+
+#### Custom Domain Testing
+```typescript
+// Mock domain resolution in tests
+await page.route('**/resolveDomain*', async route => {
+  await route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      orgId: 'test-org',
+      name: 'Test Organization',
+      branding: { theme: { /* colors */ } },
+      domains: []
+    })
+  });
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+#### Development
+```bash
+# Local Firebase Functions
+FUNCTIONS_BASE_URL=http://localhost:5001/bct-whitelabel-0825/us-central1
+
+# Enable development mode (mocks DNS verification)
+NODE_ENV=development
+FUNCTIONS_EMULATOR=true
+```
+
+#### Production
+```bash
+# Production Firebase Functions
+FUNCTIONS_BASE_URL=https://us-central1-bct-whitelabel-0825.cloudfunctions.net
+
+# Real DNS verification
+NODE_ENV=production
+```
+
+### CSS Variables Mapping
+
+The theme system maps organization colors to these CSS custom properties:
+
+```css
+:root {
+  --color-accent-500: /* theme.accent */
+  --color-bg-canvas: /* theme.bgCanvas */
+  --color-bg-surface: /* theme.bgSurface */
+  --color-text-primary: /* theme.textPrimary */
+  --color-text-secondary: /* theme.textSecondary */
+}
+```
+
+All Tailwind utilities (e.g., `bg-accent-500`, `text-primary`) automatically use these variables.
+
+## Testing
+
+### Running Tests
+```bash
+# Run whitelabel-specific tests
+npm run test -- whitelabel.spec.ts
+
+# Run with UI for debugging
+npm run test:ui -- whitelabel.spec.ts
+
+# Run in headed mode to see browser
+npm run test:headed -- whitelabel.spec.ts
+```
+
+### Test Coverage
+- **Domain Resolution**: Host-based organization lookup
+- **Theme Application**: CSS variable injection and FOUC prevention
+- **Branding UI**: Logo upload, color editing, live preview
+- **Domain Management**: Add/verify/delete custom domains
+- **Error Handling**: Graceful fallbacks for missing organizations
+- **Accessibility**: Color contrast validation
+
+### Mock Data
+Tests use realistic mock organizations and domain data. See `tests/whitelabel.spec.ts` for examples.
+
+## Security Considerations
+
+### Domain Verification
+- **DNS TXT Records**: Prevents unauthorized domain claiming
+- **Token Generation**: Cryptographically secure verification tokens
+- **Rate Limiting**: Built into Firebase Functions
+- **Validation**: Strict domain format checking
+
+### Asset Upload
+- **File Types**: Restricted to images only (PNG, JPG, SVG)
+- **Size Limits**: 2MB maximum file size
+- **Storage**: Firebase Storage with security rules
+- **Sanitization**: Image processing to prevent malicious uploads
+
+### Theme Injection
+- **XSS Prevention**: Color values validated as hex codes only
+- **CSS Injection**: No arbitrary CSS allowed, only predefined variables
+- **Contrast Validation**: Ensures accessibility compliance
+
+## Performance
+
+### Bootstrap Optimization
+- **Early Execution**: Runs before React hydration
+- **Caching**: Organization data cached in localStorage
+- **Minimal Dependencies**: Lightweight bootstrap script
+- **Error Resilience**: Continues with defaults if resolution fails
+
+### Theme Application
+- **CSS Variables**: More efficient than class switching
+- **No Re-renders**: Theme changes don't trigger React re-renders
+- **Bundle Size**: Design tokens reduce CSS payload
+- **Memory Usage**: Minimal runtime footprint
+
+## Troubleshooting
+
+### Domain Verification Issues
+1. **DNS Propagation**: Can take up to 24 hours globally
+2. **Record Format**: Ensure TXT record name includes subdomain
+3. **Value Accuracy**: Copy verification token exactly as provided
+4. **TTL Settings**: Use 300 seconds for faster propagation during setup
+
+### Theme Not Applying
+1. **Organization Resolution**: Check browser console for resolution errors
+2. **CSS Variables**: Inspect element to verify variables are set
+3. **Cache Issues**: Clear localStorage and refresh page
+4. **API Connectivity**: Verify Functions endpoints are accessible
+
+### Logo Display Issues
+1. **File Format**: Use PNG, JPG, or SVG only
+2. **CORS Policy**: Ensure image URLs allow cross-origin requests
+3. **Size Optimization**: Large images may slow page load
+4. **Fallback Handling**: App continues without logo if load fails
+
+## Future Enhancements
+
+### Planned Features
+- **Favicon Customization**: Dynamic favicon updates
+- **Email Templates**: Per-organization email branding
+- **Font Selection**: Custom typography options
+- **Advanced Themes**: Gradient and pattern support
+- **White-label Mobile**: Native app theming
+- **Analytics Integration**: Usage tracking per organization
+
+### API Improvements
+- **Real DNS Resolution**: Replace mock DNS with actual lookups
+- **CDN Integration**: Optimize asset delivery
+- **Webhook Support**: Real-time domain status updates
+- **Bulk Operations**: Mass domain import/export
+- **API Keys**: Third-party integration authentication
+
+---
+
+## Quick Start Checklist
+
+For new organizations wanting to set up whitelabel branding:
+
+- [ ] Upload organization logo in Branding Settings
+- [ ] Customize theme colors to match brand
+- [ ] Test live preview functionality
+- [ ] Add custom domain in Domain Settings
+- [ ] Configure DNS TXT record with provided token
+- [ ] Verify domain ownership
+- [ ] Test live site on custom domain
+- [ ] Update any hardcoded URLs in marketing materials
+
+For developers integrating whitelabel features:
+
+- [ ] Review organization store and context usage
+- [ ] Understand theme CSS variable system
+- [ ] Test with multiple mock organizations
+- [ ] Implement proper error boundaries
+- [ ] Add accessibility validation for custom themes
+- [ ] Write tests for new organization-specific features