orion/docs/architecture/media-architecture.md

Media Management Architecture

This document describes the consumer-agnostic media architecture used in the platform.

Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        CONSUMER MODULES                              │
│                                                                      │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐            │
│   │   Catalog   │    │ Art Gallery │    │   Future    │            │
│   │             │    │  (future)   │    │   Module    │            │
│   │ ProductMedia│    │ GalleryMedia│    │ XxxMedia    │            │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘            │
│          │                  │                  │                    │
│          └──────────────────┼──────────────────┘                    │
│                             │                                       │
│                             ▼                                       │
│   ┌─────────────────────────────────────────────────────────────┐  │
│   │                      CMS Module                              │  │
│   │                                                              │  │
│   │   MediaFile (generic, consumer-agnostic storage)            │  │
│   │   MediaService (upload, download, metadata management)       │  │
│   └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Design Principles

1. Consumer-Agnostic Storage

The CMS module provides generic media storage without knowing what entities will use the media files. This means:

• MediaFile stores file metadata (path, size, type, dimensions)
• MediaService handles upload, download, and file operations
• CMS has no knowledge of products, galleries, or any specific consumers

2. Consumer-Owned Associations

Each module that needs media defines its own association table:

• Catalog: ProductMedia links products to media files
• Future Art Gallery: Would define GalleryMedia
• Future Blog: Would define PostMedia

This follows the principle: The consumer knows what it needs, the provider doesn't need to know who uses it.

3. Correct Dependency Direction

WRONG (Hidden Dependency):
  CMS → Catalog (CMS knows about Product)

CORRECT:
  Catalog → CMS (Catalog uses MediaFile)

Optional modules (catalog) depend on core modules (cms), never the reverse.

Key Components

MediaFile Model (CMS)

# app/modules/cms/models/media.py

class MediaFile(Base, TimestampMixin):
    """Generic store media file - consumer-agnostic."""

    __tablename__ = "media_files"

    id = Column(Integer, primary_key=True)
    store_id = Column(Integer, ForeignKey("stores.id"), nullable=False)

    # File identification
    filename = Column(String(255), nullable=False)  # UUID-based
    original_filename = Column(String(255))
    file_path = Column(String(500), nullable=False)

    # File properties
    media_type = Column(String(20), nullable=False)  # image, video, document
    mime_type = Column(String(100))
    file_size = Column(Integer)

    # Image/video dimensions
    width = Column(Integer)
    height = Column(Integer)

    # Metadata
    alt_text = Column(String(500))
    description = Column(Text)
    folder = Column(String(100), default="general")

    # Usage tracking (updated by consumers)
    usage_count = Column(Integer, default=0)

    # Note: Consumer-specific associations (ProductMedia, etc.) are defined
    # in their respective modules. CMS doesn't know about specific consumers.

MediaService (CMS)

The MediaService provides generic operations:

# app/modules/cms/services/media_service.py

class MediaService:
    """Generic media operations - consumer-agnostic."""

    async def upload_file(self, db, store_id, file_content, filename, folder="general"):
        """Upload a file to store's media library."""
        ...

    def get_media(self, db, store_id, media_id):
        """Get a media file by ID."""
        ...

    def get_media_library(self, db, store_id, skip=0, limit=100, **filters):
        """List store's media files with filtering."""
        ...

    def update_media_metadata(self, db, store_id, media_id, **metadata):
        """Update file metadata (alt_text, description, etc.)."""
        ...

    def delete_media(self, db, store_id, media_id):
        """Delete a media file."""
        ...

ProductMedia Model (Catalog)

# app/modules/catalog/models/product_media.py

class ProductMedia(Base, TimestampMixin):
    """Product-specific media association - owned by catalog."""

    __tablename__ = "product_media"

    id = Column(Integer, primary_key=True)
    product_id = Column(Integer, ForeignKey("products.id", ondelete="CASCADE"))
    media_id = Column(Integer, ForeignKey("media_files.id", ondelete="CASCADE"))

    # Usage type: main_image, gallery, variant, thumbnail, swatch
    usage_type = Column(String(50), nullable=False, default="gallery")
    display_order = Column(Integer, default=0)
    variant_id = Column(Integer)  # For variant-specific images

    # Relationships
    product = relationship("Product", back_populates="media_associations")
    media = relationship("MediaFile", lazy="joined")

