From 29983f11a9e43f9a590e508367ae28dc9b3f64be Mon Sep 17 00:00:00 2001
From: Matthew Raymer <matthew.raymer@anomalistdesign.com>
Date: Fri, 2 May 2025 10:30:09 +0000
Subject: [PATCH] doc: camera system details

---
 docs/camera-implementation.md | 97 +++++++++++++++++++++++++++++++++--
 1 file changed, 94 insertions(+), 3 deletions(-)

diff --git a/docs/camera-implementation.md b/docs/camera-implementation.md
index 4e4b2415..495023a8 100644
--- a/docs/camera-implementation.md
+++ b/docs/camera-implementation.md
@@ -2,10 +2,13 @@
 
 ## Overview
 
-This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for two main purposes:
+This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for several purposes:
 
-1. QR Code scanning
-2. Photo capture
+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
 
@@ -40,6 +43,28 @@ Component for photo capture and selection.
 - 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
@@ -98,6 +123,72 @@ Desktop implementation (currently unimplemented).
 - 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