Initial commit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/REVIEW_QUEUE_STRUCTURE.md

@@ -0,0 +1,107 @@
+# Review Queue Directory Structure
+
+## Overview
+The review queue maintains the same directory structure as the final destination to keep files organized and make it clear where they came from.
+
+## Directory Structure
+
+When a file doesn't match face recognition and is moved to review:
+
+```
+Original destination:  /opt/immich/md/social media/instagram/posts/filename.mp4
+↓
+Review location:      /opt/immich/review/social media/instagram/posts/filename.mp4
+```
+
+### Examples
+
+**Instagram Post:**
+```
+/opt/immich/md/social media/instagram/posts/evalongoria_20251101.jpg
+→
+/opt/immich/review/social media/instagram/posts/evalongoria_20251101.jpg
+```
+
+**Instagram Story:**
+```
+/opt/immich/md/social media/instagram/stories/evalongoria_story.mp4
+→
+/opt/immich/review/social media/instagram/stories/evalongoria_story.mp4
+```
+
+**TikTok Reel:**
+```
+/opt/immich/md/social media/tiktok/reels/video.mp4
+→
+/opt/immich/review/social media/tiktok/reels/video.mp4
+```
+
+## Database Storage
+
+When files are moved to review, the database stores:
+
+1. **file_path**: Current location in review directory
+   ```
+   /opt/immich/review/social media/instagram/posts/filename.mp4
+   ```
+
+2. **metadata.intended_path**: Original intended destination
+   ```json
+   {
+     "intended_path": "/opt/immich/md/social media/instagram/posts/filename.mp4"
+   }
+   ```
+
+## Implementation
+
+### move_module.py (for new downloads)
+```python
+base_path = Path("/opt/immich/md")
+if destination.is_relative_to(base_path):
+    relative_path = destination.relative_to(base_path)
+    review_dest = Path("/opt/immich/review") / relative_path
+else:
+    review_dest = Path("/opt/immich/review") / source.name
+```
+
+### retroactive_face_scan.py (for existing files)
+```python
+base_path = Path(SCAN_BASE_DIR)  # /opt/immich/md
+file_path_obj = Path(file_path)
+
+if file_path_obj.is_relative_to(base_path):
+    relative_path = file_path_obj.relative_to(base_path)
+    review_path = Path(REVIEW_DIR) / relative_path
+else:
+    review_path = Path(REVIEW_DIR) / file_path_obj.name
+```
+
+## Review UI Operations
+
+### Keep Operation
+When user clicks "Keep" in Review UI:
+1. Reads `metadata.intended_path` from database
+2. Moves file from `/opt/immich/review/...` to `intended_path`
+3. Updates database `file_path` to final location
+4. Removes `intended_path` from metadata
+
+### Delete Operation
+- Deletes file from review directory
+- Removes database entry
+
+### Add Reference Operation
+1. Extracts face encoding from file
+2. Adds to face recognition references
+3. Moves file to `intended_path`
+4. Updates database
+
+## Benefits
+
+1. **Organization**: Easy to see file types and sources at a glance
+2. **Clarity**: Maintains context of where file came from
+3. **Batch Operations**: Can select all files from a specific platform/type
+4. **Filtering**: Can filter review queue by platform or source
+5. **Restoration**: Simple to move files back to intended location
+
+## Version
+Updated in v6.6.0 (2025-11-01)