# Camera Implementation Documentation

## Overview

This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for several purposes:

1. QR Code scanning for contact sharing and verification
2. Photo capture for gift records
3. Profile photo management
4. Shared photo handling
5. Image upload and processing

## Components

### QRScannerDialog.vue

Primary component for QR code scanning in web browsers.

**Key Features:**

- Uses `qrcode-stream` for web-based QR scanning
- Supports both front and back cameras
- Provides real-time camera status feedback
- Implements error handling with user-friendly messages
- Includes camera switching functionality

**Camera Access Flow:**

1. Checks for camera API availability
2. Enumerates available video devices
3. Requests camera permissions
4. Initializes camera stream with preferred settings
5. Handles various error conditions with specific messages

### PhotoDialog.vue

Component for photo capture and selection.

**Key Features:**

- Cross-platform photo capture interface
- Image cropping capabilities
- File selection fallback
- Unified interface for different platforms
- Progress feedback during upload
- Comprehensive error handling

**Camera Access Flow:**

1. User initiates photo capture
2. Platform-specific camera access is requested
3. Image is captured or selected
4. Optional cropping is performed
5. Image is processed and uploaded
6. URL is returned to caller

### ImageMethodDialog.vue

Component for selecting image input method.

**Key Features:**
- Multiple input methods (camera, file upload, URL)
- Unified interface for image selection
- Integration with PhotoDialog for processing
- Support for image cropping
- URL-based image handling

**Camera Access Flow:**

1. User selects camera option
2. PhotoDialog is opened for capture
3. Captured image is processed
4. Image is returned to parent component

### SharedPhotoView.vue

Component for handling shared photos.

**Key Features:**
- Processes incoming shared photos
- Options to use photo for gifts or profile
- Image preview and confirmation
- Server upload integration
- Temporary storage management

**Photo Processing Flow:**

1. Photo is shared to application
2. Stored temporarily in IndexedDB
3. User chooses usage (gift/profile)
4. Image is processed accordingly
5. Server upload is performed

### ContactQRScanShowView.vue

Component for QR code scanning in contact sharing.

**Key Features:**
- QR code scanning interface
- Camera controls (start/stop)
- Platform-specific implementations
- Error handling and status feedback

**Camera Access Flow:**

1. User initiates scanning
2. Camera permissions are checked
3. Camera stream is initialized
4. QR codes are detected in real-time
5. Results are processed

## Services

### QRScanner Services

#### WebDialogQRScanner

Web-based implementation of QR scanning.

**Key Methods:**

- `checkPermissions()`: Verifies camera permission status
- `requestPermissions()`: Requests camera access
- `isSupported()`: Checks for camera API support
- Handles various error conditions with specific messages

#### CapacitorQRScanner

Native implementation using Capacitor's MLKit.

**Key Features:**

- Uses `@capacitor-mlkit/barcode-scanning`
- Supports both front and back cameras
- Implements permission management
- Provides continuous scanning capability

### Platform Services

#### WebPlatformService

Web-specific implementation of platform features.

**Camera Capabilities:**

- Uses HTML5 file input with capture attribute for mobile
- Uses getUserMedia API for desktop webcam access
- Falls back to file selection if camera unavailable
- Processes captured images for consistent format
- Handles both mobile and desktop browser environments

#### CapacitorPlatformService

Native implementation using Capacitor.

**Camera Features:**

- Uses `Camera.getPhoto()` for native camera access
- Supports image editing
- Configures high-quality image capture
- Handles base64 image processing
- Provides native camera UI

#### ElectronPlatformService

Desktop implementation (currently unimplemented).

**Status:**

- Camera functionality not yet implemented
- Planned to use Electron's media APIs
- Will support desktop camera access

## Camera Usage Scenarios

### Gift Photo Capture

**Implementation:**
- Uses PhotoDialog for capture/selection
- Supports multiple input methods
- Optional image cropping
- Server upload with authentication
- Integration with gift records

**Flow:**
1. User initiates photo capture from gift details
2. ImageMethodDialog presents input options
3. PhotoDialog handles capture/selection
4. Image is processed and uploaded
5. URL is attached to gift record

### Profile Photo Management

**Implementation:**
- Uses same PhotoDialog component
- Enforces square aspect ratio
- Requires image cropping
- Updates user profile settings
- Handles profile image updates

**Flow:**
1. User initiates profile photo update
2. PhotoDialog opens with cropping enabled
3. Image is captured/selected
4. User crops to square aspect ratio
5. Image is uploaded and profile updated

### Shared Photo Processing

**Implementation:**
- Handles incoming shared photos
- Temporary storage in IndexedDB
- Options for photo usage
- Server upload integration
- Cleanup after processing

**Flow:**
1. Photo is shared to application
2. Stored temporarily in IndexedDB
3. SharedPhotoView presents options
4. User chooses usage (gift/profile)
5. Image is processed accordingly

### QR Code Scanning

**Implementation:**
- Platform-specific scanning components
- Real-time camera feed processing
- QR code detection and validation
- Contact information processing
- Error handling and retry

**Flow:**
1. User initiates QR scanning
2. Camera permissions are checked
3. Camera stream is initialized
4. QR codes are detected
5. Contact information is processed

### QR Code Workflow

**Implementation Details:**

The QR code scanning workflow is implemented across multiple components and services to provide a seamless experience for contact sharing and verification. The system supports both web-based and native implementations through platform-specific services.

#### QR Code Generation

