feat: define unified schema (Artist, Source, Post, ImageRecord, etc.) and initial migration

Implements the data model from spec §3 in one go so FC-2/FC-3 don't need
schema-adding migrations of their own. Artist is the unified entity for
both gallery 'artist:' tags and GallerySubscriber Subscriptions
(is_subscription flag). ImageProvenance is many-to-one, enabling the
enrich-on-duplicate rule for downloaded content that pHash-matches an
existing record.

The SigLIP embedding column uses pgvector(1152) for SigLIP-so400m;
swapping models in FC-2 will require a column-width migration.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/app/models/__init__.py

@@ -1,7 +1,24 @@
 """All ORM models. Import this module to make every model visible to Alembic."""
 
+from .artist import Artist
 from .base import Base
+from .credential import Credential
+from .download_event import DownloadEvent
+from .image_provenance import ImageProvenance
+from .image_record import ImageRecord
+from .post import Post
+from .source import Source
+from .tag import Tag, image_tag
 
-# Concrete models land in Task 6 and re-export here.
-
-__all__ = ["Base"]
+__all__ = [
+    "Base",
+    "Artist",
+    "Source",
+    "Credential",
+    "Post",
+    "ImageRecord",
+    "ImageProvenance",
+    "Tag",
+    "image_tag",
+    "DownloadEvent",
+]

backend/app/models/artist.py

@@ -0,0 +1,33 @@
+"""Artist — unified entity that is both the gallery's ``artist:`` tag concept
+and GallerySubscriber's Subscription. ``is_subscription`` is True if any
+Sources are attached.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, Integer, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .base import Base
+
+
+class Artist(Base):
+    __tablename__ = "artist"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
+    slug: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # True once a Source is attached; flips false if all sources removed.
+    is_subscription: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
+    # Per-artist scheduling overrides; null means "use global default".
+    auto_check: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    check_interval_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+
+    sources = relationship("Source", back_populates="artist", cascade="all, delete-orphan")

backend/app/models/credential.py

@@ -0,0 +1,24 @@
+"""Credential — encrypted blob (cookies/token/oauth) scoped per-platform,
+not per-source. One Patreon credential serves every Patreon source.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, LargeBinary, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class Credential(Base):
+    __tablename__ = "credential"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    platform: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
+    kind: Mapped[str] = mapped_column(String(32), nullable=False)  # cookies|token|oauth
+    encrypted_blob: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="active")
+    captured_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

backend/app/models/download_event.py

