---
description: 
globs: 
alwaysApply: false
---
# Camera Implementation Documentation

## Overview

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

1. QR Code scanning
2. Photo capture

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

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

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