Overview

GitHub Ticket: https://github.com/Arda-cards/management/issues/316

This project delivers the ability for users to attach images to Items (and, by extension, any entity that supports a media field). It covers the full stack: infrastructure (S3 storage, CDN delivery, presigned upload workflow), backend API integration, and user experience design.

Scope

Use cases: Set, replace, remove, and view entity images via a unified input surface supporting file selection, drag-and-drop, clipboard paste, URL entry, and camera capture. Includes grid thumbnail display, image inspector overlay, and inline edit from grid.
First entity: Item product images (1:1 square aspect ratio).
Infrastructure: Managed S3 bucket with CloudFront CDN, presigned POST upload, tenant isolation.
Reusability: Generic entity media components designed for specialization to other entity types (business affiliates, user profiles, orders).

See Scoping for per-scenario scope decisions.

Project Structure

Directory	Contents
Scoping	Per-scenario scope decisions with links to use cases and decision log
Use Case Definition	Use case analysis, Round 1 SME feedback summary, copyright liability consultation
UX Design	UX design work — component designs, interaction specifications, Storybook story plans
Previous Design Work	Backend architecture: FileStore specification, design sessions, decision log
Decision Log	Project-level decisions (SD-01 through SD-16)

Use Case	Description
`GEN::MEDIA::0001`	Set Entity Image — unified input surface (7 scenarios)
`GEN::MEDIA::0002`	Remove Entity Image — clear and revert to placeholder (1 scenario)
`GEN::MEDIA::0003`	View Entity Image — grid thumbnail, inspector overlay, error fallback (3 scenarios)
`REF::ITM::0003::0010`	Set Item Image During Creation
`REF::ITM::0004::0006`	Change or Remove Item Image

Current Status — Completed (2026-04-16)

The project is complete with all core phases delivered and the primary frontend PR (arda-frontend-app#742) merged to main. The following administrative items remain open due to reviewer PTO and are tracked for follow-up:

operations#163 — awaiting review (backend validation + multi-PDF print)
infrastructure#440 — awaiting review (Amplify compute role, CDN env vars)
arda-frontend-app#755 — zoom < 1 canvas export bug (design-system coordinate-space issue)

Completed phases

Phase	Repository	PR	Status
1: AWS Infrastructure	infrastructure	#435	Merged
2a: common-module	common-module	—	Released (8.1.0)
2b: operations endpoints	operations	#161	Merged
3.1: api-proxy publish	api-proxy	#3	Merged (v2.0.0)
3.2–3.4: Design system	ux-prototype	#63–#99	Merged (5.0.0)
3.5: BFF routes	arda-frontend-app	#742	Merged (0.102.0)
3.6: SPA integration	arda-frontend-app	#742	Merged (0.102.0)
3.7: Release	documentation	—	This closure

Previous status

Three backend design sessions were completed, covering bucket organization, CDN integration, upload workflow, S3 abstraction design, and Item module integration. Key architectural decisions (two-bucket strategy, presigned POST with S3-enforced validation, phased CloudFront rollout) are documented in the design decision log.

The user-facing use cases (GEN::MEDIA::0001, GEN::MEDIA::0002, GEN::MEDIA::0003) have been written and reviewed. Round 1 SME feedback has been incorporated — see the feedback summary. Scoping decisions (SD-01 through SD-16) are recorded in the decision log.

A copyright liability consultation has been prepared analyzing the risk profile of each image input method. Two addendums cover the effect of a user-facing copyright verification prompt (recommended for all upload methods) and the constraints required for cross-tenant sharing of image data.

Open Decisions

Id	Decision	Status	Reference
SD-01	Fetch-and-store external URLs	Resolved (TD-01/TD-09 — SPA-side fetch-and-store)	Decision Log, Copyright Consultation
SD-05	Cross-tenant image sharing	Out of scope for this version	Decision Log
SD-10	Auto-compression	In scope (implemented in UX components)	Decision Log