@@ -0,0 +1,28 @@
+"""DownloadEvent — log of every gallery-dl run, populated by FC-3."""
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Integer, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class DownloadEvent(Base):
+    __tablename__ = "download_event"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    source_id: Mapped[int] = mapped_column(
+        ForeignKey("source.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    post_id: Mapped[int | None] = mapped_column(
+        ForeignKey("post.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    status: Mapped[str] = mapped_column(String(32), nullable=False)  # pending|running|ok|error
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    bytes_downloaded: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    files_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)

backend/app/models/image_provenance.py

@@ -0,0 +1,33 @@
+"""ImageProvenance — links an ImageRecord to a Post.
+
+Many-to-one (one image, many provenance rows) enables the enrich-on-duplicate
+rule (spec §3): when a downloaded image is a pHash dupe of an existing
+record, we append a new provenance row to the existing record rather than
+dropping the metadata.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Integer, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class ImageProvenance(Base):
+    __tablename__ = "image_provenance"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    image_record_id: Mapped[int] = mapped_column(
+        ForeignKey("image_record.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    post_id: Mapped[int] = mapped_column(
+        ForeignKey("post.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    source_id: Mapped[int] = mapped_column(
+        ForeignKey("source.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    captured_metadata: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    captured_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )

backend/app/models/image_record.py

@@ -0,0 +1,71 @@
+"""ImageRecord — the gallery's primary entity, ported from ImageRepo.
+
+ML fields and thumbnails are declared now (in FC-1) so FC-2 can populate them
+without a schema migration. The SigLIP embedding column uses pgvector's Vector
+type — pgvector extension is enabled in the initial migration.
+"""
+
+from datetime import datetime
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import (
+    JSON,
+    BigInteger,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    func,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+ORIGIN_CHOICES = ("downloaded", "imported_filesystem", "uploaded")
+
+
+class ImageRecord(Base):
+    __tablename__ = "image_record"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+
+    # On-disk identity
+    path: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
+    sha256: Mapped[str] = mapped_column(String(64), nullable=False, unique=True, index=True)
+    phash: Mapped[str | None] = mapped_column(String(32), nullable=True, index=True)
+    size_bytes: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    mime: Mapped[str] = mapped_column(String(64), nullable=False)
+    width: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    height: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # Thumbnail (populated by FC-2)
+    thumbnail_path: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # Origin / provenance pointers
+    origin: Mapped[str] = mapped_column(Enum(*ORIGIN_CHOICES, name="origin_enum"), nullable=False)
+    primary_post_id: Mapped[int | None] = mapped_column(
+        ForeignKey("post.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+
+    # ML fields (populated by FC-2's ml-worker)
+    wd14_predictions: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    wd14_model_version: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # 1152 = SigLIP-so400m embedding dim. Swapping models in FC-2 may require
+    # a column-width migration.
+    siglip_embedding: Mapped[list[float] | None] = mapped_column(Vector(1152), nullable=True)
+    siglip_model_version: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
+    # Centroid score cache (populated post-tagging)
+    centroid_scores: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )

backend/app/models/post.py

@@ -0,0 +1,33 @@
+"""Post — provenance anchor for content downloaded from a Source.
+
+A Post is one creator post; it may contain many images/videos.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Integer, String, Text, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class Post(Base):
+    __tablename__ = "post"
+    __table_args__ = (
+        UniqueConstraint("source_id", "external_post_id", name="uq_post_source_external_id"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    source_id: Mapped[int] = mapped_column(
+        ForeignKey("source.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    external_post_id: Mapped[str] = mapped_column(String(128), nullable=False)
+    post_url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    post_title: Mapped[str | None] = mapped_column(Text, nullable=True)
+    post_date: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    raw_metadata: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+
+    downloaded_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )

backend/app/models/source.py

@@ -0,0 +1,31 @@
+"""Source — a platform-specific URL owned by an Artist (e.g., a Patreon URL).
+
+Multiple sources per artist support creators with cross-platform presence.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .base import Base
+
+
+class Source(Base):
+    __tablename__ = "source"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    artist_id: Mapped[int] = mapped_column(
+        ForeignKey("artist.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    platform: Mapped[str] = mapped_column(String(64), nullable=False)
+    url: Mapped[str] = mapped_column(Text, nullable=False)
+    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+
+    config_overrides: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+
+    last_checked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    check_interval_override: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    artist = relationship("Artist", back_populates="sources")

backend/app/models/tag.py

@@ -0,0 +1,40 @@
+"""Tag + ImageTag association.
+
+Tags use namespaced strings (``artist:Name``, ``character:Name``,
+``rating:safe``, etc.). Artist tags are kept in sync with the Artist table —
+the sync trigger lands in FC-2.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Table, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .base import Base
+
+image_tag = Table(
+    "image_tag",
+    Base.metadata,
+    Column(
+        "image_record_id",
+        ForeignKey("image_record.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column("tag_id", ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True),
+    Column("source", String(32), nullable=False, default="manual"),  # manual|auto|ml
+    Column("created_at", DateTime(timezone=True), nullable=False, server_default=func.now()),
+)
+
+
+class Tag(Base):
+    __tablename__ = "tag"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True, index=True)
+    namespace: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+
+    images = relationship("ImageRecord", secondary=image_tag, backref="tags")