auto-virtual-tryon-frontend/docs/superpowers/specs/2026-03-28-resource-library-design.md

Resource Library Design

Goal: Build a real resource-library backend for models, scenes, and garments with S3 direct-upload preparation, persisted resource metadata, and list APIs that the existing frontend library pages can consume.

Scope: Replace mock resource-library data with a dedicated backend resource domain. The first slice supports public-read assets, presigned upload preparation, one-shot resource creation, and real list retrieval. Upload UI is out of scope; API tests and existing frontend readers are the verification path.

Decisions

• Resource-library records are independent from order-generated assets.
• Files are stored in S3 and read publicly through the configured CDN hostname.
• Uploads use a two-step direct-upload flow:
  1. Backend issues presigned upload parameters and storage metadata.
  2. Client uploads to S3 and then creates the resource record with uploaded file metadata.
• A resource can include:
  • one original file
  • one thumbnail file
  • multiple gallery files
• Type-specific fields in the first version:
  • model: gender, age_group
  • scene: environment
  • garment: category
• Garment category remains a plain string for now. Config management can come later.

Backend Shape

• Add a dedicated library_resources table for business metadata.
• Add a dedicated library_resource_files table for uploaded file references.
• Add enums for resource type, file role, and optional status/environment metadata.
• Add API routes for:
  • upload presign
  • resource create
  • resource list
• Keep the existing order asset model untouched.

Frontend Shape

• Keep the existing frontend library pages and submit-workbench readers.
• Replace the current mock BFF implementation with a proxy that calls the new backend list endpoint and maps backend payloads into the existing LibraryItemVM.
• Upload UI is deferred. No new client-side upload forms are required in this slice.

Verification

• Backend integration tests cover:
  • presign response generation
  • resource creation with original/thumbnail/gallery files
  • filtered resource listing by type and type-specific fields
• Frontend route tests cover:
  • successful proxying and mapping from backend payload to existing view-model shape
  • unsupported library-type rejection remains normalized