feat: Add pagination support for image gallery API

backend/app/database/images.py

@@ -1,6 +1,7 @@
 # Standard library imports
 import sqlite3
 from typing import Any, List, Mapping, Tuple, TypedDict, Union
+import math
 
 # App-specific imports
 from app.config.settings import (
@@ -39,6 +40,24 @@ class UntaggedImageRecord(TypedDict):
     metadata: Mapping[str, Any]
 
 
+class PaginationInfo(TypedDict):
+    """Represents pagination metadata"""
+
+    page: int
+    limit: int
+    total_count: int
+    total_pages: int
+    has_next: bool
+    has_previous: bool
+
+
+class PaginatedImagesResult(TypedDict):
+    """Represents paginated images result"""
+
+    images: List[dict]
+    pagination: PaginationInfo
+
+
 ImageClassPair = Tuple[ImageId, ClassId]
 
 
@@ -120,22 +139,39 @@ def db_bulk_insert_images(image_records: List[ImageRecord]) -> bool:
         conn.close()
 
 
-def db_get_all_images(tagged: Union[bool, None] = None) -> List[dict]:
+def db_get_all_images(
+    tagged: Union[bool, None] = None,
+    page: Union[int, None] = None,
+    limit: Union[int, None] = None,
+) -> Union[List[dict], PaginatedImagesResult]:
     """
     Get all images from the database with their tags.
 
     Args:
         tagged: Optional filter for tagged status. If None, returns all images.
                 If True, returns only tagged images. If False, returns only untagged images.
+        page: Optional page number (1-indexed). If None, returns all images without pagination.
+        limit: Optional number of images per page. If None, returns all images without pagination.
 
     Returns:
-        List of dictionaries containing all image data including tags
+        If page and limit are provided: PaginatedImagesResult with images and pagination info
+        Otherwise: List of dictionaries containing all image data including tags
     """
     conn = _connect()
     cursor = conn.cursor()
 
     try:
-        # Build the query with optional WHERE clause
+        # First, get total count for pagination
+        count_query = "SELECT COUNT(DISTINCT i.id) FROM images i"
+        count_params = []
+        if tagged is not None:
+            count_query += " WHERE i.isTagged = ?"
+            count_params.append(tagged)
+
+        cursor.execute(count_query, count_params)
+        total_count = cursor.fetchone()[0]
+
+        # Build the main query with optional WHERE clause
         query = """
             SELECT 
                 i.id, 
@@ -205,10 +241,43 @@ def db_get_all_images(tagged: Union[bool, None] = None) -> List[dict]:
         # Sort by path
         images.sort(key=lambda x: x["path"])
 
+        # Apply pagination if page and limit are provided
+        if page is not None and limit is not None:
+            # Calculate pagination values
+            total_pages = math.ceil(total_count / limit) if limit > 0 else 0
+            offset = (page - 1) * limit
+            paginated_images = images[offset : offset + limit]
+
+            pagination_info: PaginationInfo = {
+                "page": page,
+                "limit": limit,
+                "total_count": total_count,
+                "total_pages": total_pages,
+                "has_next": page < total_pages,
+                "has_previous": page > 1,
+            }
+
+            return {
+                "images": paginated_images,
+                "pagination": pagination_info,
+            }
+
         return images
 
     except Exception as e:
         logger.error(f"Error getting all images: {e}")
+        if page is not None and limit is not None:
+            return {
+                "images": [],
+                "pagination": {
+                    "page": page,
+                    "limit": limit,
+                    "total_count": 0,
+                    "total_pages": 0,
+                    "has_next": False,
+                    "has_previous": False,
+                },
+            }
         return []
     finally:
         conn.close()

backend/app/routes/images.py

@@ -37,45 +37,100 @@ class ImageData(BaseModel):
     tags: Optional[List[str]] = None
 
 
+class PaginationInfo(BaseModel):
+    page: int
+    limit: int
+    total_count: int
+    total_pages: int
+    has_next: bool
+    has_previous: bool
+
+
 class GetAllImagesResponse(BaseModel):
     success: bool
     message: str
     data: List[ImageData]
 
 
+class PaginatedImagesResponse(BaseModel):
+    success: bool
+    message: str
+    data: List[ImageData]
+    pagination: PaginationInfo
+
+
 @router.get(
     "/",
-    response_model=GetAllImagesResponse,
+    response_model=None,
     responses={500: {"model": ErrorResponse}},
 )
 def get_all_images(
-    tagged: Optional[bool] = Query(None, description="Filter images by tagged status")
+    tagged: Optional[bool] = Query(None, description="Filter images by tagged status"),
+    page: Optional[int] = Query(None, ge=1, description="Page number (1-indexed)"),
+    limit: Optional[int] = Query(
+        None, ge=1, le=100, description="Number of images per page (max 100)"
+    ),
 ):
-    """Get all images from the database."""
+    """
+    Get all images from the database.
+
+    - If `page` and `limit` are provided, returns paginated results.
+    - If `page` and `limit` are not provided, returns all images (backward compatible).
+    """
     try:
-        # Get all images with tags from database (single query with optional filter)
-        images = db_get_all_images(tagged=tagged)
-
-        # Convert to response format
-        image_data = [
-            ImageData(
-                id=image["id"],
-                path=image["path"],
-                folder_id=image["folder_id"],
-                thumbnailPath=image["thumbnailPath"],
-                metadata=image_util_parse_metadata(image["metadata"]),
-                isTagged=image["isTagged"],
-                isFavourite=image.get("isFavourite", False),
-                tags=image["tags"],
+        # Get images with optional pagination
+        result = db_get_all_images(tagged=tagged, page=page, limit=limit)
+
+        # Check if paginated result
+        if page is not None and limit is not None:
+            images = result["images"]
+            pagination = result["pagination"]
+
+            # Convert to response format
+            image_data = [
+                ImageData(
+                    id=image["id"],
+                    path=image["path"],
+                    folder_id=image["folder_id"],
+                    thumbnailPath=image["thumbnailPath"],
+                    metadata=image_util_parse_metadata(image["metadata"]),
+                    isTagged=image["isTagged"],
+                    isFavourite=image.get("isFavourite", False),
+                    tags=image["tags"],
+                )
+                for image in images
+            ]
+
+            return PaginatedImagesResponse(
+                success=True,
+                message=f"Successfully retrieved {len(image_data)} images (page {pagination['page']} of {pagination['total_pages']})",
+                data=image_data,
+                pagination=PaginationInfo(**pagination),
+            )
+        else:
+            # Non-paginated response (backward compatible)
+            images = result
+
+            # Convert to response format
+            image_data = [
+                ImageData(
+                    id=image["id"],
+                    path=image["path"],
+                    folder_id=image["folder_id"],
+                    thumbnailPath=image["thumbnailPath"],
+                    metadata=image_util_parse_metadata(image["metadata"]),
+                    isTagged=image["isTagged"],
+                    isFavourite=image.get("isFavourite", False),
+                    tags=image["tags"],
+                )
+                for image in images
+            ]
+
+            return GetAllImagesResponse(
+                success=True,
+                message=f"Successfully retrieved {len(image_data)} images",
+                data=image_data,
             )
-            for image in images
-        ]
-
-        return GetAllImagesResponse(
-            success=True,
-            message=f"Successfully retrieved {len(image_data)} images",
-            data=image_data,
-        )
 
     except Exception as e:
         raise HTTPException(

frontend/src/api/api-functions/images.ts

@@ -1,12 +1,68 @@
 import { imagesEndpoints } from '../apiEndpoints';
 import { apiClient } from '../axiosConfig';
-import { APIResponse } from '@/types/API';
+import { APIResponse, PaginatedAPIResponse } from '@/types/API';
+import { Image } from '@/types/Media';
 
+export interface FetchImagesParams {
+  tagged?: boolean;
+  page?: number;
+  limit?: number;
+}
+
+/**
+ * Fetch images from the API with optional pagination.
+ *
+ * @param params - Optional parameters for filtering and pagination
+ * @param params.tagged - Filter by tagged status
+ * @param params.page - Page number (1-indexed)
+ * @param params.limit - Number of images per page
+ * @returns APIResponse or PaginatedAPIResponse depending on whether pagination params are provided
+ */
 export const fetchAllImages = async (
+  params?: FetchImagesParams | boolean,
+): Promise<APIResponse | PaginatedAPIResponse<Image>> => {
+  // Handle backward compatibility: if params is a boolean, treat it as tagged filter
+  const queryParams: Record<string, unknown> = {};
+
+  if (typeof params === 'boolean') {
+    queryParams.tagged = params;
+  } else if (params) {
+    if (params.tagged !== undefined) {
+      queryParams.tagged = params.tagged;
+    }
+    if (params.page !== undefined) {
+      queryParams.page = params.page;
+    }
+    if (params.limit !== undefined) {
+      queryParams.limit = params.limit;
+    }
+  }
+
+  const response = await apiClient.get<
+    APIResponse | PaginatedAPIResponse<Image>
+  >(imagesEndpoints.getAllImages, { params: queryParams });
+  return response.data;
+};
+
+/**
+ * Fetch paginated images from the API.
+ *
+ * @param page - Page number (1-indexed)
+ * @param limit - Number of images per page (default: 50)
+ * @param tagged - Optional filter by tagged status
+ * @returns PaginatedAPIResponse with images and pagination info
+ */
+export const fetchPaginatedImages = async (
+  page: number,
+  limit: number = 50,
   tagged?: boolean,
-): Promise<APIResponse> => {
-  const params = tagged !== undefined ? { tagged } : {};
-  const response = await apiClient.get<APIResponse>(
+): Promise<PaginatedAPIResponse<Image>> => {
+  const params: Record<string, unknown> = { page, limit };
+  if (tagged !== undefined) {
+    params.tagged = tagged;
+  }
+
+  const response = await apiClient.get<PaginatedAPIResponse<Image>>(
     imagesEndpoints.getAllImages,
     { params },
   );