Entity Media Management
Feature code: GEN::MEDIA
The Entity Media Management feature provides a unified capability for attaching, replacing, and removing images on any entity in the platform. The first entity to use this capability is the Item (REF::ITM); the design is intentionally cross-cutting so that future entity types (Business Affiliates, Facilities, Kanban Cards) can inherit it without re-specifying the interaction model.
Use case reference: Entity Media Behaviors (GEN::MEDIA::0001, GEN::MEDIA::0002, GEN::MEDIA::0003)
Unified Input Surface
Section titled “Unified Input Surface”The defining characteristic of this feature is that the user has a single interaction point for providing an image. The system automatically detects how the image was provided and handles it accordingly. There is no mode selector, no “Upload” vs. “URL” toggle, and no technical terminology exposed to the user.
A user can provide an image by:
- Selecting a file from their device or dragging a file onto the image area.
- Pasting image content from the clipboard.
- Pasting or typing an image web address (URL).
- Pasting a raw image data string (such as a base64-encoded image copied from a technical source).
- Capturing a photo with a device camera (mobile devices).
All methods converge into the same preview and confirmation step. The user sees a preview of the image before committing. If the entity already has an image, the current image remains visible alongside the preview for comparison.
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0001 | The system shall provide a single image input surface that accepts file selection, drag-and-drop, clipboard paste, URL text entry, and data URI text without requiring the user to select an input mode. |
GEN::MEDIA::FR-0002 | The system shall automatically detect the input method and route the provided image through the appropriate internal processing path. All paths converge to the managed upload path — no input method results in a directly persisted external URL. |
GEN::MEDIA::FR-0003 | The system shall display a preview of the provided image before the user confirms, regardless of input method. |
GEN::MEDIA::FR-0004 | When replacing an existing image, the system shall display the current image alongside the new preview for visual comparison. |
Accepted Formats and Constraints
Section titled “Accepted Formats and Constraints”The system accepts images in JPEG, PNG, WebP, HEIC, and HEIF formats. HEIC/HEIF is the default photo format on modern iPhones and many Android devices; accepting these formats natively avoids forcing users to convert before uploading. A maximum file size applies regardless of input method (default: 10 MB, configurable per entity type). Entity types may define minimum dimension requirements where image quality matters for display (e.g., product catalog thumbnails).
When an image does not meet these constraints, the system provides a plain-language explanation of the problem and what the user should do instead. Technical jargon (MIME types, content-length headers, payload limits) is never exposed.
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0005 | The system shall accept images in JPEG, PNG, WebP, HEIC, and HEIF formats. |
GEN::MEDIA::FR-0006 | The system shall enforce a maximum file size per entity type, with a platform default of 10 MB. |
GEN::MEDIA::FR-0007 | The system shall support configurable minimum image dimensions per entity type. |
GEN::MEDIA::FR-0008 | All validation error messages shall use plain language understandable by non-technical users and suggest a corrective action. |
URL Validation
Section titled “URL Validation”When the user provides a web address, the system validates it before accepting it as an image reference:
- Only secure web addresses (HTTPS) are accepted. All other address schemes are rejected.
- The system checks that the address responds and returns image content of a supported type.
- Addresses that cannot be reached or that point to non-image content are rejected with a clear explanation.
These validations apply at both the client and the server to ensure that stored image references are always valid HTTPS URLs.
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0009 | The system shall accept only HTTPS URLs as external image references. All other URI schemes (http:, data:, blob:, javascript:, file:) shall be rejected for persistence. |
GEN::MEDIA::FR-0010 | The system shall verify URL reachability and confirm the response is an image of a supported content type before accepting it. |
GEN::MEDIA::FR-0011 | URL scheme validation shall be enforced on both client and server (defense in depth). |
Data URI Handling
Section titled “Data URI Handling”When a user pastes or types a raw data URI string (e.g., a base64-encoded image), the system decodes it and processes the resulting image through the managed upload path — the same path used for file selection and clipboard paste. Data URIs are never stored as entity image references. If the data URI cannot be decoded into a valid image, the system shows an error.
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0012 | The system shall decode data: and blob: URI text input and route the decoded content through the managed upload path. |
GEN::MEDIA::FR-0013 | The system shall never persist a data: or blob: URI as an entity image reference. |
Preview and Crop
Section titled “Preview and Crop”After the system accepts the input, the user sees a preview rendered at the target aspect ratio defined by the entity type. Entity types that benefit from user-controlled framing (e.g., product photos that must fit a square thumbnail) may enable cropping, allowing the user to reposition and scale the visible area within the preview.
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0014 | The system shall render an image preview at the target aspect ratio defined by the entity type. |
GEN::MEDIA::FR-0015 | The system shall support crop functionality, allowing the user to reposition and scale the visible area within the entity-type aspect ratio. V1 always enables crop with a locked aspect ratio. Per-entity-type optionality (disabling crop for entity types that don’t need it) is deferred to a future release. |
Image Replacement and Removal
Section titled “Image Replacement and Removal”Replacing an image is the same flow as setting one for the first time — the user activates the image area and provides a new image. The only difference is that the current image is shown alongside the preview for comparison.
Removing an image clears the entity’s image reference and reverts the display to a default placeholder. The system prompts for confirmation before removing.
In both cases, the previous image is retained in the entity’s version history for audit purposes. Archival and purging of superseded or disassociated assets is out of scope.
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0016 | Replacing an existing image shall use the same interaction flow as setting an image for the first time. |
GEN::MEDIA::FR-0017 | Removing an image shall require user confirmation and revert the entity display to a default placeholder. |
GEN::MEDIA::FR-0018 | Previous image references shall be retained in the entity’s version history. The system shall not automatically delete superseded image assets. |
Storage Model
Section titled “Storage Model”From the user’s perspective, all images “just work” — they appear wherever the entity is displayed. Behind the scenes, all images are stored in platform-managed storage and delivered through a content delivery network, regardless of how the user provided them.
- File, clipboard, and data URI inputs are uploaded directly to managed storage via the presigned upload workflow.
- HTTPS URL inputs are fetched client-side, rendered in the image editor for crop/zoom/rotate, and then uploaded to managed storage via the same presigned upload workflow. The external URL is never persisted as the entity’s image reference.
This unified storage path simplifies the rendering model (all images come from the CDN), eliminates availability concerns from external URLs becoming unreachable, and ensures consistent URL validation at the backend (all persisted URLs match the expected CDN host and key pattern).
Requirements
Section titled “Requirements”| ID | Requirement |
|---|---|
GEN::MEDIA::FR-0019 | Images provided via file, clipboard, or data URI shall be uploaded to platform-managed storage and served through a CDN. |
GEN::MEDIA::FR-0020 | HTTPS URLs provided by the user shall be fetched client-side, processed through the image editor, and uploaded to platform-managed storage. External URLs shall not be persisted as entity image references. |
Summary
Section titled “Summary”| Aspect | Detail |
|---|---|
| Feature code | GEN::MEDIA |
| Requirements | GEN::MEDIA::FR-0001 through GEN::MEDIA::FR-0020 |
| Use cases | GEN::MEDIA::0001 (Set Entity Image), GEN::MEDIA::0002 (Remove Entity Image), GEN::MEDIA::0003 (View Entity Image) |
| Initial entity | Item (REF::ITM) |
| Personas | All personas who create or edit entities with image fields |
Copyright: © Arda Systems 2025-2026, All rights reserved