Add GET /genres directory endpoint

GET /movies and GET /series accept a genre filter (an Aurora genre id),
but nothing exposed what those ids actually are -- genres otherwise
only ever appear embedded in a movie/series response's own genres
list. This is the resolve-by-name-first-then-filter step the frontend
needs to build real genre browsing.

No filter, no sort_by -- always alphabetical by name, same pattern as
collections/companies (genres have no categorical field or popularity/
date to sort by). page_size defaults to 50 (max 200) rather than the
20/50 used elsewhere, since genres are a small, fixed reference set
(TMDb has ~19-20 total) a client typically wants in full for a filter
dropdown, not paginated like a catalog of millions of movies.

Also fixed two stale "behind Traefik" mentions in app/main.py's module
docstring while touching this file, left over from the earlier
cPanel/host-webserver deployment change.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

app/api/v1/genres.py

@@ -0,0 +1,28 @@
+"""Genre endpoints (section 17: additive) -- a directory for the `genre`
+filter GET /movies and GET /series already accept, which takes an Aurora
+genre id with no prior way to discover what those ids are."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.core.security import enforce_rate_limit
+from app.schemas.common import GenreListOut
+from app.services import genre_service
+
+router = APIRouter(prefix="/genres", tags=["genres"], dependencies=[Depends(enforce_rate_limit)])
+
+
+@router.get("", response_model=GenreListOut)
+async def list_genres(
+    page: int = Query(1, ge=1),
+    # Genres are a small, fixed reference set (TMDb has ~19-20 total) --
+    # default/max page_size sized so a client can fetch the whole
+    # directory in one call for a filter dropdown, unlike the huge
+    # catalogs GET /movies etc. paginate through.
+    page_size: int = Query(50, ge=1, le=200),
+    session: AsyncSession = Depends(get_db),
+) -> GenreListOut:
+    return await genre_service.list_genres(session, page=page, page_size=page_size)

app/main.py

@@ -1,7 +1,8 @@
 """Aurora Core FastAPI application factory.
 
 Stateless by design (section 1): nothing here holds request-scoped state in
-process memory, so any number of API replicas can run behind Traefik.
+process memory, so any number of API replicas can run behind a reverse
+proxy without sticky sessions.
 """
 
 from __future__ import annotations
@@ -25,6 +26,7 @@ from app.api.v1 import (
     collections,
     companies,
     episodes,
+    genres,
     health,
     movies,
     people,
@@ -174,4 +176,5 @@ app.include_router(episodes.router, prefix=API_V1_PREFIX)
 app.include_router(people.router, prefix=API_V1_PREFIX)
 app.include_router(collections.router, prefix=API_V1_PREFIX)
 app.include_router(companies.router, prefix=API_V1_PREFIX)
+app.include_router(genres.router, prefix=API_V1_PREFIX)
 app.include_router(admin.router, prefix=API_V1_PREFIX)

app/repositories/genre_repository.py

@@ -0,0 +1,34 @@
+"""Data access for Genre."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.genre import Genre
+
+
+async def get_genre_by_id(session: AsyncSession, genre_id: uuid.UUID) -> Genre | None:
+    result = await session.execute(select(Genre).where(Genre.id == genre_id))
+    return result.scalar_one_or_none()
+
+
+async def list_genres(session: AsyncSession, *, limit: int, offset: int) -> tuple[list[Genre], int]:
+    """Browse genres -- see movie_repository.list_movies for the
+    window-function total-count approach this mirrors. Genres have no
+    categorical field to filter by and no popularity/date to sort by, so
+    this always orders alphabetically by name (with an id tiebreak for
+    stable pagination)."""
+
+    stmt = (
+        select(Genre, func.count().over().label("total_count"))
+        .order_by(Genre.name.asc(), Genre.id.asc())
+        .limit(limit)
+        .offset(offset)
+    )
+    rows = (await session.execute(stmt)).all()
+    if not rows:
+        return [], 0
+    return [row[0] for row in rows], rows[0].total_count

app/schemas/common.py

@@ -22,6 +22,14 @@ class GenreOut(ORMModel):
     name: str
 
 
+class GenreListOut(BaseModel):
+    page: int
+    page_size: int
+    total_results: int
+    total_pages: int
+    results: list[GenreOut] = []
+
+
 class KeywordOut(ORMModel):
     id: str
     name: str

app/services/genre_service.py

@@ -0,0 +1,27 @@
+"""Assembles Genre API responses from repository data.
+
+Genres have no detail page of their own -- they only ever appear embedded
+in movie/series responses (see app/services/common.py) and as entries in
+this directory listing, which exists so a client can resolve the Aurora
+genre ids that GET /movies and GET /series accept as a filter without
+having to have already seen a title in that genre first."""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.ids import aurora_id
+from app.repositories import genre_repository
+from app.schemas.common import GenreListOut, GenreOut
+
+
+async def list_genres(session: AsyncSession, *, page: int, page_size: int) -> GenreListOut:
+    genres, total = await genre_repository.list_genres(
+        session, limit=page_size, offset=(page - 1) * page_size
+    )
+    results = [GenreOut(id=aurora_id("genre", str(g.id)), name=g.name) for g in genres]
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return GenreListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )