Overview

This document summarizes the requirements, decisions, and rationale behind the user-facing use cases for entity image management. It bridges the product use case specifications (in GEN::MEDIA and REF::ITM) and the technical design (in this project’s project-description and FileStore design).

Problem Statement

The platform needs the ability to attach images to entities (starting with Items). From a technical perspective, this involves multiple input paths (file upload, URL reference, clipboard paste), different storage backends (managed S3 vs. external URL), and infrastructure concerns (presigned URLs, CDN, tenant isolation). From a user perspective, none of this complexity should be visible.

The core design challenge: define user-facing use cases that hide the implementation boundary between upload and URL reference, so that non-technical personas (particularly Sam Scansworth and Owen Ownerton) encounter a single, coherent experience.

Key Decision: Unified Input Surface

Decision

Define a single use case (GEN::MEDIA::0001 — Set Entity Image) that covers all input methods. The system detects what the user provides and routes it internally. The user never selects a “mode” (upload vs. URL vs. paste).

Rationale

Considered Alternative	Why Rejected
Separate use cases per input method (GEN::IMG::0001 Upload, GEN::IMG::0002 URL, GEN::IMG::0003 Clipboard)	Forces the user to choose a technical path before starting. Non-technical users think “I want to set the picture,” not “I want to upload a file.” Tripled documentation surface with significant overlap.
Two use cases: Upload vs. URL	Still requires mode selection. Users pasting from a browser clipboard wouldn’t know which mode to choose.
URL-only (no managed upload)	Missing the most common case: user has a file on their device. Would force users to host images elsewhere first.

Impact on Technical Design

The unified input surface means:

• The API must accept both a managed upload reference (CDN URL from the presigned workflow) and an external HTTPS URL in the same imageUrl field.
• The client is responsible for detecting input type and routing: file/paste → presigned upload flow; URL text → validation and direct storage.
• The backend validates the stored URL (scheme, format) but does not need to know how it was obtained.

Cross-reference: This decision informs DQ-5 (Upload Workflow and API Design) in the project description — the two-phase presigned upload workflow is the internal implementation for the managed upload path, invisible to the user.

Note

Whether the external URL path should be collapsed into the managed upload path (fetch-and-store at ingest time) is under review. A copyright liability consultation has been prepared analyzing the risk profile of each upload method. The key finding: server-side fetching of external URLs (Method 5b) is the highest-risk scenario and may not qualify for DMCA safe harbor. See Round 1 Feedback T-03 for the pending resolution.

Key Decision: Collapse Replace Into Set

Decision

Replace is not a separate use case. GEN::MEDIA::0001 (Set Entity Image) handles both first-time and replacement scenarios as conditional branches within the same flow.

Rationale

From the user’s perspective, “set the picture” and “change the picture” are the same gesture — they activate the image area and provide a new image. The only UX difference is that the current image is visible during the replacement flow for comparison. This is a functional scenario (GEN::MEDIA::0001::0005.FS), not a separate use case.

Key Decision: data: URIs Are Transient Only

Decision

data: URIs are used only as transient client-side previews (browser-generated from clipboard paste). They are never persisted, never sent to the API, and never stored in entity fields.

Rationale

Concern	Impact
Security	data: URIs can encode HTML/SVG with embedded JavaScript. Storing and rendering them opens XSS vectors.
Storage abuse	A data: URI embeds the full file in a text field, bypassing file size limits that apply to the upload path.
No reachability semantics	The URL reachability check is meaningless — the content is the URL.
CSP complications	Allowing data: in img-src weakens Content Security Policy broadly.

The client extracts the binary payload from the data: URI and routes it through the managed upload path. The stored reference is always a CDN URL. This applies both to browser-generated data: URIs from clipboard paste and to data: or blob: URI strings typed or pasted as text — in either case the system decodes the content and uploads it rather than rejecting it (see GEN::MEDIA::0001::0002.FS).

Cross-reference: This decision reinforces the HTTPS-only scheme validation in GEN::MEDIA::0001::0004.FS and informs DQ-1 (Security of Asset URLs).

Key Decision: HTTPS-Only URL Scheme

Decision

The URL input path accepts only HTTPS URLs. All other schemes (http:, data:, blob:, javascript:, file:) are rejected at both client and server.

Rationale

• Single-scheme validation is simple to implement and explain to users.
• HTTP (without TLS) exposes image content to MITM attacks and mixed-content browser warnings.
• The remaining schemes are either browser-internal (blob:, data:), dangerous (javascript:), or inapplicable (file:).

Cross-reference: Enforced in GEN::MEDIA::0001::0004.FS. Also applies to the bulk import Image column (REF::ITM::0006::0005.FS).

Key Decision: Plain-Language Error Messages

Decision

All validation failures produce plain-language messages that suggest what the user should do, never technical jargon.

Rationale

The personas who set images — especially Irene (Inventory Manager) and Sam (Shop Floor Worker) — are not expected to understand terms like “MIME type”, “Content-Length”, or “presigned URL”. Error messages are written from the user’s perspective:

