Scenarios

Sequence diagrams and narratives for the seven in-scope scenarios defined in the Scenario Inventory. Each diagram uses five sub-systems: User, SPA, BFF, Backend, and Storage (a black box per TD-07). For the structural overview — sub-system responsibilities, dependencies, and shared interface contracts — see design.md. AWS-specific details are in aws-specification.md.

Conventions

• Happy path focus. Diagrams show the primary success path. Error paths are described in the narrative.
• DRY references. Scenarios that share system interactions reference the primary scenario (S1) rather than repeating the sequence.
• Presigned POST. Per TD-08, all uploads use presigned POST (form-based) with server-side policy enforcement.
• Fetch-and-store. Per TD-01, external HTTPS URLs are fetched SPA-side, edited, and uploaded via the managed path. No external URLs are persisted.

---

S1: Upload Image (Managed Path)

Use cases covered: GEN::MEDIA::0001::0001.UC, 0002.FS (file/drag-drop/clipboard), 0003.FS (formats/limits), 0005.FS (preview/crop), 0006.FS (confirm/persist)

Design decisions: TD-01, TD-03, TD-04, TD-05, TD-06, TD-07, TD-08

Requirements: FR-001, FR-002, FR-006, FR-008, FR-009, FR-013–FR-024

This is the primary scenario covering file selection, drag-and-drop, and clipboard paste inputs. All other managed-upload scenarios reference this one.

Caution

The entity update path shown above (PUT /api/items/<itemEId>) uses the current plural BFF route. Arda-cards/management#847 will standardize all BFF routes to singular convention (PUT /api/item/<itemEId>). Before implementing, check the resolution of that ticket and use the correct endpoint path.

Narrative

1. Activate: The user clicks an empty image placeholder or a “Change image” control. The SPA displays the unified input surface (drop zone with visual cues, file picker button, URL text field, dismiss button).

2. Provide: The user provides an image via file selection, drag-and-drop, clipboard paste, or data:/blob: URI text. The SPA detects the input type automatically (FR-002). For data: or blob: URI text, the SPA decodes the content as image data and routes it through this same managed upload path (FR-007); if decoding fails, the unrecognized-text error is shown. Format validation (FR-008) and size validation (FR-009) happen immediately. If the file exceeds the maximum size, the SPA attempts auto-compression before rejecting.

3. Edit and Confirm: The image appears in the preview editor at the entity-type aspect ratio (1:1 for Items). The user can crop, zoom, rotate, pan, and reset. A copyright acknowledgment checkbox must be accepted (FR-018). On confirm, the SPA applies the crop parameters and generates the final Blob.

4. Request Credentials: The SPA requests presigned POST credentials via the BFF. The BFF proxies the request to the Backend (Operations), adding authentication headers and tenant context. The Backend generates a UUID-based object key, constructs presigned POST form fields with policy conditions (Content-Type, Content-Length, key prefix, expiry), and returns them.

5. Upload: The SPA uploads the image directly to Storage using the presigned POST form. File bytes never pass through the BFF or Backend (TD-06).

6. Persist: The SPA uses the cdnUrl returned by the Backend (in the presigned credential response) and updates the entity via the BFF/Backend API. The Backend validates the URL matches the expected CDN pattern (TD-05), verifies the object exists in Storage via HEAD, and persists the URL on the entity.

Error Paths

• Validation failure (format, size): SPA shows inline plain-language error (FR-013). User can retry immediately.
• Presigned credential failure (Backend unavailable): SPA shows error toast. User can retry.
• Upload failure (network, S3 error): SPA allows retry with same image. Credentials re-requested if expired (NFR-010).
• Entity persist failure (Backend validation rejects URL): SPA shows error. Image is orphaned in Storage; cleanup deferred (NFR-012).

---

S2: Set Image from External URL

Use cases covered: GEN::MEDIA::0001::0002.FS (URL text entry), 0004.FS (URL validation)

Design decisions: TD-01, TD-02, TD-05

Requirements: FR-003, FR-004, FR-010, FR-011

This scenario covers the fetch-and-store variant where the user provides an HTTPS URL. The SPA fetches the image, renders it in the editor, and then follows the S1 upload path.

Narrative

1. Provide URL: The user types or pastes text into the input surface. The SPA detects the HTTPS URL pattern and validates the scheme (FR-010). Non-HTTPS schemes are rejected immediately with a plain-language message.

2. Reachability Check: The SPA attempts a HEAD request directly to the URL to verify reachability and content type (FR-011). If CORS blocks the request, the SPA falls back to the BFF’s reachability-check endpoint (TD-02). The BFF only checks external URLs — never URLs on managed storage (NFR-008). The BFF endpoint is rate-limited to prevent SSRF abuse (NFR-009).