**Contact QR Codes:**
- Generated using `qrcode.vue` component
- Contains encrypted contact information
- Includes user ID and verification data
- Supports offline sharing
- Implements error correction

**QR Code Format:**
```json
{
  "type": "contact",
  "userId": "encrypted_user_id",
  "timestamp": "creation_time",
  "version": "qr_code_version",
  "data": "encrypted_contact_data"
}
```

#### QR Code Scanning Workflow

**1. Initiation:**
- User selects "Scan QR Code" option
- Platform-specific scanner is initialized
- Camera permissions are verified
- Appropriate scanner component is loaded

**2. Platform-Specific Implementation:**

*Web Implementation:*
- Uses `qrcode-stream` for real-time scanning
- Supports both front and back cameras
- Implements continuous scanning
- Provides visual feedback for scanning status
- Handles browser compatibility issues

*Native Implementation (Capacitor):*
- Uses `@capacitor-mlkit/barcode-scanning`
- Leverages native camera capabilities
- Provides optimized scanning performance
- Supports multiple barcode formats
- Implements native permission handling

**3. Scanning Process:**
- Camera stream is initialized
- Real-time frame analysis begins
- QR codes are detected and decoded
- Validation of QR code format
- Processing of contact information

**4. Contact Processing:**
- Decryption of contact data
- Validation of user information
- Verification of timestamp
- Check for duplicate contacts
- Processing of shared data

**5. Error Handling:**
- Invalid QR code format
- Expired QR codes
- Duplicate contact attempts
- Network connectivity issues
- Permission denials
- Camera access problems

**6. Success Flow:**
- Contact information is extracted
- User is prompted for confirmation
- Contact is added to user's list
- Success notification is displayed
- Camera resources are cleaned up

#### Security Measures

**QR Code Security:**
- Encryption of contact data
- Timestamp validation
- Version checking
- User verification
- Rate limiting for scans

**Data Protection:**
- Secure transmission of contact data
- Validation of QR code authenticity
- Prevention of duplicate scans
- Protection against malicious codes
- Secure storage of contact information

#### User Experience

**Scanning Interface:**
- Clear visual feedback
- Camera preview
- Scanning status indicators
- Error messages
- Success confirmations

**Accessibility:**
- Support for different screen sizes
- Clear instructions
- Error recovery options
- Alternative input methods
- Offline capability

#### Performance Considerations

**Optimization:**
- Efficient camera resource usage
- Quick QR code detection
- Minimal processing overhead
- Battery usage optimization
- Memory management

**Platform-Specific Optimizations:**
- Web: Optimized for browser performance
- Native: Leverages device capabilities
- Desktop: Efficient resource usage
- Mobile: Battery and performance balance

## Platform-Specific Considerations

### iOS

- Requires `NSCameraUsageDescription` in Info.plist
- Supports both front and back cameras
- Implements proper permission handling
- Uses native camera UI through Capacitor
- Handles photo library access

### Android

- Requires camera permissions in manifest
- Supports both front and back cameras
- Handles permission requests through Capacitor
- Uses native camera UI
- Manages photo library access

### Web

- Requires HTTPS for camera access
- Implements fallback mechanisms
- Handles browser compatibility issues
- Uses getUserMedia API on desktop
- Uses file input with capture on mobile
- Supports multiple input methods

## Error Handling

### Common Error Scenarios

1. No camera found
2. Permission denied
3. Camera in use by another application
4. HTTPS required
5. Browser compatibility issues
6. Upload failures
7. Image processing errors

### Error Response

- User-friendly error messages
- Troubleshooting tips
- Clear instructions for resolution
- Platform-specific guidance
- Graceful fallbacks

## Security Considerations

### Permission Management

- Explicit permission requests
- Permission state tracking
- Graceful handling of denied permissions
- Platform-specific permission handling
- Secure permission storage

### Data Handling

- Secure image processing
- Proper cleanup of camera resources
- No persistent storage of camera data
- Secure server upload
- Temporary storage management

## Best Practices

### Camera Access

1. Always check for camera availability
2. Request permissions explicitly
3. Handle all error conditions
4. Provide clear user feedback
5. Implement proper cleanup
6. Use platform-specific optimizations

### Performance

1. Optimize camera resolution
2. Implement proper resource cleanup
3. Handle camera switching efficiently
4. Manage memory usage
5. Optimize image processing
6. Handle upload efficiently

### User Experience

1. Clear status indicators
2. Intuitive camera controls
3. Helpful error messages
4. Smooth camera switching
5. Responsive UI feedback
6. Platform-appropriate UI

## Future Improvements

### Planned Enhancements

1. Implement Electron camera support
2. Add advanced camera features
3. Improve error handling
4. Enhance user feedback
5. Optimize performance
6. Add image compression options

### Known Issues

1. Electron camera implementation pending
2. Some browser compatibility limitations
3. Platform-specific quirks to address
4. Mobile browser camera access limitations
5. Image upload performance on slow connections

## Dependencies

### Key Packages

- `@capacitor-mlkit/barcode-scanning`
- `qrcode-stream`
- `vue-picture-cropper`
- `@capacitor/camera`
- Platform-specific camera APIs

## Testing

### Test Scenarios

1. Permission handling
2. Camera switching
3. Error conditions
4. Platform compatibility
5. Performance metrics
6. Upload scenarios
7. Image processing

### Test Environment

- Multiple browsers
- iOS and Android devices
- Desktop platforms
- Various network conditions 
- Different camera configurations