forked from trent_larson/crowd-funder-for-time-pwa
chore: cleanup documents
This commit is contained in:
Matt Raymer
91
doc/DEEP_LINKS.md
Normal file
91
doc/DEEP_LINKS.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# TimeSafari Deep Linking Documentation
|
||||
|
||||
## Type System Overview
|
||||
|
||||
The deep linking system uses a multi-layered type safety approach:
|
||||
|
||||
1. **Runtime Validation (Zod Schemas)**
|
||||
- Validates URL structure
|
||||
- Enforces parameter requirements
|
||||
- Sanitizes input data
|
||||
- Provides detailed validation errors
|
||||
|
||||
2. **TypeScript Types**
|
||||
- Generated from Zod schemas
|
||||
- Ensures compile-time type safety
|
||||
- Provides IDE autocompletion
|
||||
- Catches type errors during development
|
||||
|
||||
3. **Router Integration**
|
||||
- Type-safe parameter passing
|
||||
- Route-specific parameter validation
|
||||
- Query parameter type checking
|
||||
|
||||
## Implementation Files
|
||||
|
||||
- `src/types/deepLinks.ts`: Type definitions and validation schemas
|
||||
- `src/services/deepLinks.ts`: Deep link processing service
|
||||
- `src/main.capacitor.ts`: Capacitor integration
|
||||
|
||||
## Type Safety Examples
|
||||
|
||||
```typescript
|
||||
// Parameter type safety
|
||||
type ClaimParams = DeepLinkParams["claim"];
|
||||
// TypeScript knows this has:
|
||||
// - id: string
|
||||
// - view?: "details" | "certificate" | "raw"
|
||||
// Runtime validation
|
||||
const result = deepLinkSchemas.claim.safeParse({
|
||||
id: "123",
|
||||
view: "details"
|
||||
});
|
||||
// Validates at runtime with detailed error messages
|
||||
```
|
||||
|
||||
## Supported URL Schemes
|
||||
|
||||
All deep links follow the format: `timesafari://<route>/<param>?<query>`
|
||||
|
||||
### Claim Routes
|
||||
|
||||
- `timesafari://claim/:id`
|
||||
- Query params:
|
||||
- `view`: "details" | "certificate" | "raw"
|
||||
|
||||
- `timesafari://claim-cert/:id`
|
||||
- `timesafari://claim-add-raw/:id`
|
||||
- Query params:
|
||||
- `claim`: JSON string of claim data
|
||||
- `claimJwtId`: JWT ID for claim
|
||||
|
||||
### Contact Routes
|
||||
|
||||
- `timesafari://contact-edit/:did`
|
||||
- `timesafari://contact-import/:jwt`
|
||||
- Query params:
|
||||
- `contacts`: JSON array of contacts
|
||||
|
||||
### Project Routes
|
||||
|
||||
- `timesafari://project/:id`
|
||||
- Query params:
|
||||
- `view`: "details" | "edit"
|
||||
|
||||
### Invite Routes
|
||||
|
||||
- `timesafari://invite-one-accept/:jwt`
|
||||
- Query params:
|
||||
- `type`: "one" | "many"
|
||||
|
||||
### Gift Routes
|
||||
|
||||
- `timesafari://confirm-gift/:id`
|
||||
- Query params:
|
||||
- `action`: "confirm" | "details"
|
||||
|
||||
### Offer Routes
|
||||
|
||||
- `timesafari://offer-details/:id`
|
||||
- Query params:
|
||||
- `view`: "details"
|
||||
507
doc/camera-implementation.md
Normal file
507
doc/camera-implementation.md
Normal file
@@ -0,0 +1,507 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user