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,45 @@
+"""Generalized external identifier system.
+
+Links an Aurora entity (any type) to its identifier in an external provider
+(TMDb, IMDb, TVDb, Wikidata, ...). External IDs are references, never
+primary keys — see app/core/ids.py and docs/architecture.md.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+from app.models.provider import Provider
+
+
+class ExternalID(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "external_ids"
+    __table_args__ = (
+        # A provider's ID for a given entity type must be unique (one Aurora
+        # entity per provider-native ID).
+        UniqueConstraint(
+            "provider_id", "entity_type", "external_id", name="uq_external_id_source"
+        ),
+        # An Aurora entity has at most one mapping per provider.
+        UniqueConstraint(
+            "entity_type", "entity_id", "provider_id", name="uq_external_id_entity_provider"
+        ),
+    )
+
+    entity_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    entity_id: Mapped[uuid.UUID] = mapped_column(nullable=False)
+
+    provider_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("providers.id", ondelete="CASCADE"), nullable=False
+    )
+    external_id: Mapped[str] = mapped_column(String(200), nullable=False)
+    url: Mapped[str | None] = mapped_column(String(500), nullable=True)
+
+    provider: Mapped[Provider] = relationship()
+
+
+__all__ = ["ExternalID"]