crowd-funder-from-jason/doc/qr-code-implementation-guide.md

# QR Code Implementation Guide

## Overview

This document describes the QR code scanning and generation implementation in the TimeSafari application. The system uses a platform-agnostic design with specific implementations for web and mobile platforms.

## Architecture

### Directory Structure
```
src/
├── services/
│   └── QRScanner/
│       ├── types.ts              # Core interfaces and types
│       ├── QRScannerFactory.ts   # Factory for creating scanner instances
│       ├── CapacitorQRScanner.ts # Mobile implementation using MLKit
│       ├── WebInlineQRScanner.ts # Web implementation using MediaDevices API
│       └── interfaces.ts         # Additional interfaces
├── components/
│   └── QRScanner/
│       └── QRScannerDialog.vue   # Shared UI component
└── views/
    ├── ContactQRScanView.vue     # Dedicated scanning view
    └── ContactQRScanShowView.vue # Combined QR display and scanning view
```

### Core Components

1. **Factory Pattern**
   - `QRScannerFactory` - Creates appropriate scanner instance based on platform
   - Common interface `QRScannerService` implemented by all scanners
   - Platform detection via Capacitor and build flags

2. **Platform-Specific Implementations**
   - `CapacitorQRScanner` - Native mobile implementation using MLKit
   - `WebInlineQRScanner` - Web browser implementation using MediaDevices API
   - `QRScannerDialog.vue` - Shared UI component

3. **View Components**
   - `ContactQRScanView` - Dedicated view for scanning QR codes
   - `ContactQRScanShowView` - Combined view for displaying and scanning QR codes

## Implementation Details

### Core Interfaces

```typescript
interface QRScannerService {
  checkPermissions(): Promise<boolean>;
  requestPermissions(): Promise<boolean>;
  isSupported(): Promise<boolean>;
  startScan(options?: QRScannerOptions): Promise<void>;
  stopScan(): Promise<void>;
  addListener(listener: ScanListener): void;
  onStream(callback: (stream: MediaStream | null) => void): void;
  cleanup(): Promise<void>;
}

interface ScanListener {
  onScan: (result: string) => void;
  onError?: (error: Error) => void;
}

interface QRScannerOptions {
  camera?: "front" | "back";
  showPreview?: boolean;
  playSound?: boolean;
}
```

### Platform-Specific Implementations

#### Mobile (Capacitor)
- Uses `@capacitor-mlkit/barcode-scanning`
- Native camera access through platform APIs
- Optimized for mobile performance
- Supports both iOS and Android
- Real-time QR code detection
- Back camera preferred for scanning

Configuration:
```typescript
// capacitor.config.ts
const config: CapacitorConfig = {
  plugins: {
    MLKitBarcodeScanner: {
      formats: ['QR_CODE'],
      detectorSize: 1.0,
      lensFacing: 'back',
      googleBarcodeScannerModuleInstallState: true
    }
  }
};
```

#### Web
- Uses browser's MediaDevices API
- Vue.js components for UI
- EventEmitter for stream management
- Browser-based camera access
- Inline camera preview
- Responsive design
- Cross-browser compatibility

### View Components

#### ContactQRScanView
- Dedicated view for scanning QR codes
- Full-screen camera interface
- Simple UI focused on scanning
- Used primarily on native platforms
- Streamlined scanning experience

#### ContactQRScanShowView
- Combined view for QR code display and scanning
- Shows user's own QR code
- Handles user registration status
- Provides options to copy contact information
- Platform-specific scanning implementation:
  - Native: Button to navigate to ContactQRScanView
  - Web: Built-in scanning functionality

### QR Code 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: Uses `qrcode-stream` for real-time scanning
   - Native: Uses `@capacitor-mlkit/barcode-scanning`

3. **Scanning Process**
   - Camera stream initialization
   - Real-time frame analysis
   - QR code detection and decoding
   - 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

## Build Configuration

### Common Vite Configuration
```typescript
// vite.config.common.mts
export async function createBuildConfig(mode: string) {
  const isCapacitor = mode === "capacitor";
  
  return defineConfig({
    define: {
      'process.env.VITE_PLATFORM': JSON.stringify(mode),
      'process.env.VITE_PWA_ENABLED': JSON.stringify(!isNative),
      __IS_MOBILE__: JSON.stringify(isCapacitor),
      __USE_QR_READER__: JSON.stringify(!isCapacitor)
    },
    optimizeDeps: {
      include: [
        '@capacitor-mlkit/barcode-scanning',
        'vue-qrcode-reader'
      ]
    }
  });
}
```

### Platform-Specific Builds
```json
{
  "scripts": {
    "build:web": "vite build --config vite.config.web.mts",
    "build:capacitor": "vite build --config vite.config.capacitor.mts",
    "build:all": "npm run build:web && npm run build:capacitor"
  }
}
```

## 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. Invalid QR code format
7. Expired QR codes
8. Duplicate contact attempts
9. Network connectivity issues

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

## Security Considerations

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

## 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
5. Battery usage optimization

### User Experience
1. Clear visual feedback
2. Camera preview
3. Scanning status indicators
4. Error messages
5. Success confirmations
6. Intuitive camera controls
7. Smooth camera switching
8. Responsive UI feedback

## Testing

### Test Scenarios
1. Permission handling
2. Camera switching
3. Error conditions
4. Platform compatibility
5. Performance metrics
6. QR code detection
7. Contact processing
8. Security validation

### Test Environment
- Multiple browsers
- iOS and Android devices
- Various network conditions
- Different camera configurations

## Dependencies

### Key Packages
- `@capacitor-mlkit/barcode-scanning`
- `qrcode-stream`
- `vue-qrcode-reader`
- Platform-specific camera APIs

## Maintenance

### Regular Updates
- Keep dependencies updated
- Monitor platform changes
- Update documentation
- Review security patches

### Performance Monitoring
- Track memory usage
- Monitor camera performance
- Check error rates
- Analyze user feedback