ocean-cleanup/QR_CODE_CHECKIN_IMPLEMENTATION.md

# QR Code Check-In System Implementation

## Overview

Implemented a QR code-based check-in system for event attendees. Event organizers can scan attendee QR codes from their mobile devices to track attendance at cleanup events.

## Features

### 1. User QR Code Display
- **Location**: User Profile Page (Overview tab)
- **Component**: `UserQRCode` (`src/components/user/UserQRCode.tsx`)
- Each user has a unique QR code containing their Clerk user ID
- QR code is displayed prominently on their profile for easy access
- Users can show this QR code to event organizers for check-in

### 2. QR Code Scanner
- **Component**: `QRCodeScanner` (`src/components/event/QRCodeScanner.tsx`)
- Uses `html5-qrcode` library for camera-based scanning
- Mobile-optimized with back camera support
- Real-time scanning with visual feedback
- Error handling for invalid QR codes

### 3. Event Check-In Page
- **Route**: `/events/:eventId/checkin`
- **Component**: `EventCheckInPage` (`src/pages/EventCheckInPage.tsx`)
- **Access**: Only event organizers can access
- Features:
  - Live QR code scanner
  - List of registered attendees
  - Visual indication of checked-in attendees
  - Real-time updates after successful check-in
  - Success/error notifications

### 4. Backend API
- **Endpoint**: `POST /api/events/:id/checkin`
- **Controller**: `eventController.checkInAttendee`
- **Service**: `eventService.checkInAttendee`
- Validates:
  - User is the event organizer
  - Attendee is registered for the event
  - Attendee hasn't already checked in
- Returns attendee information on successful check-in

## User Flow

### For Attendees:
1. Navigate to their profile page
2. View their personal QR code in the Overview tab
3. Show QR code to event organizer at the event

### For Organizers:
1. Navigate to their event details
2. Click "QR Code Check-In" button
3. Grant camera permissions
4. Click "Start Scanning"
5. Point camera at attendee's QR code
6. System automatically checks in the attendee
7. Visual confirmation and attendee list updates

## Technical Implementation

### Dependencies Added:
```json
{
  "qrcode.react": "^3.x.x",
  "html5-qrcode": "^2.x.x",
  "@types/qrcode.react": "^1.x.x"
}
```

### QR Code Data Format:
```json
{
  "userId": "clerk_user_id",
  "type": "attendee-checkin",
  "timestamp": 1234567890
}
```

### Key Components:

1. **UserQRCode.tsx**
   - Generates QR code using `qrcode.react`
   - High error correction level (H)
   - 200x200px size with margin
   - Displays user's name below QR code

2. **QRCodeScanner.tsx**
   - Uses Html5Qrcode for camera access
   - 250x250px scanning box
   - 10 FPS scanning rate
   - Parses and validates QR code data
   - Callbacks for successful scan and errors

3. **EventCheckInPage.tsx**
   - Fetches event and attendee data
   - Verifies organizer permissions
   - Manages scanner state
   - Handles check-in API calls
   - Updates UI in real-time

### Backend Changes:

1. **eventController.ts**
   - Added `checkInAttendee` method
   - Validates organizer permissions
   - Finds or creates user from Clerk ID
   - Calls service layer for check-in

2. **eventService.ts**
   - Added `checkInAttendee` method
   - Validates registration status
   - Prevents duplicate check-ins
   - Updates attendance record

3. **eventRoutes.ts**
   - Added `POST /:id/checkin` route
   - Protected with `requireAuth` middleware

## UI/UX Enhancements

### User Profile:
- QR code card with clear instructions
- Prominent placement in Overview tab
- User identification below QR code

### Check-In Page:
- Mobile-responsive design
- Large, easy-to-use scanner interface
- Clear start/stop buttons
- Real-time attendee list with check-in status
- Color-coded status indicators (green for checked in)
- Success/error toast notifications

### Event Detail Modal:
- Added "QR Code Check-In" button for organizers
- Purple button with QR icon
- Available before and after event date
- Navigates to dedicated check-in page

## Security Considerations

1. **Authorization**: Only event organizers can access check-in page
2. **Validation**: Backend validates all check-in requests
3. **QR Code Format**: Structured JSON with type validation
4. **Timestamp**: Included in QR code (not currently validated, but available for future use)

## Mobile Optimization

- Camera access optimized for mobile devices
- Back camera selected by default
- Responsive layout for small screens
- Touch-friendly buttons and controls
- Large scanning area for easy targeting

## Future Enhancements

1. **Offline Support**: Cache attendee list for offline check-in
2. **Bulk Check-In**: Allow manual selection of multiple attendees
3. **Check-In History**: Track check-in timestamps
4. **QR Code Expiry**: Add time-based validation to QR codes
5. **Export**: Generate check-in reports
6. **Notifications**: Send confirmation to attendees upon check-in

## Testing

### Manual Testing Checklist:
- [ ] User can view their QR code on profile page
- [ ] QR code scanner requests camera permission
- [ ] Scanner successfully reads QR codes
- [ ] Only organizers can access check-in page
- [ ] Check-in updates attendee status
- [ ] Duplicate check-ins are prevented
- [ ] Error messages display correctly
- [ ] Mobile camera works properly
- [ ] Attendee list updates in real-time

## Files Modified/Created

### Frontend:
- `src/components/user/UserQRCode.tsx` (new)
- `src/components/user/index.ts` (new)
- `src/components/event/QRCodeScanner.tsx` (new)
- `src/pages/EventCheckInPage.tsx` (new)
- `src/pages/UserProfilePage.tsx` (modified)
- `src/components/event/EventDetailModal.tsx` (modified)
- `src/App.tsx` (modified)
- `package.json` (modified)

### Backend:
- `server/src/controllers/eventController.ts` (modified)
- `server/src/services/eventService.ts` (modified)
- `server/src/routes/eventRoutes.ts` (modified)

## Deployment Notes

1. Ensure camera permissions are properly configured in production
2. HTTPS required for camera access in browsers
3. Test on various mobile devices and browsers
4. Consider rate limiting for check-in endpoint
5. Monitor for QR code scanning performance issues

## Support

For issues or questions:
- Check browser camera permissions
- Ensure HTTPS is enabled
- Verify user is registered for the event
- Check that user is the event organizer
- Review browser console for errors