diff --git a/reactrebuild0825/SCANNER_TECHNICAL_RUNBOOK.md b/reactrebuild0825/SCANNER_TECHNICAL_RUNBOOK.md new file mode 100644 index 0000000..0f53c9d --- /dev/null +++ b/reactrebuild0825/SCANNER_TECHNICAL_RUNBOOK.md @@ -0,0 +1,1037 @@ +# Scanner PWA Technical Runbook + +## System Architecture Overview + +The Black Canyon Tickets Scanner PWA is an offline-first Progressive Web App designed for gate staff to scan tickets with comprehensive abuse prevention and mobile optimization. + +### Core Components +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Scanner PWA Architecture │ +├─────────────────────────────────────────────────────────────────┤ +│ Frontend (React PWA) │ Backend APIs │ +│ ├── Camera/QR Detection │ ├── /api/tickets/verify │ +│ ├── Offline Queue (IndexedDB) │ ├── /api/scans/log │ +│ ├── Background Sync (SW) │ ├── /api/scanner/sync │ +│ ├── Rate Limiting Client │ └── /api/scanner/conflicts │ +│ └── Abuse Prevention UI │ │ +├─────────────────────────────────────────────────────────────────┤ +│ Infrastructure │ Monitoring │ +│ ├── Supabase/Firebase DB │ ├── Sentry Error Tracking │ +│ ├── CDN (Vercel/Netlify) │ ├── Performance Monitoring │ +│ ├── SSL/HTTPS (Required) │ ├── Real-time Alerts │ +│ └── Service Worker Caching │ └── Usage Analytics │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Environment Setup + +### Staging Environment Configuration + +#### Environment Variables +```bash +# Database Configuration +VITE_SUPABASE_URL=https://staging-scanner.supabase.co +VITE_SUPABASE_ANON_KEY=eyJ...staging-key +SUPABASE_SERVICE_ROLE_KEY=eyJ...service-key + +# Scanner API Configuration +VITE_SCANNER_API_URL=https://staging-api.blackcanyontickets.com +VITE_SCANNER_RATE_LIMIT=8 +VITE_SCANNER_DEBOUNCE_MS=2000 + +# PWA Configuration +VITE_PWA_NAME=BCT Scanner (Staging) +VITE_PWA_SHORT_NAME=BCT Scanner +VITE_PWA_THEME_COLOR=#1e40af + +# Monitoring Configuration +VITE_SENTRY_DSN=https://staging@sentry.io/project +SENTRY_ENVIRONMENT=staging +SENTRY_RELEASE=$VERCEL_GIT_COMMIT_SHA + +# Feature Flags +VITE_SCANNER_OFFLINE_ENABLED=true +VITE_ABUSE_PREVENTION_ENABLED=true +VITE_DEVICE_TRACKING_ENABLED=true +``` + +#### Deployment Configuration + +**Vercel (Recommended)** +```json +{ + "buildCommand": "npm run build", + "outputDirectory": "dist", + "installCommand": "npm ci", + "framework": "vite", + "functions": { + "api/**/*.ts": { + "runtime": "nodejs18.x" + } + }, + "headers": [ + { + "source": "/sw.js", + "headers": [ + { + "key": "Cache-Control", + "value": "public, max-age=0, must-revalidate" + } + ] + } + ] +} +``` + +**Netlify Alternative** +```toml +[build] + command = "npm run build" + publish = "dist" + +[[headers]] + for = "/sw.js" + [headers.values] + Cache-Control = "public, max-age=0, must-revalidate" + +[[headers]] + for = "/manifest.json" + [headers.values] + Cache-Control = "public, max-age=86400" +``` + +### Production Environment + +#### SSL/HTTPS Requirements +- **Camera API:** Requires HTTPS for getUserMedia() access +- **Service Workers:** HTTPS required for PWA functionality +- **Geolocation:** HTTPS required for location services +- **Web Push:** HTTPS required for background sync + +#### Database Configuration +```sql +-- Scanner-specific tables +CREATE TABLE scanner_logs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + device_id VARCHAR(255) NOT NULL, + event_id UUID NOT NULL, + qr_code VARCHAR(500) NOT NULL, + scan_result VARCHAR(50) NOT NULL, -- 'valid', 'invalid', 'already_scanned' + scan_timestamp TIMESTAMPTZ DEFAULT NOW(), + zone VARCHAR(100), + sync_status VARCHAR(50) DEFAULT 'synced', + created_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE TABLE scan_conflicts ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + device_id VARCHAR(255) NOT NULL, + qr_code VARCHAR(500) NOT NULL, + offline_result VARCHAR(50) NOT NULL, + server_result VARCHAR(50) NOT NULL, + event_id UUID NOT NULL, + conflict_timestamp TIMESTAMPTZ DEFAULT NOW(), + resolution_status VARCHAR(50) DEFAULT 'pending' +); + +-- Indexes for performance +CREATE INDEX idx_scanner_logs_device_event ON scanner_logs(device_id, event_id); +CREATE INDEX idx_scanner_logs_timestamp ON scanner_logs(scan_timestamp DESC); +CREATE INDEX idx_scan_conflicts_unresolved ON scan_conflicts(resolution_status) + WHERE resolution_status = 'pending'; +``` + +## API Endpoints and Integration + +### Core Scanner APIs + +#### 1. Ticket Verification Endpoint +```typescript +POST /api/tickets/verify +Content-Type: application/json +Authorization: Bearer {jwt_token} + +{ + "qr": "TICKET_UUID_OR_CODE", + "eventId": "event_uuid", + "deviceId": "device_fingerprint", + "zone": "Gate A" +} + +// Responses +// Success (200) +{ + "valid": true, + "ticket": { + "eventTitle": "Sample Event", + "ticketTypeName": "General Admission", + "customerEmail": "customer@example.com", + "seatNumber": "A-15" // if assigned seating + } +} + +// Already Scanned (200) +{ + "valid": false, + "reason": "already_scanned", + "scannedAt": "2024-01-01T18:30:00Z", + "scannedBy": "device_abc123", + "zone": "Main Entrance" +} + +// Invalid (200) +{ + "valid": false, + "reason": "invalid", // or "expired", "cancelled", "locked" + "message": "Ticket not found or has been cancelled" +} + +// Rate Limited (429) +{ + "error": "rate_limit_exceeded", + "retryAfter": 5, + "message": "Too many requests from device" +} +``` + +#### 2. Scan Logging Endpoint +```typescript +POST /api/scans/log +Content-Type: application/json +Authorization: Bearer {jwt_token} + +{ + "deviceId": "device_fingerprint", + "eventId": "event_uuid", + "qr": "TICKET_CODE", + "result": "valid", // valid, invalid, already_scanned + "zone": "Gate A", + "timestamp": "2024-01-01T18:30:00Z", + "latency": 245, // ms + "offline": false +} + +// Response (202 Accepted) +{ + "logged": true, + "scanId": "scan_uuid" +} +``` + +#### 3. Offline Sync Endpoint +```typescript +POST /api/scanner/sync +Content-Type: application/json +Authorization: Bearer {jwt_token} + +{ + "deviceId": "device_fingerprint", + "scans": [ + { + "qr": "TICKET_CODE_1", + "eventId": "event_uuid", + "result": "valid", + "timestamp": "2024-01-01T18:30:00Z", + "zone": "Gate A" + } + // ... more scans + ] +} + +// Response (200) +{ + "synced": 15, + "conflicts": 2, + "failed": 0, + "conflictDetails": [ + { + "qr": "TICKET_CODE_X", + "offlineResult": "valid", + "serverResult": "already_scanned", + "conflictId": "conflict_uuid" + } + ] +} +``` + +### Server-Side Rate Limiting + +#### Redis-Based Rate Limiting +```javascript +// Rate limiting implementation +const rateLimit = async (deviceId, windowMs = 1000, maxRequests = 8) => { + const key = `rate_limit:${deviceId}`; + const current = await redis.incr(key); + + if (current === 1) { + await redis.expire(key, Math.ceil(windowMs / 1000)); + } + + if (current > maxRequests) { + throw new RateLimitError('Rate limit exceeded', { + retryAfter: await redis.ttl(key) + }); + } + + return { remaining: maxRequests - current, resetTime: Date.now() + windowMs }; +}; +``` + +#### Device Abuse Tracking +```javascript +const trackDeviceAbuse = async (deviceId, violation) => { + const key = `abuse:${deviceId}`; + const violations = await redis.get(key) || '[]'; + const parsed = JSON.parse(violations); + + parsed.push({ + type: violation.type, // 'rate_limit', 'invalid_qr_spam' + timestamp: Date.now(), + details: violation.details + }); + + // Keep only last 24 hours of violations + const oneDayAgo = Date.now() - 86400000; + const recent = parsed.filter(v => v.timestamp > oneDayAgo); + + await redis.setex(key, 86400, JSON.stringify(recent)); + + // Calculate escalating penalty + const penalty = calculatePenalty(recent); + if (penalty > 0) { + await redis.setex(`penalty:${deviceId}`, penalty, '1'); + } +}; +``` + +## Monitoring and Alerting + +### Sentry Configuration + +#### Error Monitoring Setup +```javascript +// sentry.client.ts +import * as Sentry from '@sentry/react'; + +Sentry.init({ + dsn: process.env.VITE_SENTRY_DSN, + environment: process.env.NODE_ENV, + integrations: [ + new Sentry.BrowserTracing({ + tracingOrigins: [/^https:\/\/.*\.blackcanyontickets\.com\/api/], + }), + ], + tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0, + beforeSend(event) { + // Filter out rate limiting errors as they're expected + if (event.exception?.values?.[0]?.type === 'RateLimitError') { + return null; + } + return event; + } +}); +``` + +#### Performance Monitoring +```javascript +// Performance tracking in scanner +const trackScanPerformance = (scanResult) => { + Sentry.addBreadcrumb({ + category: 'scanner', + message: `Scan ${scanResult.result}`, + level: 'info', + data: { + latency: scanResult.latency, + offline: scanResult.offline, + zone: scanResult.zone, + deviceMemory: performance.memory?.usedJSHeapSize || 0 + } + }); + + // Track performance metrics + Sentry.setTag('scanning_session', true); + Sentry.setContext('device_info', { + memory: performance.memory?.usedJSHeapSize, + connection: navigator.connection?.effectiveType, + battery: navigator.battery?.level + }); +}; +``` + +### Alert Configuration + +#### Critical Alerts (Immediate Response) +```yaml +# Sentry Alert Rules +- name: "Scanner API Errors" + conditions: + - error_count > 10 in 5 minutes + actions: + - slack: "#incidents" + - email: "oncall@blackcanyontickets.com" + +- name: "High Rate Limiting" + conditions: + - event.type = "RateLimitError" + - count > 50 in 10 minutes + actions: + - slack: "#scanner-ops" + +- name: "Sync Failures" + conditions: + - event.message contains "sync_failed" + - count > 25 in 15 minutes + actions: + - slack: "#scanner-ops" + - pagerduty: "P1" +``` + +#### Performance Thresholds +```javascript +// Client-side performance monitoring +const performanceMonitor = { + scanLatency: { + warning: 1000, // ms + critical: 3000 + }, + memoryUsage: { + warning: 50 * 1024 * 1024, // 50MB + critical: 100 * 1024 * 1024 // 100MB + }, + syncQueueSize: { + warning: 50, + critical: 100 + }, + offlineTime: { + warning: 300000, // 5 minutes + critical: 900000 // 15 minutes + } +}; +``` + +### Dashboard URLs and Metrics + +#### Grafana Dashboards +- **Scanner Operations**: `https://grafana.bct.com/d/scanner-ops` + - Real-time scan rates by device/zone + - Network latency and error rates + - Offline queue sizes and sync status + +- **Performance Metrics**: `https://grafana.bct.com/d/scanner-perf` + - Memory usage trends + - Battery life estimates + - Camera initialization times + +- **Business Metrics**: `https://grafana.bct.com/d/scanner-business` + - Entry throughput by gate + - Peak scanning times + - Duplicate/invalid ticket rates + +#### Real-Time Monitoring +```javascript +// Health check endpoint +GET /api/scanner/health +{ + "status": "healthy", + "checks": { + "database": "ok", + "redis": "ok", + "camera_api": "ok" + }, + "metrics": { + "active_devices": 15, + "scans_per_minute": 245, + "pending_syncs": 12, + "conflict_rate": 0.02 + } +} +``` + +## Network Requirements and Quality + +### WiFi Configuration + +#### Recommended WiFi Setup +```yaml +Network Requirements: + - SSID: "BCT-Staff" (dedicated for scanners) + - Security: WPA3-Enterprise (or WPA2-Personal minimum) + - Bandwidth: 10 Mbps minimum, 50 Mbps recommended + - Latency: <100ms to API servers + - Coverage: -65 dBm minimum signal at all gate locations + +Quality of Service (QoS): + - Scanner traffic priority: High + - API requests: TCP/443 (HTTPS) + - Sync operations: TCP/443 (HTTPS) + - Background sync: TCP/443 (HTTPS) +``` + +#### Network Monitoring +```bash +# WiFi quality testing script +#!/bin/bash +WIFI_SSID="BCT-Staff" +API_ENDPOINT="https://api.blackcanyontickets.com/health" + +echo "Testing WiFi Quality for Scanner Operations" +echo "===========================================" + +# Signal strength test +SIGNAL=$(iwconfig wlan0 | grep 'Signal level' | awk '{print $4}' | cut -d= -f2) +echo "Signal Strength: $SIGNAL dBm" +if [ ${SIGNAL:1} -gt 65 ]; then + echo "⚠️ Warning: Signal strength may affect scanning" +fi + +# Latency test +PING=$(ping -c 5 api.blackcanyontickets.com | tail -1 | awk '{print $4}' | cut -d/ -f2) +echo "Average Latency: ${PING}ms" +if (( $(echo "$PING > 200" | bc -l) )); then + echo "⚠️ Warning: High latency may slow scanning" +fi + +# Throughput test +echo "Testing API response time..." +API_TIME=$(curl -o /dev/null -s -w "%{time_total}" $API_ENDPOINT) +echo "API Response Time: ${API_TIME}s" +if (( $(echo "$API_TIME > 2.0" | bc -l) )); then + echo "❌ Critical: API too slow for real-time scanning" +fi +``` + +### Cellular Fallback Configuration + +#### Carrier Requirements +```yaml +Cellular Backup: + - Carriers: Verizon, AT&T, T-Mobile (multi-carrier preferred) + - Data Plans: Unlimited or 10GB+ per device per event + - Coverage: -85 dBm minimum LTE signal + - Speeds: 5 Mbps down, 1 Mbps up minimum + +Network Priority: + 1. WiFi (primary) + 2. 5G/LTE (automatic fallback) + 3. Offline mode (complete network failure) +``` + +#### Network Handoff Testing +```javascript +// Network quality detection +const detectNetworkQuality = () => { + const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection; + + return { + type: connection?.effectiveType || 'unknown', // '4g', '3g', 'slow-2g' + downlink: connection?.downlink || 0, // Mbps + rtt: connection?.rtt || 0, // ms round trip time + saveData: connection?.saveData || false + }; +}; + +// Adaptive behavior based on connection +const adaptToNetworkQuality = (quality) => { + if (quality.effectiveType === 'slow-2g') { + // Reduce sync frequency, smaller batches + return { syncInterval: 30000, batchSize: 5 }; + } else if (quality.effectiveType === '3g') { + return { syncInterval: 10000, batchSize: 10 }; + } else { + // 4G or better - full speed + return { syncInterval: 5000, batchSize: 25 }; + } +}; +``` + +## Performance Baselines and SLAs + +### Expected Performance Metrics + +#### Scanning Operations +```yaml +Scan Processing: + - QR Detection Time: <500ms (camera to recognition) + - API Verification Time: <1000ms (network request) + - UI Response Time: <100ms (result display) + - Total Scan Time: <3 seconds (end-to-end) + +Throughput: + - Peak Rate: 8 scans/second (rate limit) + - Sustained Rate: 4-6 scans/second per device + - Concurrent Devices: 20+ devices per event + - Entry Processing: <10 seconds per attendee (including interaction) +``` + +#### Device Performance +```yaml +Memory Usage: + - Initial Load: <15MB heap size + - After 100 scans: <25MB heap size + - After 1000 scans: <40MB heap size + - Memory Growth Rate: <20MB per hour + +Battery Life: + - Continuous Scanning: 4+ hours minimum + - Standby with App Open: 8+ hours + - Background Sync Impact: <10% additional drain + - Flashlight Usage: -25% battery life + +CPU Performance: + - Camera Processing: <30% CPU usage + - QR Detection: <50% CPU burst (brief) + - Background Sync: <10% CPU usage + - Thermal Throttling: Graceful degradation +``` + +#### Network Performance +```yaml +Sync Operations: + - Single Scan Sync: <500ms + - Batch Sync (25 scans): <2 seconds + - Full Queue Sync (100 scans): <10 seconds + - Conflict Resolution: <1 second per conflict + +Offline Capabilities: + - Queue Capacity: 1000+ scans per device + - Storage Persistence: Survives app/browser restart + - Sync Success Rate: >99% when network restored + - Data Integrity: Zero scan loss during offline operation +``` + +### Service Level Agreements (SLAs) + +#### Availability Targets +```yaml +System Availability: 99.9% during event hours +- API Uptime: 99.95% +- Database Uptime: 99.99% +- CDN Availability: 99.9% +- SSL Certificate: 99.99% + +Response Time Targets: +- Scanner API: <1 second (95th percentile) +- Health Checks: <200ms (99th percentile) +- Sync Operations: <5 seconds (99th percentile) + +Error Rate Targets: +- False Positives: <0.5% (valid tickets rejected) +- False Negatives: <0.1% (invalid tickets accepted) +- Sync Failures: <1% of total sync operations +- Conflict Rate: <2% of offline scans +``` + +#### Performance Degradation Response +```yaml +Performance Tiers: + Tier 1 (Green - Normal): + - Scan latency: <1 second + - Memory usage: <40MB + - Battery life: >4 hours + - Action: Monitor only + + Tier 2 (Yellow - Degraded): + - Scan latency: 1-3 seconds + - Memory usage: 40-70MB + - Battery life: 2-4 hours + - Action: Alert on-call, prepare mitigation + + Tier 3 (Red - Critical): + - Scan latency: >3 seconds + - Memory usage: >70MB + - Battery life: <2 hours + - Action: Immediate response, activate backup procedures +``` + +## Escalation Procedures and Contacts + +### Technical Escalation Matrix + +#### Severity Levels +```yaml +P1 - Business Critical (Response: 5 minutes): + - Complete scanner system failure + - Database corruption affecting scan verification + - Security breach or data leak + - >50% of devices unable to scan + +P2 - High Impact (Response: 15 minutes): + - Single API endpoint failure + - Performance degradation affecting >25% devices + - Network sync failures >10 minutes + - Rate limiting preventing legitimate scans + +P3 - Medium Impact (Response: 1 hour): + - Individual device issues (hardware/software) + - Non-critical API errors + - Monitoring/alerting issues + - Minor UI/UX problems + +P4 - Low Impact (Response: 4 hours): + - Enhancement requests + - Documentation updates + - Non-urgent performance optimization + - Cosmetic UI issues +``` + +#### Contact Directory + +**Primary On-Call (24/7 During Events)** +```yaml +Platform Engineering Lead: + - Name: [REDACTED] + - Phone: [REDACTED] + - Email: oncall-platform@blackcanyontickets.com + - Slack: @platform-oncall + - Responsibilities: API issues, database problems, sync failures + +DevOps Engineer: + - Name: [REDACTED] + - Phone: [REDACTED] + - Email: oncall-devops@blackcanyontickets.com + - Slack: @devops-oncall + - Responsibilities: Infrastructure, networking, deployment issues + +Frontend Engineering Lead: + - Name: [REDACTED] + - Phone: [REDACTED] + - Email: oncall-frontend@blackcanyontickets.com + - Slack: @frontend-oncall + - Responsibilities: PWA issues, camera problems, UI/UX bugs +``` + +**Secondary/Escalation Contacts** +```yaml +Engineering Manager: + - Phone: [REDACTED] + - When: P1 incidents >30 minutes, team coordination needed + +CTO: + - Phone: [REDACTED] + - When: P1 incidents >60 minutes, business decisions needed + +CEO: + - Phone: [REDACTED] + - When: Business-critical failures, external communication needed +``` + +**Vendor/External Support** +```yaml +Supabase Support: + - Contact: support@supabase.com + - SLA: 4 hours (Pro Plan) + - Phone: Emergency hotline available + +Sentry Support: + - Contact: support@sentry.io + - SLA: 8 hours (Business Plan) + - Documentation: docs.sentry.io + +Vercel Support: + - Contact: support@vercel.com + - SLA: 24 hours (Pro Plan) + - Status Page: vercel-status.com +``` + +### Escalation Procedures + +#### P1 Incident Response +```yaml +Step 1 (0-5 minutes): + - Acknowledge incident in #incidents Slack channel + - Start incident bridge call/video chat + - Assign incident commander (usually platform lead) + - Begin status page updates + +Step 2 (5-15 minutes): + - Assess scope and impact + - Implement immediate mitigation (fallback procedures) + - Escalate to Engineering Manager if needed + - Communicate with venue/operations team + +Step 3 (15-30 minutes): + - Deploy fixes or activate backup systems + - Monitor recovery and impact reduction + - Update stakeholders every 10 minutes + - Document timeline and actions taken + +Step 4 (Post-resolution): + - Conduct immediate hot wash (15 minutes) + - Schedule full post-mortem within 48 hours + - Update runbooks based on lessons learned + - Communicate resolution to all stakeholders +``` + +#### Common Escalation Scenarios + +**Complete Scanner Failure** +```yaml +Symptoms: All devices unable to scan, API returning errors +Immediate Actions: + 1. Check system status dashboard + 2. Verify database connectivity + 3. Activate manual entry procedures at gates + 4. Estimate impact and communicate timeline + +Escalation Triggers: + - Issue not resolved in 15 minutes → Engineering Manager + - Manual entry activated → Operations Manager + - Expected duration >1 hour → CTO +``` + +**Mass Device Issues** +```yaml +Symptoms: >10 devices experiencing problems simultaneously +Immediate Actions: + 1. Check for CDN/deployment issues + 2. Verify service worker updates aren't causing problems + 3. Roll back recent deployments if necessary + 4. Distribute backup devices + +Escalation Triggers: + - >50% devices affected → Immediate escalation to Engineering Manager + - Hardware-related issues → Venue operations team + - Software issues persisting >20 minutes → CTO notification +``` + +**Database/API Performance Issues** +```yaml +Symptoms: Slow scan response times, sync delays, timeouts +Immediate Actions: + 1. Check database performance metrics + 2. Review API response times and error rates + 3. Scale database resources if possible + 4. Enable aggressive client-side caching + +Escalation Triggers: + - Database CPU >90% for >5 minutes → DevOps immediate response + - API latency >5 seconds → Platform Engineering lead + - Unable to scale resources → CTO (budget approval needed) +``` + +## Security Considerations + +### Data Protection and Privacy + +#### Local Data Storage +```yaml +IndexedDB Contents: + - Scan Queue: QR codes, timestamps, results (temporary) + - Device Settings: Zone, preferences (non-sensitive) + - Conflict Log: Sync discrepancies (temporary) + - No Storage: Customer PII, payment info, passwords + +Data Retention: + - Scan Queue: Auto-purged after successful sync + - Settings: Persisted until manual reset + - Conflicts: Retained 24 hours for review + - Error Logs: Purged every 7 days +``` + +#### Network Security +```yaml +API Communication: + - Protocol: HTTPS only (TLS 1.3 preferred) + - Authentication: JWT tokens with 2-hour expiration + - Rate Limiting: 8 requests/second per device + - Input Validation: All QR codes validated server-side + +Content Security Policy: + - script-src: 'self' cdn.sentry.io + - connect-src: 'self' *.supabase.co *.sentry.io + - img-src: 'self' data: https: + - camera: Required for QR scanning +``` + +#### Device Security +```yaml +Client-Side Protection: + - No API keys stored in client code + - Device fingerprinting (non-PII) for abuse tracking + - Local encryption of sensitive scan data + - Secure session management + +Physical Security: + - Device lock screen during breaks + - Remote wipe capabilities if stolen + - Tamper detection for unusual usage patterns + - Secure storage when not in use +``` + +### Vulnerability Management + +#### Regular Security Assessments +```yaml +Automated Scanning: + - Daily: npm audit for dependency vulnerabilities + - Weekly: OWASP ZAP scan of staging environment + - Monthly: Full penetration test of production + +Manual Review: + - Code Review: Required for all scanner-related changes + - Security Review: Required for API changes + - Access Review: Quarterly review of admin permissions +``` + +#### Incident Response Plan +```yaml +Security Incident Types: + 1. Data Breach (customer PII exposed) + 2. Unauthorized Access (admin account compromise) + 3. Service Disruption (DDoS, malicious traffic) + 4. Device Compromise (stolen/hacked scanner device) + +Response Timeline: + - Detection to Acknowledgment: <15 minutes + - Initial Assessment: <30 minutes + - Containment Actions: <1 hour + - Customer Notification: <24 hours (if PII involved) +``` + +## Maintenance and Updates + +### Regular Maintenance Tasks + +#### Daily Operations +```bash +# Daily health check script +#!/bin/bash +echo "BCT Scanner Daily Health Check - $(date)" + +# Check API health +curl -f https://api.blackcanyontickets.com/health || echo "❌ API health check failed" + +# Check database connections +psql $DATABASE_URL -c "SELECT 1" || echo "❌ Database connection failed" + +# Check error rates in Sentry +# (This would integrate with Sentry API to get error counts) + +# Check device online status +# (Query database for devices that haven't synced in >24 hours) +``` + +#### Weekly Maintenance +```yaml +System Updates: + - Review and apply npm dependency updates + - Update browser compatibility testing + - Review performance metrics and trends + - Clean up old scan logs and conflict data + +Monitoring Review: + - Review Sentry error trends + - Analyze performance degradation patterns + - Update alert thresholds based on data + - Test escalation procedures +``` + +#### Monthly Maintenance +```yaml +Security Updates: + - Apply security patches to all dependencies + - Review and rotate API keys/secrets + - Update SSL certificates if needed + - Review access logs for unusual patterns + +Performance Optimization: + - Analyze database query performance + - Review and optimize API endpoints + - Update caching strategies + - Test load balancing configuration +``` + +### Deployment and Rollback Procedures + +#### Production Deployment +```yaml +Deployment Process: + 1. Code Review: Minimum 2 approvals required + 2. Staging Testing: Full test suite + manual QA + 3. Blue-Green Deployment: Zero downtime deployment + 4. Gradual Rollout: 10% → 50% → 100% traffic + 5. Monitoring: 24-hour observation period + +Rollback Triggers: + - Error rate >5% increase from baseline + - Response time >2x normal latency + - Critical functionality broken (scanning failure) + - Security vulnerability discovered + +Rollback Process: + 1. Immediate: Switch traffic to previous version (2 minutes) + 2. Communication: Alert all stakeholders (5 minutes) + 3. Investigation: Root cause analysis (30 minutes) + 4. Fix Forward: Rapid bug fix deployment if possible +``` + +#### Emergency Hotfixes +```yaml +Hotfix Criteria: + - Security vulnerability (any severity) + - Data corruption or loss + - Complete service outage + - Critical business function broken + +Hotfix Process: + 1. Create hotfix branch from production + 2. Make minimal fix with tests + 3. Emergency code review (single approver) + 4. Direct to production deployment + 5. Post-deployment verification + 6. Full retrospective within 24 hours +``` + +--- + +## Appendices + +### A. Browser Compatibility Matrix +```yaml +Recommended Browsers: + - Chrome 88+: ✅ Full support, best performance + - Safari 14+: ✅ iOS support, some PWA limitations + - Firefox 85+: ✅ Good fallback, slower QR detection + - Edge 88+: ✅ Windows support, Chromium-based + +Required APIs: + - getUserMedia (Camera): All supported browsers + - IndexedDB: All supported browsers + - Service Workers: All supported browsers + - BarcodeDetector: Chrome only, ZXing fallback for others +``` + +### B. Database Schema Reference +```sql +-- Complete scanner database schema +-- See SCANNER_DATABASE_SCHEMA.sql for full implementation +``` + +### C. Monitoring Queries +```sql +-- Active scanning sessions +SELECT + COUNT(DISTINCT device_id) as active_devices, + COUNT(*) as total_scans, + AVG(EXTRACT(EPOCH FROM (NOW() - scan_timestamp))) as avg_age_seconds +FROM scanner_logs +WHERE scan_timestamp > NOW() - INTERVAL '1 hour'; + +-- Conflict analysis +SELECT + offline_result, + server_result, + COUNT(*) as conflicts +FROM scan_conflicts +WHERE conflict_timestamp > NOW() - INTERVAL '24 hours' +GROUP BY offline_result, server_result; +``` + +### D. Performance Benchmarking Scripts +```bash +# Device performance test script +# See SCANNER_PERFORMANCE_TEST.sh for full implementation +``` + +This technical runbook provides comprehensive guidance for IT administrators and technical staff to successfully deploy, monitor, and maintain the Scanner PWA system. Regular updates to this document should reflect operational lessons learned and system evolution. \ No newline at end of file diff --git a/reactrebuild0825/STAFF_TRAINING_MATERIALS.md b/reactrebuild0825/STAFF_TRAINING_MATERIALS.md new file mode 100644 index 0000000..df01ec5 --- /dev/null +++ b/reactrebuild0825/STAFF_TRAINING_MATERIALS.md @@ -0,0 +1,302 @@ +# Scanner PWA Staff Training Materials + +## 📱 Quick Setup Guide for Gate Staff + +### Before Your Shift - Device Setup (15 minutes) + +#### Step 1: Install the Scanner App +**For iPhone/iPad:** +1. Open **Safari** browser (not Chrome!) +2. Go to: `scanner.blackcanyontickets.com/scan` +3. Tap the **Share** button (box with arrow up) +4. Select **"Add to Home Screen"** +5. Name it "Gate Scanner" → Tap **Add** + +**For Android Phone:** +1. Open **Chrome** browser +2. Go to: `scanner.blackcanyontickets.com/scan` +3. Look for **"Add to Home Screen"** popup +4. If no popup: Tap 3 dots → "Add to Home Screen" +5. Name it "Gate Scanner" → Tap **Add** + +#### Step 2: Set Up Camera Permission +1. **Tap the "Gate Scanner"** app on your home screen +2. When asked for camera access → **Tap "Allow"** +3. You should see the camera view with a scanning frame + +**If camera doesn't work:** +- iPhone: Settings → Privacy → Camera → Gate Scanner → ON +- Android: Settings → Apps → Gate Scanner → Permissions → Camera → Allow + +#### Step 3: Configure Your Gate +1. In the scanner app, **tap the gear ⚙️ icon** +2. Enter your gate name: "Main Gate", "VIP Entrance", etc. +3. Leave other settings as default → **Tap Save** + +### During Your Shift - Basic Operation + +#### How to Scan Tickets +1. **Hold your device 6-12 inches from the QR code** +2. **Center the code in the scanning frame** +3. **Hold steady** - don't move until you hear a beep +4. **Look at the result banner** at the top + +#### Understanding Scan Results + +**✅ GREEN = SUCCESS - Let them in!** +- Shows: Event name, ticket type, customer email +- Action: Allow entry immediately + +**⚠️ YELLOW = ALREADY SCANNED - Check carefully!** +- Shows: When and where it was first scanned +- Action: Ask "Have you been in and out?" If no → **Call supervisor** + +**❌ RED = INVALID - Do not allow entry** +- Shows: Error reason (fake, expired, cancelled) +- Action: Direct to box office, be polite but firm + +**🔵 BLUE = OFFLINE ACCEPTED - Let them in** +- Shows: "Will verify when connection restored" +- Action: Allow entry (normal during network issues) + +**🔒 RED WITH LOCK = LOCKED TICKET - Do not allow entry** +- Shows: "Payment dispute" or "Refund processed" +- Action: Direct to support, provide contact info + +#### Using the Flashlight +- **Automatic:** Flashlight turns on in dark conditions +- **Manual:** Tap the flashlight 🔦 icon to toggle on/off +- **Best for:** Dark venues, evening events, hard-to-read codes + +### Common Situations and Solutions + +#### "The scanner isn't working!" +**Problem:** Black screen, no camera view +**Fix:** +1. Close the app completely (swipe up, swipe away) +2. Reopen "Gate Scanner" app +3. If still broken → Use backup device or call for help + +#### "It says 'scanning too fast'" +**Problem:** Orange/red warning about speed limit +**Fix:** +1. **Slow down!** Wait for beep before next scan +2. If blocked, wait for countdown timer to finish +3. Resume at normal speed (about 1 scan every 2-3 seconds) + +#### "Scans aren't saving/syncing" +**Problem:** High "pending sync" number in settings +**Fix:** +1. Check WiFi connection - switch to cellular if needed +2. Keep scanning (they'll sync when connection returns) +3. If pending count > 50 → Alert IT support + +#### "Customer says ticket should work" +**Problem:** Valid-looking ticket scanning as invalid/already used +**Response:** +1. **Don't argue** - be polite and professional +2. Say: "I'm showing an issue with this ticket" +3. Direct them to: "Please visit the box office for assistance" +4. **Never override** the scanner result + +### Emergency Procedures + +#### Complete Scanner Failure +**If ALL scanners stop working:** +1. **Switch to paper list immediately** +2. Check names against ID +3. Mark attendees manually +4. **Call IT support** right away + +#### Network Outage +**If internet/WiFi goes down:** +1. **Keep scanning** - app works offline +2. Look for blue "offline accepted" results +3. Check settings → pending sync count occasionally +4. **Don't panic** - everything will sync later + +#### Device Problems +**If your device breaks/overheats/gets stolen:** +1. **Get backup device** from supervisor +2. Report incident immediately +3. Continue with backup while replacement is configured + +### Smartphone Tips for All-Day Scanning + +#### Battery Management +- **Before shift:** Charge to 100% +- **During shift:** Use power bank if available +- **Screen settings:** Set brightness to 75% (not 100%) +- **Close other apps** to save battery + +#### Comfort and Safety +- **Hold device properly:** Support with both hands when possible +- **Take breaks:** Look away from screen every 20-30 minutes +- **Stay hydrated:** Scanning in sun/heat is exhausting +- **Rotate positions:** Switch scanning hand to avoid strain + +#### Professional Appearance +- **Keep device clean:** Wipe screen regularly for best scanning +- **Professional demeanor:** Device is a work tool, not personal phone +- **Focus on customers:** Make eye contact, smile, be welcoming +- **Efficient processing:** Quick scan → friendly greeting → direct to entrance + +## 🎯 Troubleshooting Quick Reference + +### Problem → Solution Flowchart + +**Camera not working** → Close app → Reopen → Check permissions → Use backup device + +**Too fast warning** → Slow down → Wait for countdown → Resume normal pace + +**Network issues** → Continue offline → Monitor pending sync → Report if >50 pending + +**Invalid ticket** → Be polite → Explain issue → Direct to box office → Never override + +**Already scanned** → Ask if re-entry → Check time/location → Call supervisor if suspicious + +**Device failure** → Report immediately → Get backup device → Continue operations + +### Contact Information (Post at Each Gate) + +**Technical Issues:** +- IT Support: [PHONE] +- Network Problems: [EMAIL] + +**Operational Issues:** +- Gate Supervisor: [PHONE] +- Event Manager: [PHONE] +- Security: [RADIO CHANNEL] + +**Emergency Contacts:** +- Venue Management: [PHONE] +- Medical Emergency: 911 +- Fire/Police Emergency: 911 + +### Scanner Settings Reference + +**Access Settings:** Tap gear icon ⚙️ in app header + +**Important Settings:** +- **Zone/Gate:** Your gate name (required) +- **Optimistic Accept:** ON (allows offline scanning) +- **Audio Feedback:** ON (success beep) +- **Haptic Feedback:** ON (vibration) + +**Information Displays:** +- **Total Scans:** Count from your device +- **Pending Sync:** Waiting for internet (should be low) +- **Last Sync:** Most recent successful sync time + +## 📋 Pre-Shift Checklist (Print and Laminate) + +### Device Check ✅ +- [ ] Scanner app installed and opens correctly +- [ ] Camera permission granted and working +- [ ] Flashlight toggles on/off properly +- [ ] Device charged to 80%+ battery +- [ ] Gate/zone name configured in settings + +### Network Check ✅ +- [ ] WiFi connected and internet working +- [ ] Cellular signal available as backup +- [ ] Test scan synchronizes (pending sync = 0) + +### Knowledge Check ✅ +- [ ] Know all scan result colors and meanings +- [ ] Understand "already scanned" policy +- [ ] Can locate backup device and contact numbers +- [ ] Practice manual entry for broken QR codes +- [ ] Rehearsed "invalid ticket" customer response + +### Supplies Check ✅ +- [ ] Power bank/charging cable available +- [ ] Backup device identified and tested +- [ ] Emergency contact sheet posted +- [ ] Guest list printout as fallback +- [ ] Hand sanitizer (if required) + +## 💡 Pro Tips for Efficient Scanning + +### Optimal Scanning Technique +1. **Position:** 6-12 inches from QR code +2. **Angle:** Device parallel to ticket (not tilted) +3. **Lighting:** Use flashlight in dim conditions +4. **Stability:** Hold steady until beep sounds +5. **Speed:** Average 1 scan every 2-3 seconds + +### Managing Peak Entry Times +- **Stay calm** during rush periods +- **Communicate** - tell people "One moment please" +- **Be efficient** but don't sacrifice accuracy +- **Watch for rate limiting** warnings +- **Ask for help** if line gets too long + +### Customer Service Excellence +- **Smile and make eye contact** while device processes +- **Explain briefly** if there's a delay: "Just verifying your ticket" +- **Be patient** with elderly or tech-confused customers +- **Stay positive** even when dealing with invalid tickets +- **Thank people** for their patience during busy times + +### Maintaining Equipment +- **Keep screen clean** - use microfiber cloth +- **Protect from rain** - use bag/cover if needed +- **Avoid extreme temperatures** - shade device when possible +- **Handle carefully** - scanning devices are expensive +- **Report damage immediately** - don't try to fix yourself + +## 🚨 Staff Safety and Security + +### Personal Safety +- **Stay alert** to surroundings while scanning +- **Know emergency exits** and evacuation procedures +- **Keep radio/communication device** accessible +- **Report suspicious behavior** to security +- **Never confront** aggressive customers alone + +### Device Security +- **Keep device secure** when not scanning +- **Don't leave unattended** even briefly +- **Report theft/loss immediately** +- **Don't share login credentials** with other staff +- **Lock screen** during breaks if device supports it + +### Data Privacy +- **Customer data** stays on device only +- **Don't photograph** or share scan results +- **Don't discuss** customer information with others +- **Follow venue privacy policies** for all customer interactions + +## 📞 Quick Contact Card (Wallet Size) + +**🔧 Technical Support** +IT Help: [PHONE] +Platform Issues: [EMAIL] + +**👥 Operations** +Gate Supervisor: [PHONE] +Event Manager: [PHONE] +Security Radio: Channel [#] + +**🚨 Emergencies** +Medical: 911 +Fire/Police: 911 +Venue Management: [PHONE] + +**📱 Scanner Issues** +• Camera black screen: Close/reopen app +• Too fast warning: Slow down, wait +• Network issues: Continue offline +• Invalid ticket: Direct to box office + +**⚠️ Remember** +✅ Green = Enter +⚠️ Yellow = Check carefully +❌ Red = No entry +🔵 Blue = Enter (offline) +🔒 Red lock = No entry (contact support) + +--- + +*Keep this card with you during your shift. When in doubt, ask your supervisor or call technical support. Your job is to keep entry moving safely and efficiently!* \ No newline at end of file diff --git a/reactrebuild0825/STAGING_ROLLOUT_CHECKLIST.md b/reactrebuild0825/STAGING_ROLLOUT_CHECKLIST.md new file mode 100644 index 0000000..51e764e --- /dev/null +++ b/reactrebuild0825/STAGING_ROLLOUT_CHECKLIST.md @@ -0,0 +1,431 @@ +# Scanner PWA Staging Rollout Checklist + +## Executive Summary + +This checklist ensures successful deployment of the Scanner PWA for gate operations. The system is designed for offline-first operation with comprehensive abuse prevention and mobile optimization for staff devices. + +**Critical Success Factors:** +- ✅ Staff devices properly configured with PWA installation +- ✅ Camera permissions granted and torch functionality verified +- ✅ Offline queue testing completed before event start +- ✅ Rate limiting and abuse prevention systems tested +- ✅ Emergency fallback procedures documented and rehearsed + +## Pre-Event Setup (IT/Admin Team) +*Time Estimate: 2-3 hours | Role: 🎯 IT Administrator* + +### Environment Configuration +- [ ] **Staging Environment Setup** + - [ ] Deploy scanner PWA to staging URL + - [ ] Configure Sentry monitoring with staging environment + - [ ] Set up Firebase/Supabase staging database + - [ ] Test API endpoints for ticket verification + - [ ] Verify SSL certificates and HTTPS enforcement + - ⏱️ *30 minutes* + +- [ ] **Network Infrastructure** + - [ ] Configure venue WiFi with dedicated SSID for staff devices + - [ ] Test cellular coverage at all gate locations + - [ ] Set up network monitoring for quality alerts + - [ ] Verify firewall rules allow scanner API traffic + - [ ] Test network handoff between WiFi and cellular + - ⏱️ *45 minutes* + +### Monitoring Setup +- [ ] **Sentry Configuration** + - [ ] Enable real-time error tracking + - [ ] Set up performance monitoring thresholds + - [ ] Configure alerts for critical errors + - [ ] Test alert notification channels (Slack, email) + - ⏱️ *15 minutes* + +- [ ] **Performance Baselines** + - [ ] Document expected scan rates (8 scans/second max) + - [ ] Set latency targets (<1000ms per scan) + - [ ] Define memory usage thresholds (<20MB growth) + - [ ] Establish battery life expectations + - ⏱️ *15 minutes* + +### Test Data Preparation +- [ ] **Mock Ticket Generation** + - [ ] Generate sample QR codes for testing + - [ ] Create mix of valid, invalid, and duplicate test tickets + - [ ] Prepare locked/disputed ticket scenarios + - [ ] Document test ticket IDs for staff reference + - ⏱️ *30 minutes* + +### Device Procurement +- [ ] **Hardware Requirements** + - [ ] Verify minimum device specs (iOS 14+, Android 8+, Chrome 88+) + - [ ] Ensure devices have functional cameras and flashlights + - [ ] Test battery life under continuous scanning (4+ hours) + - [ ] Prepare backup devices (20% extra capacity) + - ⏱️ *45 minutes* + +## Staff Device Setup (Gate Team) +*Time Estimate: 45 minutes per device | Role: 🎯 Gate Staff + IT Support* + +### PWA Installation Process + +#### iOS Devices (iPhone/iPad) +- [ ] **Safari Installation** + 1. [ ] Open Safari browser (Chrome not recommended for iOS PWA) + 2. [ ] Navigate to scanner URL: `https://scanner.blackcanyontickets.com/scan?eventId=EVENT_ID` + 3. [ ] Tap Share button (square with arrow up) + 4. [ ] Select "Add to Home Screen" + 5. [ ] Rename app to "BCT Scanner" if desired + 6. [ ] Tap "Add" to complete installation + - ⏱️ *5 minutes per device* + +- [ ] **Camera Permission Setup** + 1. [ ] Launch BCT Scanner app from home screen + 2. [ ] When prompted, tap "Allow" for camera access + 3. [ ] If denied, go to Settings > Privacy & Security > Camera + 4. [ ] Find "BCT Scanner" and toggle ON + 5. [ ] Return to app and verify camera view appears + - ⏱️ *3 minutes per device* + +#### Android Devices +- [ ] **Chrome Installation** + 1. [ ] Open Chrome browser + 2. [ ] Navigate to scanner URL + 3. [ ] Look for "Add to Home screen" banner at bottom + 4. [ ] If no banner, tap Chrome menu (3 dots) > "Add to Home screen" + 5. [ ] Name the app "BCT Scanner" + 6. [ ] Tap "Add" to install + - ⏱️ *5 minutes per device* + +- [ ] **Camera Permission Setup** + 1. [ ] Launch BCT Scanner from home screen + 2. [ ] Tap "Allow" when camera permission requested + 3. [ ] If denied, go to Settings > Apps > BCT Scanner > Permissions + 4. [ ] Enable Camera permission + 5. [ ] Return to app and verify camera functionality + - ⏱️ *3 minutes per device* + +### Device Optimization +- [ ] **Battery Management** + - [ ] Disable automatic screen lock (set to "Never" during event) + - [ ] Enable "Keep screen on while charging" if available + - [ ] Close unnecessary background apps + - [ ] Set screen brightness to 75% (balance visibility/battery) + - ⏱️ *5 minutes per device* + +- [ ] **Torch/Flashlight Setup** + - [ ] Test flashlight functionality in scanner settings + - [ ] Verify automatic torch activation in low light + - [ ] Practice manual torch toggle (tap torch icon) + - [ ] Check flashlight doesn't interfere with scanning + - ⏱️ *3 minutes per device* + +### Zone/Gate Configuration +- [ ] **Scanner Settings** + - [ ] Open scanner settings (gear icon) + - [ ] Set Zone/Gate identifier (e.g., "Main Gate", "VIP Entrance") + - [ ] Enable optimistic scanning for offline operation + - [ ] Test audio/haptic feedback preferences + - [ ] Verify settings persist after app restart + - ⏱️ *5 minutes per device* + +### Functional Testing +- [ ] **Basic Operation Test** + - [ ] Scan valid test QR code → verify SUCCESS (green banner) + - [ ] Scan same code again → verify ALREADY SCANNED (yellow banner) + - [ ] Scan invalid code → verify ERROR (red banner) + - [ ] Test manual entry fallback if QR scan fails + - ⏱️ *8 minutes per device* + +- [ ] **Offline Testing** + - [ ] Enable airplane mode + - [ ] Scan test QR codes → verify OFFLINE ACCEPTED (blue banner) + - [ ] Check pending sync count in settings + - [ ] Re-enable network → verify automatic background sync + - [ ] Confirm all scans appear in sync history + - ⏱️ *10 minutes per device* + +- [ ] **Performance Testing** + - [ ] Rapid scan test → verify rate limiting at 8 scans/second + - [ ] Check "scanning too fast" warning appears appropriately + - [ ] Test cooldown period and recovery + - [ ] Monitor device performance and temperature + - ⏱️ *6 minutes per device* + +## Day-of Operations (Gate Management) +*Role: 🎯 Gate Staff Manager* + +### Pre-Event Checklist (30 minutes before gates open) +- [ ] **Device Readiness** + - [ ] Verify all scanner devices are charged (80%+ battery) + - [ ] Confirm PWA is installed and launches correctly + - [ ] Test camera functionality at each gate location + - [ ] Check network connectivity (WiFi and cellular) + - ⏱️ *10 minutes* + +- [ ] **Staff Briefing** + - [ ] Distribute laminated quick reference cards + - [ ] Demonstrate proper QR code scanning technique + - [ ] Explain scan result colors (green/yellow/red/blue) + - [ ] Review duplicate ticket procedures + - [ ] Practice emergency manual verification process + - ⏱️ *15 minutes* + +- [ ] **System Verification** + - [ ] Run test scans on all devices + - [ ] Verify offline mode works (brief airplane mode test) + - [ ] Check Sentry monitoring is receiving data + - [ ] Confirm backup devices are available and configured + - ⏱️ *5 minutes* + +### Active Scanning Operations + +#### Optimal Scanning Technique +**Staff should hold device 6-12 inches from QR code:** +- [ ] **Lighting:** Use torch in dark conditions, avoid in bright sunlight +- [ ] **Angle:** Hold device parallel to ticket, not at angle +- [ ] **Stability:** Keep device steady for 2-3 seconds until beep +- [ ] **Speed:** Wait for result banner before scanning next ticket + +#### Scan Result Actions + +**✅ SUCCESS (Green Banner)** +- Action: Allow entry immediately +- Display: Shows event name, ticket type, customer email +- Staff Note: Normal entry, no action required + +**⚠️ ALREADY SCANNED (Yellow Banner)** +- Action: **DO NOT** allow entry without verification +- Display: Shows original scan time and location +- Staff Response: + 1. Check if same person attempting re-entry + 2. If different person, possible duplicate/fraud - call supervisor + 3. If same person, check reason for re-entry (bathroom, etc.) + +**❌ INVALID TICKET (Red Banner)** +- Action: **DO NOT** allow entry +- Display: Shows error reason (expired, cancelled, fake) +- Staff Response: + 1. Politely explain ticket issue + 2. Direct customer to box office for assistance + 3. Note incident if appears fraudulent + +**🔵 OFFLINE ACCEPTED (Blue Banner)** +- Action: Allow entry (will be verified when connection restored) +- Display: "Scan queued for verification" +- Staff Note: Normal during network outages, monitor pending sync count + +**🔒 TICKET LOCKED (Red Banner)** +- Action: **DO NOT** allow entry +- Display: Shows lock reason (payment dispute, refund, etc.) +- Staff Response: + 1. Explain ticket has been flagged + 2. Provide support contact: support@blackcanyontickets.com + 3. Direct to box office for resolution + +### Peak Traffic Management +- [ ] **High-Volume Scanning** + - [ ] Monitor scan rate - maintain steady pace below 8/second limit + - [ ] Watch for "slow down" warnings - pause scanning briefly + - [ ] Use multiple lanes/scanners to distribute load + - [ ] Keep backup manual list ready for device failures + - ⏱️ *Ongoing during event* + +### Troubleshooting During Event + +#### Camera Issues +**Problem:** Camera not working, black screen +**Solution:** +1. Close scanner app completely +2. Reopen app and grant camera permission again +3. Try different lighting conditions +4. If persistent, switch to backup device + +#### Network Issues +**Problem:** Scans not syncing, high pending count +**Solution:** +1. Check WiFi connection, switch to cellular if needed +2. Note pending sync count - will sync when connection restored +3. Continue scanning in offline mode (optimistic enabled) +4. Alert IT if pending count exceeds 50 scans + +#### Device Performance Issues +**Problem:** Slow scanning, app freezing, overheating +**Solution:** +1. Close other apps to free memory +2. Move device to cooler location if overheating +3. Restart scanner app (data preserved in IndexedDB) +4. Switch to backup device if problems persist + +#### Rate Limiting Triggered +**Problem:** "Scanning too fast" warning/block +**Solution:** +1. Pause scanning for indicated cooldown period +2. Use manual entry during cooldown if necessary +3. Resume at slower pace - wait for result before next scan +4. Alert supervisor if blocking persists + +## Post-Event Procedures (Data Sync and Cleanup) +*Role: 🎯 IT Administrator + Gate Manager* + +### Immediate Post-Event (Within 30 minutes) +- [ ] **Data Synchronization** + - [ ] Verify all devices show zero pending sync count + - [ ] Force sync on any devices with remaining queue items + - [ ] Export scan logs from each device for reconciliation + - [ ] Check for sync conflicts in scanner settings + - ⏱️ *15 minutes* + +- [ ] **Conflict Resolution** + - [ ] Review conflict log for offline vs online discrepancies + - [ ] Document any manual entry required due to scanner issues + - [ ] Cross-reference duplicate scan warnings with actual entry + - [ ] Generate exception report for unusual scan patterns + - ⏱️ *15 minutes* + +### Data Reconciliation (Within 2 hours) +- [ ] **Attendance Verification** + - [ ] Compare total scans vs ticket sales + - [ ] Identify and investigate any significant discrepancies + - [ ] Validate VIP/special access attendees + - [ ] Generate final attendance report + - ⏱️ *30 minutes* + +- [ ] **Analytics Review** + - [ ] Review Sentry performance metrics + - [ ] Analyze peak scanning times and bottlenecks + - [ ] Document any rate limiting incidents + - [ ] Assess network quality throughout event + - ⏱️ *15 minutes* + +### Device Maintenance +- [ ] **Scanner App Cleanup** + - [ ] Clear scan history on each device (privacy) + - [ ] Reset zone/gate settings to default + - [ ] Log out staff users if authenticated + - [ ] Remove PWA from devices if temporary deployment + - ⏱️ *5 minutes per device* + +- [ ] **Hardware Care** + - [ ] Wipe down devices and sanitize if required + - [ ] Check for physical damage from event use + - [ ] Charge devices to full before storage + - [ ] Store in secure location with other event equipment + - ⏱️ *10 minutes total* + +## Emergency Procedures +*🚨 Critical Fallback Plans* + +### Complete Scanner Failure +**When:** All scanners offline, app crashes, network failure +**Response:** +1. **Switch to Manual Verification** + - Retrieve printed guest list/ticket manifest + - Verify names against government ID + - Manually mark attendees on paper list + - Document all manual entries for later data entry + +2. **Communication Protocol** + - Notify IT support immediately via radio/phone + - Alert event manager of fallback activation + - Post signage explaining temporary manual check-in + - Estimate extended entry times to attendees + +### Network Outage +**When:** Complete internet failure, but scanners functional +**Response:** +1. **Continue Offline Operations** + - Scanners will continue working in offline mode + - Enable optimistic scanning for smooth entry + - Monitor pending sync counts on each device + - Document network outage time for later reconciliation + +2. **Extended Offline Protocol** + - If outage exceeds 2 hours, export scan data to backup storage + - Use cellular hotspot to sync critical scan data + - Implement manual backup logging every 30 minutes + - Prepare for bulk data sync when network restored + +### Device Security Incident +**When:** Device theft, loss, or suspected tampering +**Response:** +1. **Immediate Actions** + - Report incident to security and event management + - Remotely log out device if possible (authentication system) + - Switch to backup device immediately + - Document incident details and time + +2. **Data Protection** + - Scan data is local only (no sensitive personal data stored) + - Device contains only QR scan logs and timestamps + - Remote wipe not necessary (no payment/personal data) + - Generate incident report for insurance/security review + +## Escalation Contacts +*24/7 Support During Event* + +### Technical Issues (Priority Order) +1. **IT Support Lead**: [NAME] - [PHONE] - Scanner app, network, device issues +2. **Platform Engineering**: [EMAIL] - API failures, data sync issues +3. **DevOps On-Call**: [PHONE] - Infrastructure, database, severe outages +4. **CTO Escalation**: [PHONE] - Business-critical failures only + +### Operational Issues +1. **Gate Operations Manager**: [NAME] - [PHONE] - Staff coordination, entry policies +2. **Event Producer**: [NAME] - [PHONE] - Customer disputes, entry decisions +3. **Venue Security**: [NAME] - [PHONE] - Safety, crowd control, incidents +4. **Executive Producer**: [PHONE] - Business decisions, policy overrides + +### Business Critical Escalation +**When to Escalate Immediately:** +- Complete scanner system failure affecting multiple gates +- Security incident involving device theft/tampering +- Data integrity issues (scan counts not matching sales) +- Network outage exceeding 30 minutes during peak entry +- Staff injury or safety incident at scanner-equipped gate + +**Escalation SLA:** +- Technical response: 5 minutes during event hours +- On-site support: 15 minutes for critical issues +- Business decision: 10 minutes for entry policy questions + +## Success Metrics and KPIs + +### Performance Targets +- **Scan Success Rate**: >99% valid tickets processed correctly +- **False Positive Rate**: <1% valid tickets rejected incorrectly +- **Average Scan Time**: <3 seconds from QR present to result +- **Network Sync Success**: >98% of offline scans sync correctly +- **Device Uptime**: >99% operational time during event hours + +### User Experience Metrics +- **Staff Training Time**: <30 minutes per device setup +- **Entry Processing Speed**: <10 seconds average per attendee +- **Error Recovery Time**: <2 minutes to resolve common issues +- **Manual Fallback Incidents**: <5% of total entry volume + +### Technical Metrics +- **Memory Usage**: <20MB growth over 4-hour scanning session +- **Battery Performance**: >4 hours continuous operation per device +- **Rate Limiting Effectiveness**: <10 abuse prevention triggers per event +- **Conflict Resolution**: <1% offline/online scan discrepancies + +--- + +## Quick Reference Summary + +**Before Event:** Test all devices, train staff, verify network ✅ +**During Event:** Monitor sync, handle exceptions, maintain scan pace ⚠️ +**After Event:** Sync data, resolve conflicts, clean devices ✅ +**Emergencies:** Manual fallback, escalation contacts, incident documentation 🚨 + +**Key Numbers to Remember:** +- 8 scans/second maximum rate +- 6-12 inch optimal scanning distance +- 80%+ battery minimum for event start +- 50 pending scans = escalation threshold +- 4+ hours expected battery life per device + +**Critical File Locations:** +- Staff quick reference cards (laminated) +- Emergency contact list (posted at each gate) +- Test QR codes (secure storage) +- Backup device storage location \ No newline at end of file