Add database schema with SQLAlchemy async + Alembic migrations

Set up PostgreSQL database layer with async SQLAlchemy 2.0 and asyncpg driver.
Implements 6 core tables (games, routes, pokemon, route_encounters, nuzlocke_runs,
encounters) with foreign keys, indexes, and an initial Alembic migration.

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

backend/src/app/models/__init__.py

@@ -0,0 +1,15 @@
+from app.models.encounter import Encounter
+from app.models.game import Game
+from app.models.nuzlocke_run import NuzlockeRun
+from app.models.pokemon import Pokemon
+from app.models.route import Route
+from app.models.route_encounter import RouteEncounter
+
+__all__ = [
+    "Encounter",
+    "Game",
+    "NuzlockeRun",
+    "Pokemon",
+    "Route",
+    "RouteEncounter",
+]

backend/src/app/models/encounter.py

@@ -0,0 +1,29 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, SmallInteger, String, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Encounter(Base):
+    __tablename__ = "encounters"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    run_id: Mapped[int] = mapped_column(ForeignKey("nuzlocke_runs.id"), index=True)
+    route_id: Mapped[int] = mapped_column(ForeignKey("routes.id"), index=True)
+    pokemon_id: Mapped[int] = mapped_column(ForeignKey("pokemon.id"), index=True)
+    nickname: Mapped[str | None] = mapped_column(String(50))
+    status: Mapped[str] = mapped_column(String(20))  # caught, fainted, missed
+    catch_level: Mapped[int | None] = mapped_column(SmallInteger)
+    faint_level: Mapped[int | None] = mapped_column(SmallInteger)
+    caught_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+    run: Mapped["NuzlockeRun"] = relationship(back_populates="encounters")
+    route: Mapped["Route"] = relationship(back_populates="encounters")
+    pokemon: Mapped["Pokemon"] = relationship(back_populates="encounters")
+
+    def __repr__(self) -> str:
+        return f"<Encounter(id={self.id}, pokemon_id={self.pokemon_id}, status='{self.status}')>"

backend/src/app/models/game.py

@@ -0,0 +1,22 @@
+from sqlalchemy import SmallInteger, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Game(Base):
+    __tablename__ = "games"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+    slug: Mapped[str] = mapped_column(String(100), unique=True)
+    generation: Mapped[int] = mapped_column(SmallInteger)
+    region: Mapped[str] = mapped_column(String(50))
+    box_art_url: Mapped[str | None] = mapped_column(String(500))
+    release_year: Mapped[int | None] = mapped_column(SmallInteger)
+
+    routes: Mapped[list["Route"]] = relationship(back_populates="game")
+    runs: Mapped[list["NuzlockeRun"]] = relationship(back_populates="game")
+
+    def __repr__(self) -> str:
+        return f"<Game(id={self.id}, name='{self.name}')>"

backend/src/app/models/nuzlocke_run.py

@@ -0,0 +1,27 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class NuzlockeRun(Base):
+    __tablename__ = "nuzlocke_runs"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    game_id: Mapped[int] = mapped_column(ForeignKey("games.id"), index=True)
+    name: Mapped[str] = mapped_column(String(100))
+    status: Mapped[str] = mapped_column(String(20), index=True)  # active, completed, failed
+    rules: Mapped[dict] = mapped_column(JSONB, default=dict)
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    game: Mapped["Game"] = relationship(back_populates="runs")
+    encounters: Mapped[list["Encounter"]] = relationship(back_populates="run")
+
+    def __repr__(self) -> str:
+        return f"<NuzlockeRun(id={self.id}, name='{self.name}', status='{self.status}')>"

backend/src/app/models/pokemon.py

@@ -0,0 +1,23 @@
+from sqlalchemy import SmallInteger, String
+from sqlalchemy.dialects.postgresql import ARRAY
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Pokemon(Base):
+    __tablename__ = "pokemon"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    national_dex: Mapped[int] = mapped_column(SmallInteger, unique=True)
+    name: Mapped[str] = mapped_column(String(50))
+    types: Mapped[list[str]] = mapped_column(ARRAY(String(20)))
+    sprite_url: Mapped[str | None] = mapped_column(String(500))
+
+    route_encounters: Mapped[list["RouteEncounter"]] = relationship(
+        back_populates="pokemon"
+    )
+    encounters: Mapped[list["Encounter"]] = relationship(back_populates="pokemon")
+
+    def __repr__(self) -> str:
+        return f"<Pokemon(id={self.id}, name='{self.name}', dex={self.national_dex})>"

backend/src/app/models/route.py

@@ -0,0 +1,22 @@
+from sqlalchemy import ForeignKey, SmallInteger, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Route(Base):
+    __tablename__ = "routes"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+    game_id: Mapped[int] = mapped_column(ForeignKey("games.id"), index=True)
+    order: Mapped[int] = mapped_column(SmallInteger)
+
+    game: Mapped["Game"] = relationship(back_populates="routes")
+    route_encounters: Mapped[list["RouteEncounter"]] = relationship(
+        back_populates="route"
+    )
+    encounters: Mapped[list["Encounter"]] = relationship(back_populates="route")
+
+    def __repr__(self) -> str:
+        return f"<Route(id={self.id}, name='{self.name}')>"

backend/src/app/models/route_encounter.py

@@ -0,0 +1,25 @@
+from sqlalchemy import ForeignKey, SmallInteger, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class RouteEncounter(Base):
+    __tablename__ = "route_encounters"
+    __table_args__ = (
+        UniqueConstraint(
+            "route_id", "pokemon_id", "encounter_method", name="uq_route_pokemon_method"
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    route_id: Mapped[int] = mapped_column(ForeignKey("routes.id"), index=True)
+    pokemon_id: Mapped[int] = mapped_column(ForeignKey("pokemon.id"), index=True)
+    encounter_method: Mapped[str] = mapped_column(String(30))
+    encounter_rate: Mapped[int] = mapped_column(SmallInteger)
+
+    route: Mapped["Route"] = relationship(back_populates="route_encounters")
+    pokemon: Mapped["Pokemon"] = relationship(back_populates="route_encounters")
+
+    def __repr__(self) -> str:
+        return f"<RouteEncounter(route_id={self.route_id}, pokemon_id={self.pokemon_id}, method='{self.encounter_method}')>"