feat: implement self-contained module architecture (Phase 1 & 2)

Phase 1 - Foundation:
- Add app/modules/contracts/ with Protocol definitions for cross-module
  communication (ServiceProtocol, ContentServiceProtocol, MediaServiceProtocol)
- Enhance app/modules/base.py ModuleDefinition with self-contained module
  support (is_self_contained, services_path, models_path, etc.)
- Update app/templates_config.py with multi-directory template loading
  using Jinja2 ChoiceLoader for module templates

Phase 2 - CMS Pilot Module:
- Migrate CMS service to app/modules/cms/services/content_page_service.py
- Create app/modules/cms/exceptions.py with CMS-specific exceptions
- Configure app/modules/cms/models/ to re-export ContentPage from canonical
  location (models.database) to avoid circular imports
- Update cms_module definition with is_self_contained=True and paths
- Add backwards compatibility shims with deprecation warnings:
  - app/services/content_page_service.py -> app.modules.cms.services
  - app/exceptions/content_page.py -> app.modules.cms.exceptions

Note: SQLAlchemy models remain in models/database/ as the canonical location
to avoid circular imports at startup time. Module model packages re-export
from the canonical location.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/modules/contracts/__init__.py

@@ -0,0 +1,32 @@
+# app/modules/contracts/__init__.py
+"""
+Cross-module contracts using Protocol pattern.
+
+This module defines type-safe interfaces for cross-module communication.
+Modules depend on protocols rather than concrete implementations, enabling:
+- Loose coupling between modules
+- Testability through mock implementations
+- Clear dependency boundaries
+
+Usage:
+    from app.modules.contracts.cms import ContentServiceProtocol
+
+    class OrderService:
+        def __init__(self, content: ContentServiceProtocol | None = None):
+            self._content = content
+
+        @property
+        def content(self) -> ContentServiceProtocol:
+            if self._content is None:
+                from app.modules.cms.services import content_page_service
+                self._content = content_page_service
+            return self._content
+"""
+
+from app.modules.contracts.base import ServiceProtocol
+from app.modules.contracts.cms import ContentServiceProtocol
+
+__all__ = [
+    "ServiceProtocol",
+    "ContentServiceProtocol",
+]

app/modules/contracts/base.py

@@ -0,0 +1,47 @@
+# app/modules/contracts/base.py
+"""
+Base protocol definitions for cross-module communication.
+
+Protocols define the interface that services must implement without
+requiring inheritance. This allows for:
+- Duck typing with static type checking
+- Easy mocking in tests
+- Module independence
+"""
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+
+@runtime_checkable
+class ServiceProtocol(Protocol):
+    """
+    Base protocol for all module services.
+
+    Services should be stateless and operate on database sessions
+    passed as arguments. This ensures:
+    - Thread safety
+    - Transaction boundaries are clear
+    - Easy testing with mock sessions
+    """
+
+    pass
+
+
+@runtime_checkable
+class CRUDServiceProtocol(Protocol):
+    """
+    Protocol for services that provide CRUD operations.
+
+    All methods receive a database session as the first argument.
+    """
+
+    def get_by_id(self, db: "Session", id: int) -> object | None:
+        """Get entity by ID."""
+        ...
+
+    def delete(self, db: "Session", id: int) -> bool:
+        """Delete entity by ID. Returns True if deleted."""
+        ...

app/modules/contracts/cms.py

@@ -0,0 +1,148 @@
+# app/modules/contracts/cms.py
+"""
+CMS module contracts.
+
+Defines the interface for content management functionality that other
+modules can depend on without importing the concrete implementation.
+"""
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+
+@runtime_checkable
+class ContentServiceProtocol(Protocol):
+    """
+    Protocol for content page service.
+
+    Defines the interface for retrieving and managing content pages
+    with three-tier resolution (platform > vendor default > vendor override).
+    """
+
+    def get_page_for_vendor(
+        self,
+        db: "Session",
+        platform_id: int,
+        slug: str,
+        vendor_id: int | None = None,
+        include_unpublished: bool = False,
+    ) -> object | None:
+        """
+        Get content page with three-tier resolution.
+
+        Resolution order:
+        1. Vendor override (platform_id + vendor_id + slug)
+        2. Vendor default (platform_id + vendor_id=NULL + is_platform_page=False + slug)
+
+        Args:
+            db: Database session
+            platform_id: Platform ID
+            slug: Page slug
+            vendor_id: Vendor ID (None for defaults only)
+            include_unpublished: Include draft pages
+
+        Returns:
+            ContentPage or None
+        """
+        ...
+
+    def get_platform_page(
+        self,
+        db: "Session",
+        platform_id: int,
+        slug: str,
+        include_unpublished: bool = False,
+    ) -> object | None:
+        """
+        Get a platform marketing page.
+
+        Args:
+            db: Database session
+            platform_id: Platform ID
+            slug: Page slug
+            include_unpublished: Include draft pages
+
+        Returns:
+            ContentPage or None
+        """
+        ...
+
+    def list_pages_for_vendor(
+        self,
+        db: "Session",
+        platform_id: int,
+        vendor_id: int | None = None,
+        include_unpublished: bool = False,
+        footer_only: bool = False,
+        header_only: bool = False,
+        legal_only: bool = False,
+    ) -> list:
+        """
+        List all available pages for a vendor storefront.
+
+        Merges vendor overrides with vendor defaults, prioritizing overrides.
+
+        Args:
+            db: Database session
+            platform_id: Platform ID
+            vendor_id: Vendor ID (None for vendor defaults only)
+            include_unpublished: Include draft pages
+            footer_only: Only pages marked for footer display
+            header_only: Only pages marked for header display
+            legal_only: Only pages marked for legal/bottom bar display
+
+        Returns:
+            List of ContentPage objects
+        """
+        ...
+
+    def list_platform_pages(
+        self,
+        db: "Session",
+        platform_id: int,
+        include_unpublished: bool = False,
+        footer_only: bool = False,
+        header_only: bool = False,
+    ) -> list:
+        """
+        List platform marketing pages.
+
+        Args:
+            db: Database session
+            platform_id: Platform ID
+            include_unpublished: Include draft pages
+            footer_only: Only pages marked for footer display
+            header_only: Only pages marked for header display
+
+        Returns:
+            List of platform marketing ContentPage objects
+        """
+        ...
+
+
+@runtime_checkable
+class MediaServiceProtocol(Protocol):
+    """
+    Protocol for media library service.
+
+    Defines the interface for managing media files (images, documents, etc.).
+    """
+
+    def get_media_by_id(
+        self,
+        db: "Session",
+        media_id: int,
+    ) -> object | None:
+        """Get media item by ID."""
+        ...
+
+    def list_media_for_vendor(
+        self,
+        db: "Session",
+        vendor_id: int,
+        media_type: str | None = None,
+    ) -> list:
+        """List media items for a vendor."""
+        ...