Initial Aurora Core 0.1 implementation

Production-grade media metadata backend per docs/aurora-core-spec.md: Aurora-owned UUIDv7 identity system, normalized movie/TV/people/credits schema, provider abstraction with a TMDb adapter, an idempotent async ingestion pipeline (normalize -> match -> upsert -> provenance), a Postgres FTS/trigram search layer, a stateless FastAPI v1 API with Redis caching/rate-limiting, arq workers, dev/prod Docker Compose topologies, unit + integration + load tests, CI, and architecture/ database/API/ERD documentation. Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-09-04 17:34:03 -05:00
commit c20df1c503
111 changed files with 10041 additions and 0 deletions
@@ -0,0 +1,118 @@
+"""Television model: Series -> Seasons -> Episodes (section 5)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import date
+
+from sqlalchemy import Date, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+from app.models.enums import SeriesStatus
+
+
+class Series(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "series"
+
+    title: Mapped[str] = mapped_column(String(500), nullable=False, index=True)
+    original_title: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    sort_title: Mapped[str] = mapped_column(String(500), nullable=False, index=True)
+
+    overview: Mapped[str | None] = mapped_column(Text, nullable=True)
+    tagline: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    status: Mapped[SeriesStatus] = mapped_column(
+        default=SeriesStatus.RETURNING_SERIES, nullable=False
+    )
+    original_language_code: Mapped[str | None] = mapped_column(
+        ForeignKey("languages.code"), nullable=True
+    )
+    first_air_date: Mapped[date | None] = mapped_column(Date, nullable=True, index=True)
+    last_air_date: Mapped[date | None] = mapped_column(Date, nullable=True)
+
+    number_of_seasons: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    number_of_episodes: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    popularity: Mapped[float | None] = mapped_column(nullable=True)
+    vote_average: Mapped[float | None] = mapped_column(nullable=True)
+    vote_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    source_provider_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("providers.id", ondelete="SET NULL"), nullable=True
+    )
+
+
+class SeriesAlternateTitle(Base, UUIDPrimaryKeyMixin):
+    __tablename__ = "series_alternate_titles"
+
+    series_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("series.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    title: Mapped[str] = mapped_column(String(500), nullable=False)
+    country_code: Mapped[str | None] = mapped_column(ForeignKey("countries.code"), nullable=True)
+    type: Mapped[str | None] = mapped_column(String(50), nullable=True)
+
+
+class SeriesSpokenLanguage(Base):
+    __tablename__ = "series_spoken_languages"
+
+    series_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("series.id", ondelete="CASCADE"), primary_key=True
+    )
+    language_code: Mapped[str] = mapped_column(ForeignKey("languages.code"), primary_key=True)
+
+
+class SeriesProductionCountry(Base):
+    __tablename__ = "series_production_countries"
+
+    series_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("series.id", ondelete="CASCADE"), primary_key=True
+    )
+    country_code: Mapped[str] = mapped_column(ForeignKey("countries.code"), primary_key=True)
+
+
+class Season(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "seasons"
+    __table_args__ = (UniqueConstraint("series_id", "season_number", name="uq_season_number"),)
+
+    series_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("series.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    season_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    title: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    overview: Mapped[str | None] = mapped_column(Text, nullable=True)
+    air_date: Mapped[date | None] = mapped_column(Date, nullable=True)
+    episode_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+
+class Episode(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "episodes"
+    __table_args__ = (
+        UniqueConstraint("season_id", "episode_number", name="uq_episode_number"),
+    )
+
+    season_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("seasons.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    # Denormalized for direct filtering/joins without hopping through seasons.
+    series_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("series.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    season_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    episode_number: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    title: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    overview: Mapped[str | None] = mapped_column(Text, nullable=True)
+    air_date: Mapped[date | None] = mapped_column(Date, nullable=True)
+    runtime_minutes: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+
+__all__ = [
+    "Series",
+    "SeriesAlternateTitle",
+    "SeriesSpokenLanguage",
+    "SeriesProductionCountry",
+    "Season",
+    "Episode",
+]