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

Resource Library Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build a real backend resource library with S3 direct-upload preparation and switch the frontend library BFF from mock data to real backend data.

Architecture: Add a dedicated resource-library domain in the FastAPI backend with separate resource and resource-file tables. Expose presign, create, and list APIs, then proxy the list API through the Next.js BFF so the existing resource pages and submit-workbench selectors continue to work without a UI rewrite.

Tech Stack: FastAPI, SQLAlchemy async ORM, Alembic, boto3 presigning, pytest/httpx integration tests, Next.js route handlers, Vitest

---

Task 1: Backend Resource-Library Schema

Files:

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/app/infra/db/models/library_resource.py

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/app/infra/db/models/library_resource_file.py

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon/app/domain/enums.py

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon/app/infra/db/session.py

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/alembic/versions/20260328_0003_resource_library.py

• Test: /Volumes/DockCase/codes/auto-virtual-tryon/tests/test_api.py

• Step 1: Write the failing backend API test for creating and listing library resources

• Step 2: Run the targeted backend test to verify it fails

• Step 3: Add enums and ORM models for resources and resource files

• Step 4: Add an Alembic migration for the new tables and indexes

• Step 5: Ensure test database initialization imports the new models

• Step 6: Run the targeted backend test again and confirm the failure moved forward from missing schema to missing API implementation

Task 2: Backend Presign and Resource APIs

Files:

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon/app/config/settings.py

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/app/api/schemas/library.py

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/app/application/services/library_service.py

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/app/infra/storage/s3.py

• Create: /Volumes/DockCase/codes/auto-virtual-tryon/app/api/routers/library.py

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon/app/main.py

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon/pyproject.toml

• Test: /Volumes/DockCase/codes/auto-virtual-tryon/tests/test_api.py

• Step 1: Write the failing backend test for presign generation

• Step 2: Run the targeted backend presign test and verify it fails

• Step 3: Add S3 settings and a presign helper that derives CDN public URLs

• Step 4: Add request/response schemas for presign, create, and list APIs

• Step 5: Implement the library service and router with one-shot create plus filtered list

• Step 6: Run the targeted backend tests and confirm they pass

Task 3: Frontend BFF Proxy and Mapping

Files:

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon-frontend/app/api/libraries/[libraryType]/route.ts

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon-frontend/src/lib/types/view-models.ts

• Create: /Volumes/DockCase/codes/auto-virtual-tryon-frontend/src/lib/adapters/libraries.ts

• Modify: /Volumes/DockCase/codes/auto-virtual-tryon-frontend/tests/app/api/libraries.route.test.ts

• Step 1: Write the failing frontend route test for backend-proxied library data

• Step 2: Run the targeted frontend test and verify it fails

• Step 3: Add a backend-to-view-model adapter for library resources

• Step 4: Replace the mock route implementation with backend proxying while preserving normalized errors

• Step 5: Run the targeted frontend tests and confirm they pass

Task 4: Verification

Files:

• Test: /Volumes/DockCase/codes/auto-virtual-tryon/tests/test_api.py

• Test: /Volumes/DockCase/codes/auto-virtual-tryon-frontend/tests/app/api/libraries.route.test.ts

• Step 1: Run the backend targeted API tests for presign/create/list

• Step 2: Run the frontend targeted route tests

• Step 3: Run backend lint-equivalent checks if available, otherwise run the relevant pytest command set

• Step 4: Run frontend npm run typecheck and any targeted tests affected by the library route change