Technical cause	User-facing message
Content-Type is image/bmp	”This file type isn’t supported. Try a JPEG, PNG, or WebP image.”
File exceeds 10 MB	”This file is too large. The maximum size is 10 MB.”
URL scheme is http:	”Only secure web addresses (https) are accepted.”
HEAD request returns 404	”We couldn’t load an image from this address. Check that the link points directly to an image.”

Use Case Inventory

New Use Cases (GEN::MEDIA)

Written in entity-media.md.

ID	Name	Scenarios	Type
GEN::MEDIA::0001	Set Entity Image	6	1 UC, 5 FS
GEN::MEDIA::0002	Remove Entity Image	1	1 UC, 0 FS
Total		7	2 UC, 5 FS

Amended Existing Use Cases

Use Case	New Scenario	Type	Description
REF::ITM::0003 Create Item	0003::0010.UC	UC	Set item image during creation; delegates to GEN::MEDIA::0001
REF::ITM::0004 Edit Item	0004::0006.UC	UC	Change or remove item image; delegates to GEN::MEDIA::0001/0002
REF::ITM::0006 Bulk Import	0006::0005.FS	FS	Image column rules: HTTPS-only, no reachability check during import
GEN::ENT-DA::0003 Create Entity	0003::0005.FS	FS	Media attachment inheritance note for entity creation
GEN::ENT-DA::0004 Edit Entity	0004::0005.FS	FS	Media update inheritance note for entity editing

Infrastructure (not user-facing)

These are technical specifications in the FileStore design and project description, referenced by the use cases but invisible to users.

Concern	FileStore Reference	Use Case Reference
Presigned upload workflow	Write Flow	GEN::MEDIA::0001::0006.FS (Confirm and Persist)
CDN delivery	Read Flow	GEN::MEDIA::0001::0006.FS (managed upload → CDN URL)
Tenant isolation	DQ-1	GEN::MEDIA::0001::0004.FS (URL validation)
Orphan cleanup	DQ-5	Out of scope — superseded assets are retained for history
Content validation	Content Validation	GEN::MEDIA::0001::0003.FS (formats/limits)
Object key structure	DQ-3	Not user-facing
Bucket strategy	DQ-2	Not user-facing

Traceability: Design Questions ↔ Use Cases

Design Question	Use Cases Informed	Direction
DQ-1: Security of asset URLs	GEN::MEDIA::0001::0004.FS (HTTPS-only, scheme validation)	DQ informs UC
DQ-2: Bucket strategy	No direct user-facing impact	Infrastructure only
DQ-3: Object key structure	No direct user-facing impact	Infrastructure only
DQ-4: S3 abstraction	No direct user-facing impact	Infrastructure only
DQ-5: Upload workflow and API	GEN::MEDIA::0001::0002.FS (input routing), GEN::MEDIA::0001::0006.FS (confirm/persist)	Bidirectional — UC defines the user contract, DQ defines the technical implementation
DQ-6: CDN configuration	GEN::MEDIA::0001::0005.FS (preview loading from CDN), GEN::MEDIA::0001::0006.FS (CDN URL storage)	DQ informs UC
DQ-8 (implied): Image replacement	GEN::MEDIA::0001::0001.UC (replacement branch) — orphan cleanup is out of scope; superseded assets are retained for history	UC informs DQ

Open Items

Item	Status	Notes
Crop behavior per entity type	Deferred	GEN::MEDIA::0001::0005.FS states cropping is optional per entity type. Specific crop ratios for Items are not yet defined.
Mobile camera capture UX	Accepted	Camera capture accepted as a fifth named input method in GEN::MEDIA::0001::0002.FS. Detailed mobile interaction design (tap targets, viewfinder, orientation) deferred to a future mobile UX session. See Round 1 Feedback T-10.
Image display in Item list grid	Not specified	The Item list already shows an Image thumbnail column. How the thumbnail is generated (resize pipeline vs. CSS scaling) is a technical concern deferred to the FileStore design.
Bulk image import (multiple images per operation)	Out of scope	Declared out of scope in the project description. The CSV column accepts URLs only; file uploads are single-entity operations.
Reachability check during bulk import	Decision: skip	REF::ITM::0006::0005.FS explicitly skips reachability checks during bulk import to avoid blocking on external servers.
Fetch-and-store for external URLs	Resolved	Resolved by TD-01 during system design. SPA-side fetch-and-store: external URLs are fetched by the SPA, rendered in the image editor, then uploaded via the managed presigned-upload path. All persisted image URLs originate from managed storage. See Copyright Liability Consultation and Decision Log.
Copyright verification prompt	Recommended	The consultation’s Addendum 1 recommends a per-upload copyright acknowledgment for all input methods. Strengthens DMCA safe harbor, red-flag knowledge defense, and contractual indemnification. See Round 1 Feedback T-11.
Cross-tenant image sharing constraints	Recommended	The consultation’s Addendum 2 identifies constraints for cross-tenant sharing: authenticated access only, tenant-initiated sharing, copyright acknowledgment on share, EU counsel review. See Round 1 Feedback T-12.

---