3. Fetch and Load: Once reachability is confirmed, the SPA fetches the full image (direct or via BFF fallback if CORS). The image is loaded into the editor canvas for preview.

4. Remainder: From this point, the flow is identical to S1 Steps 3–6: the user edits (crop/zoom/rotate), accepts the copyright acknowledgment, the SPA uploads to Storage via presigned POST, and persists the CDN URL on the entity. The original external URL is never persisted (TD-01, TD-05). Note that the presigned credential request (S1 Step 4) happens after the final Blob is produced (post-crop), because the contentLength and contentType sent to the Backend must reflect the final edited image, not the original fetch.

Error Paths

• Non-HTTPS scheme: SPA rejects immediately: “Only secure web addresses (https) are accepted.”
• Unreachable URL: SPA shows: “We couldn’t load an image from this address.”
• Non-image content type: SPA shows: “The link doesn’t point to a supported image type.”
• CORS failure + BFF fallback failure: SPA shows generic reachability error.
• Fetch timeout: SPA shows: “The image is taking too long to load.”

---

S3: Remove Image

Use cases covered: GEN::MEDIA::0002::0001.UC

Design decisions: (none specific — uses existing entity update flow)

Requirements: FR-025, FR-026, FR-027

Narrative

1. Initiate: The user clicks the remove/clear control on the entity’s image area. The SPA displays a confirmation dialog: “Remove this image? The Item will show a default placeholder instead.”

2. Confirm: On confirm, the SPA sends an entity update with imageUrl: null. The Backend clears the image URL field. The previous image reference is retained in the entity’s bitemporal version history (FR-027). The managed asset in Storage is not deleted — it remains accessible for historical display.

3. Display: The entity reverts to the default placeholder (initials or generic icon).

Error Paths

• Cancel: No change to entity. Dialog dismissed.
• Backend failure: SPA shows error toast. Image remains unchanged.

---

S4: View Image (Read Path)

Use cases covered: GEN::MEDIA::0003::0001.UC (grid thumbnail), 0002.FS (hover quick inspection), 0003.FS (fallback/error)

Design decisions: TD-06, TD-07

Requirements: FR-028, FR-029, FR-030, FR-031

This scenario covers the read-only display of images in grid views and the inspector overlay. Images are served from CDN with authentication via CloudFront signed cookies (TD-11). The BFF issues cookies; the SPA refreshes them proactively and on tenant switch (TD-12).

Narrative

1. Cookie Provisioning: Before any CDN image request, the SPA must hold valid CloudFront signed cookies for the active tenant (FR-036). Cookies are issued by the BFF at session start, refreshed proactively at ~50% of TTL (FR-037), and re-requested immediately on tenant switch (FR-038). The cookies are set on .arda.cards with Secure; HttpOnly; SameSite=Lax, so the browser sends them automatically with <img> requests to the CDN subdomain (same-site).

2. Grid Rendering: When the entity list loads, the SPA renders image thumbnails from CDN URLs stored on the entities (FR-028). The browser includes signed cookies with each CDN request. CloudFront validates the cookie signature against the trusted key group and verifies the requested path falls within the tenant prefix. No Backend round-trip is needed for image delivery (TD-06, NFR-014). Display states:

   • No image (imageUrl is null): default placeholder with initials or generic icon.
   • Loading: lightweight shimmer indicator (FR-031). Thumbnail replaces shimmer without reflow (NFR-004).
   • 403 (expired/wrong-tenant cookie): SPA detects 403, refreshes cookies via BFF, retries the request. Brief shimmer during refresh.
   • Error (URL unreachable after retry): default placeholder with error badge (FR-030). Silent — no toast or error message.

3. Hover Quick Inspection: Hovering over a thumbnail for ~500ms shows a ImageHoverPreview popover with a larger preview of the image (FR-029). Cookies are sent automatically with the CDN request. The popover dismisses on mouse-out. No action icons are shown — the popover is purely for quick visual inspection. Not shown for error-state thumbnails. Single click on the cell selects the row (AG Grid default); double-click / Enter triggers the edit flow (S5).

Error Paths

• Expired cookies: SPA detects 403 on CDN request, calls BFF to refresh cookies, retries. Transparent to user (shimmer during brief refresh).
• Tenant switch in progress: SPA shows shimmer on all image cells until new cookies arrive. Brief visual interruption (~200-500ms for cookie refresh).
• CDN unavailable: Grid shows shimmer, then falls back to placeholder + error badge after timeout. No system error displayed.
• Slow network: Shimmer shown until loaded. No timeout toast in grid context (unlike URL input where a timeout message is appropriate).

