ADR 0002: Polymorphic media with unified collection names

Status: Proposed
Date: 2025-10-17

Context

Multiple domains (vendors, listings, users, etc.) need to attach images and other media. Each domain could have implemented its own fields and storage patterns (e.g. vendor_photos, listing_gallery, user_avatar), but that leads to:

• Duplicated logic for uploads, resizing, ordering, and deletion
• Inconsistent naming and behaviour across the app
• Harder cross-cutting tooling (e.g. media management, CDNs, caching)

Decision

Use a central polymorphic media system with unified collection names:

• A single Media model represents all stored media assets
• A polymorphic mediable pivot links media to any owning model
• Collections such as avatar, gallery, hero, documents are shared across entities
  • We do not prefix collection names with the entity type (e.g. vendor_gallery)
  • The mediable_type column already distinguishes between entities
• Additional metadata (e.g. order, collection) lives on the pivot

This gives a single, consistent way to attach and manage media across the platform.

Consequences

Positive

• Shared upload, transformation, and deletion logic across all domains
• Consistent collection naming simplifies UI and API design
• Easy to build cross-entity tools (media dashboards, cleanup jobs) using one schema

Negative / trade-offs

• The central media system becomes a dependency of many domains
• Requires care when evolving the Media model or pivot schema
• Some queries can be more complex than simple foreign-key columns on each table

Related documentation

• Architecture overview – Media Architecture