ProductMediaService (Catalog)

# app/modules/catalog/services/product_media_service.py

class ProductMediaService:
    """Product-media association operations - catalog-specific."""

    def attach_media_to_product(self, db, store_id, product_id, media_id,
                                 usage_type="gallery", display_order=0):
        """Attach a media file to a product."""
        # Verify ownership, create ProductMedia association
        ...

    def detach_media_from_product(self, db, store_id, product_id, media_id,
                                   usage_type=None):
        """Detach media from a product."""
        ...

    def get_product_media(self, db, product_id, usage_type=None):
        """Get media associations for a product."""
        ...

    def set_main_image(self, db, store_id, product_id, media_id):
        """Set the main image for a product."""
        ...

Adding Media Support to a New Module

When creating a new module that needs media (e.g., an art gallery module):

Step 1: Create Your Association Model

# app/modules/art_gallery/models/gallery_media.py

from sqlalchemy import Column, ForeignKey, Integer, String
from sqlalchemy.orm import relationship
from app.core.database import Base

class GalleryMedia(Base):
    """Gallery-specific media association."""

    __tablename__ = "gallery_media"

    id = Column(Integer, primary_key=True)
    artwork_id = Column(Integer, ForeignKey("artworks.id", ondelete="CASCADE"))
    media_id = Column(Integer, ForeignKey("media_files.id", ondelete="CASCADE"))

    # Gallery-specific fields
    is_primary = Column(Boolean, default=False)
    caption = Column(String(500))

    # Relationships
    artwork = relationship("Artwork", back_populates="media_associations")
    media = relationship("MediaFile", lazy="joined")

Step 2: Create Your Service

# app/modules/art_gallery/services/gallery_media_service.py

from app.modules.cms.models import MediaFile
from app.modules.art_gallery.models import GalleryMedia, Artwork

class GalleryMediaService:
    def attach_media_to_artwork(self, db, artist_id, artwork_id, media_id, **kwargs):
        # Verify artwork belongs to artist
        # Verify media belongs to artist (store_id)
        # Create GalleryMedia association
        ...

Step 3: Use CMS MediaService for File Operations

from app.modules.cms.services.media_service import media_service

# Upload a new file
media_file = await media_service.upload_file(
    db=db,
    store_id=artist_id,
    file_content=file_bytes,
    filename="artwork.jpg",
    folder="artworks",
)

# Then attach it to your entity
gallery_media_service.attach_media_to_artwork(
    db=db,
    artist_id=artist_id,
    artwork_id=artwork.id,
    media_id=media_file.id,
    is_primary=True,
)

Benefits of This Architecture

1. Module Independence: Catalog can be disabled without affecting CMS
2. Extensibility: New modules easily add media support
3. No Hidden Dependencies: Dependencies flow in one direction
4. Clean Separation: CMS handles storage, consumers handle associations
5. Testability: Can test CMS without any consumer modules
6. Single Responsibility: Each module owns its domain

Anti-Patterns to Avoid

Don't: Add Consumer References to MediaFile

# BAD - Creates hidden dependency
class MediaFile(Base):
    # CMS now depends on catalog!
    product_associations = relationship("ProductMedia", ...)

Don't: Put Consumer Logic in MediaService

# BAD - CMS shouldn't know about products
class MediaService:
    def attach_to_product(self, db, product_id, media_id):
        from app.modules.catalog.models import ProductMedia  # Wrong!

Don't: Query Consumer Models from CMS

# BAD - Hidden dependency
def get_media_usage(self, db, media_id):
    from app.modules.catalog.models import ProductMedia  # Wrong!
    return db.query(ProductMedia).filter(...).all()

Related Documentation

• Module System Architecture - Module structure and dependencies
• Cross-Module Import Rules - Import restrictions
• Audit Provider Pattern - Similar provider pattern for audit logging