---

S5: Grid Inline Edit

Use cases covered: GEN::MEDIA::0001::0007.FS

Design decisions: SD-15

Requirements: FR-032, FR-033

This scenario covers the entry point for image editing from within a grid view. The upload mechanics are identical to S1/S2.

Narrative

1. Trigger: Double-click or Enter on an image cell activates AG Grid’s ImageCellEditor, which opens a modal overlay with the full image editor (FR-032). The overlay prevents interaction with the background grid.

2. Provide and Edit: The user provides an image via any supported input method. The existing entity image is shown for comparison (same comparison layout as the form context). The upload flow follows S1 or S2 depending on input type.

3. Update Grid: On confirm, the entity is updated and the modal closes. The grid row refreshes to show the new thumbnail (FR-033). On discard, the overlay closes with no change.

Error Paths

• Discard: Modal closes, no change to entity.
• Same upload/persist errors as S1.

---

S6: Set Image During Item Creation

Use cases covered: REF::ITM::0003::0010.UC

Design decisions: (delegates to S1/S2 for upload mechanics)

Requirements: FR-034

This scenario shows how image upload integrates with the item creation form. The image is optional and persisted alongside other fields on form submission.

Narrative

1. Open Form: The user clicks “Add Item.” The form opens with an image field showing a default placeholder.

2. Fill Fields: The user fills in item fields (name, SKU, etc.). Field blur triggers auto-draft saving via the BFF/Backend. The draft does not yet include an image.

3. Set Image (optional): The user activates the image area and provides an image via any supported method. The upload follows S1 or S2. The resulting CDN URL is held in SPA form state — it is not yet persisted on the entity until form submission. If the user skips this step, the item is saved without an image (FR-034). Prerequisite: The presigned credential request (POST /v1/item/<itemEId>/image-upload-url) requires a persisted entity ID. The SPA must ensure a draft has been saved (Step 2) before requesting upload credentials. If the user activates the image area before any fields have been filled, the SPA triggers an auto-draft-save first.

4. Submit: On Publish or Save as Draft, the SPA sends all fields including imageUrl to the Backend. The Backend validates and persists.

Error Paths

• Cancel form: Any uploaded image becomes an orphan; cleaned up by Storage lifecycle rule (NFR-012).
• Form validation failure: Image already uploaded remains in Storage; orphan cleanup handles it if the form is never submitted.

---

S7: Change/Remove Image During Item Edit

Use cases covered: REF::ITM::0004::0006.UC

Design decisions: (delegates to S1/S2 for change, S3 for remove)

Requirements: FR-035

This scenario shows image change and removal within the item edit flow. It composes S1/S2 (change) and S3 (remove).

Narrative

1. Open Edit Form: The user selects an item and clicks Edit. The form loads with current data including the existing image.

2. Option A — Change Image: The user activates the image area. The current image is shown alongside the new preview for comparison (FR-016). The upload follows S1 or S2. The old image reference is retained in the entity’s bitemporal version history (FR-027).

3. Option B — Remove Image: The user clicks the remove control. A confirmation dialog appears per S3. On confirm, the image URL is set to null.

4. Submit: On Publish or Save as Draft, the updated (or cleared) image URL is persisted alongside all other item fields.

Error Paths

• Same as S1/S2 for change, S3 for remove.
• Cancel form after uploading new image: New image orphaned in Storage; lifecycle rule handles cleanup. Old image remains on entity.

---

Scenario Cross-Reference

Scenario	Use Cases	Key Decisions	Requirements
S1: Upload Image	0001::0001.UC, 0002.FS, 0003.FS, 0005.FS, 0006.FS	TD-01, TD-03, TD-04, TD-05, TD-06, TD-07, TD-08	FR-001–002, FR-006–009, FR-013–024
S2: External URL	0001::0002.FS (URL), 0004.FS	TD-01, TD-02, TD-05	FR-003–004, FR-010–011
S3: Remove Image	0002::0001.UC	—	FR-025–027
S4: View Image	0003::0001.UC, 0002.FS (hover inspection), 0003.FS	TD-06, TD-07, TD-11, TD-12, CD-08 (revised)	FR-028–031, FR-036–039
S5: Grid Inline Edit	0001::0007.FS	SD-15	FR-032–033
S6: Item Creation	REF::ITM::0003::0010.UC	(via S1/S2)	FR-034
S7: Item Edit	REF::ITM::0004::0006.UC	(via S1/S2/S3)	FR-035

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved