# 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

### 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

### 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

## 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
- Falls back to file selection if camera unavailable
- Processes captured images for consistent format

#### 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

#### ElectronPlatformService

Desktop implementation (currently unimplemented).

**Status:**

- Camera functionality not yet implemented
- Planned to use Electron's media APIs

## 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

### Image Upload and Processing

**Implementation:**
- Secure server upload
- Authentication handling
- Image format standardization
- Error handling and retry
- Progress feedback

**Flow:**
1. Image is prepared for upload
2. Authentication token is obtained
3. Multipart form data is created
4. Upload progress is monitored
5. Server URL is returned

## Platform-Specific Considerations

### iOS

- Requires `NSCameraUsageDescription` in Info.plist
- Supports both front and back cameras
- Implements proper permission handling

### Android

- Requires camera permissions in manifest
- Supports both front and back cameras
- Handles permission requests through Capacitor

### Web

- Requires HTTPS for camera access
- Implements fallback mechanisms
- Handles browser compatibility issues

## 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

### Error Response

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

## Security Considerations

### Permission Management

- Explicit permission requests
- Permission state tracking
- Graceful handling of denied permissions

### Data Handling

- Secure image processing
- Proper cleanup of camera resources
- No persistent storage of camera data

## 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

### Performance

1. Optimize camera resolution
2. Implement proper resource cleanup
3. Handle camera switching efficiently
4. Manage memory usage

### User Experience

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

## 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

### Known Issues

1. Electron camera implementation pending
2. Some browser compatibility limitations
3. Platform-specific quirks to address

## Dependencies

### Key Packages

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

## Testing

### Test Scenarios

1. Permission handling
2. Camera switching
3. Error conditions
4. Platform compatibility
5. Performance metrics

### Test Environment

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