src/features/discovery/docs/cloud_extraction_implementation_guide.md

# Cloud Extraction & Product Detection Guide

This document details the configuration, implementation, and safeguards that ensure successful video frame extraction and product identification in the cloud environment.

## 1. Cloud Video Extraction (`server.js`)

**Problem**: Cloud IPs (Hugging Face/AWS/GCP) are aggressively blocked by YouTube, causing `403 Forbidden` or `Sign in to confirm you're not a bot` errors.

**Solution**:
- **Authentication**: We use browser cookies exported via `YT_DLP_COOKIES_BASE64` environment variable. This authenticates the request as a legitimate user session.
- **Failover Logic**:
  1.  **Primary**: Attempt direct extraction with `yt-dlp` using cookies.
  2.  **Fallback**: If direct extraction fails (e.g., age-gated or heavy throttling), the system falls back to downloading the highest quality thumbnail available (`maxresdefault` -> `sddefault` -> `hqdefault`).
  3.  **IPv4 Forcing**: While previously discussed, specific IP forcing is less critical than valid cookies.

**Configuration Requirements**:
- `YT_DLP_COOKIES_BASE64`: Required env var containing base64-encoded Netscape format cookies.
- `yt-dlp` binary must act as a mobile client (User-Agent spoofing handles this internally in some versions, but cookies are key).

## 2. Product Detection & Thumbnails

**Problem**: Detected objects sometimes lacked cropped images (e.g., bounding box failures or `sharp` errors), leading to empty cards in the UI.

**Solution**:
- **Vision Model**: We utilize `Qwen/Qwen2.5-VL-7B-Instruct` for its strong multi-modal understanding and JSON output reliability.
- **Thumbnail Guarantee**:
  - The system attempts to crop the detected object from the frame.
  - **Regression Fix**: If the crop fails or detection comes from a full-frame analysis (fallback mode), the system **automatically uploads the full frame** as the product thumbnail.
  - This guarantees 100% image coverage for every detected product.

## 3. Data Privacy & Diagnostics

**Problem**: Diagnostic logs (e.g., "Extracted 4 frames") were appearing as "products" in the public or moderation UI, confusing users.

**Solution**:
- **Status Segregation**:
  - Valid Products: `status = 'pending_review'` (default) or `approved`.
  - Diagnostics/Errors: `status = 'rejected'`.
- **Database Hygiene**:
  - All internal logging (e.g., `logDiag`) explicitly sets `status='rejected'`.
  - Error catches in major workflows (e.g., `extractFrames`) log errors to DB with `rejected` status for debugging without polluting the UI.
- **Frontend Filtering**:
  - `ShowcaseService` explicitly filters out `status='rejected'` items from both the **Public Showcase** and **Moderation Queue**.
  - This ensures that even if a diagnostic log is generated, it remains invisible to the end-user.

## 4. Infrastructure & Deployment

**Problem**: Server timeouts or cold starts on serverless platforms (Vercel) caused extraction to fail mid-process.

**Solution**:
- **Persistent Worker**: We deploy the heavy extraction worker on **Hugging Face Spaces** (Docker/Node.js) which allows for long-running processes (up to 48 hours).
- **Inngest Coordination**: The Vercel app triggers the job via Inngest, but the heavy lifting happens on the dedicated worker, communicating back status updates.

## 5. Maintenance & Monitoring

- **Health Check**: The `/health` endpoint returns the current git version timestamp (e.g., `2026-02-07T19:30:00Z`) to verify successful deployments.
- **Database Cleanup**: Occasional SQL cleanup of old diagnostic logs can keep table size manageable:
  ```sql
  DELETE FROM detected_objects WHERE status = 'rejected' AND created_at < NOW() - INTERVAL '7 days';
  ```