Media Pipeline

Purpose

This page defines how listing photos move from upload to processed variants.

Core Rules

• listing media lives in object storage, not on the host filesystem
• the durable Phase 1 store is AWS Lightsail object storage
• provider access must stay abstract enough to move to Amazon S3 later
• the first pipeline is deterministic and non-AI
• AI work, if added later, is optional async work and never blocks baseline usability

Scope

This pipeline covers:

• upload flow
• object key ownership
• database state in listing_media
• deterministic image processing
• replacement and deletion behavior

Separation Of Concerns

Listing media is different from brand assets.

Rules:

• brand assets are curated product design files
• listing media belongs to seller inventory and moderation workflows
• do not mix storage ownership or serving rules between those systems

Source Format Rule

Seller uploads may start as:

• HEIC
• HEIF
• JPG
• PNG
• WebP

Those source uploads stay private in object storage. They are the processing input, not the buyer-facing gallery format.

Manager-owned seller upload limits are separate from those format rules.

Rules:

• batch size, source-file size, minimum dimensions, aspect-ratio range, megapixel cap, and short undo window now belong to the DB-backed site-policy layer
• the API publishes the live upload values through GET /v1/meta/media-rules and the seller /photos workspace
• clients must not hardcode those numeric limits locally

Variant Direction

The first stable image roles are:

• small thumbnail
• card image
• preview image
• larger detail image
• largest detail image

The exact implementation names may evolve, but the variant purpose must stay stable across API and UI surfaces.

Current normalized output rule:

• gallery, card, preview, and detail variants are written as WebP
• clients should treat those processed variants as the normal display format
• clients should not assume the original upload format is the same as the gallery format

Async Processing

The request path should create the record and store the original object.

Background work may then:

• normalize metadata
• generate deterministic variants
• update processing state
• optionally run AI review if the DB-backed site policy enables it

Celery handles the async step. It does not sit in the request path.

Review Gate

The deterministic worker and the AI worker are separate concerns.

Rules:

• deterministic processing may produce ready media plus WebP display variants
• if site_policies.photo_review_enabled = false, those ready photos remain gallery-eligible after processing
• if site_policies.photo_review_enabled = true, ready photos stay out of seller and public gallery surfaces until review completes with an allowed result
• if site_policies.photo_review_enabled = true but site_policies.photo_review_provider = disabled, review attempts fail into seller-visible retryable tray rows until a real provider is configured
• the live Gemini provider path is now verified end to end, but the production rollout flag is still intentionally off after that check
• public listing media access, public gallery selection, saved-list cover selection, and seller gallery reads must all follow the same review gate

Replacement Rule

Replacement uploads must not cut over early.

Rules:

• deterministic processing alone must not delete the current live photo
• the current live photo stays in place while the replacement is still uploading, processing, or waiting on review
• replacement cutover only happens after the new photo passes the review gate