The full‑stack template
your AI agent can't break

class Item(TimestampMixin, Base):
    __tablename__ = "item"
    __table_args__ = (Index("item_sku_idx", "sku"),)

    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    user_id: Mapped[uuid.UUID] = mapped_column(
        ForeignKey("user.id", ondelete="CASCADE"), index=True
    )
    name: Mapped[str] = mapped_column(String(255))
    description: Mapped[str | None] = mapped_column(Text, default=None)
    quantity: Mapped[int] = mapped_column(default=0)

"""Item repository - database access layer."""

from app.modules.items.models import Item
from app.repositories.sql_repository import SQLAlchemyRepository


class ItemRepository(SQLAlchemyRepository[Item]):
    """Repository for Item entity."""

    model = Item

class ItemFilter(ModelFilter):
    """Filter for Item queries.

    Usage in requests:
        ?search=keyword          (name or description, case-insensitive)
        ?name__ilike=%pattern%   (name only, case-insensitive)
        ?order_by=-created_at    (comma-separated; prefix "-" for descending)
    """

    order_by: list[str] = ["created_at"]
    name__ilike: str | None = None
    search: str | None = None

    class Constants(ModelFilter.Constants):
        model = Item
        search_model_fields = ["name", "description"]

export function useItems(params?: ItemsParams, enabled = true) {
  return useQuery({
    queryKey: queryKeys.items.list(params),
    queryFn: () => api.get<ItemsResponse>(buildItemsListUrl(params)),
    enabled,
    // Keep showing the current page while the next page or search result loads
    placeholderData: keepPreviousData,
  })
}

export function useCreateItem() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (data: CreateItemData) => api.post<Item>(API.ITEMS.CREATE, data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: queryKeys.items.all })
    },
  })
}