feat(services): replace RuntimeError with HTTPException in helper functions

refactor(search): extract search helpers into separate module for maintainability

feat(performance): add performance monitoring utilities and API endpoints

feat(models): add optimized projections for database queries

feat(repository): add query performance monitoring to db operations

feat(utils): add constants file for centralized configuration

app/api/performance.py

@@ -0,0 +1,63 @@
+"""
+Performance monitoring API endpoints.
+"""
+from fastapi import APIRouter, HTTPException
+from typing import Dict, Any
+import logging
+
+from app.utils.performance_monitor import get_performance_report
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+@router.get("/performance/metrics", response_model=Dict[str, Any])
+async def get_performance_metrics():
+    """
+    Get current performance metrics and recommendations.
+    """
+    try:
+        logger.info("Fetching performance metrics")
+        
+        report = get_performance_report()
+        
+        logger.info(f"Performance report generated: {report['metrics']['total_queries']} queries tracked")
+        return {
+            "status": "success",
+            "data": report
+        }
+        
+    except Exception as e:
+        logger.error(f"Error fetching performance metrics: {e}")
+        raise HTTPException(
+            status_code=500, 
+            detail=f"Failed to fetch performance metrics: {str(e)}"
+        )
+
+@router.post("/performance/reset")
+async def reset_performance_metrics():
+    """
+    Reset performance metrics (useful for testing and monitoring).
+    """
+    try:
+        logger.info("Resetting performance metrics")
+        
+        from app.utils.performance_monitor import performance_metrics
+        
+        # Reset metrics
+        performance_metrics.query_times = []
+        performance_metrics.slow_queries = []
+        performance_metrics.total_queries = 0
+        performance_metrics.total_time = 0.0
+        
+        logger.info("Performance metrics reset successfully")
+        return {
+            "status": "success",
+            "message": "Performance metrics reset successfully"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error resetting performance metrics: {e}")
+        raise HTTPException(
+            status_code=500, 
+            detail=f"Failed to reset performance metrics: {str(e)}"
+        )

app/models/optimized_projections.py

@@ -0,0 +1,237 @@
+"""
+Optimized projection fields for different use cases to reduce data transfer and improve performance.
+"""
+from datetime import datetime
+
+CURRENT_DATE = datetime.now()
+
+# Minimal fields for list views and search results
+MINIMAL_FIELDS = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "average_rating": "$average_rating.value",
+    "city": 1,
+    "merchant_category": 1,
+    "profile_picture": {"$arrayElemAt": ["$display_picture", 0]},
+}
+
+# Essential fields for card views
+CARD_FIELDS = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "business_url": 1,
+    "description": 1,
+    "profile_picture": {"$arrayElemAt": ["$display_picture", 0]},
+    "average_rating": "$average_rating.value",
+    "city": 1,
+    "merchant_category": 1,
+    "merchant_subcategory": 1,
+    "address.formatted_address": 1,
+    "promotions": 1,
+}
+
+# Optimized years_in_business calculation using $dateDiff (MongoDB 5.0+)
+YEARS_IN_BUSINESS_OPTIMIZED = {
+    "$let": {
+        "vars": {
+            "years": {"$dateDiff": {"startDate": "$available_from", "endDate": "$$NOW", "unit": "year"}},
+            "months": {"$dateDiff": {"startDate": "$available_from", "endDate": "$$NOW", "unit": "month"}},
+            "days": {"$dateDiff": {"startDate": "$available_from", "endDate": "$$NOW", "unit": "day"}}
+        },
+        "in": {
+            "$switch": {
+                "branches": [
+                    {
+                        "case": {"$gte": ["$$years", 1]},
+                        "then": {"$concat": [{"$toString": "$$years"}, " years in business"]}
+                    },
+                    {
+                        "case": {"$gte": ["$$months", 1]},
+                        "then": {"$concat": [{"$toString": "$$months"}, " months in business"]}
+                    }
+                ],
+                "default": {"$concat": [{"$toString": "$$days"}, " days in business"]}
+            }
+        }
+    }
+}
+
+# Optimized common fields with improved years_in_business calculation
+COMMON_FIELDS_OPTIMIZED = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "business_url": 1,
+    "description": 1,
+    "display_picture": 1,
+    "profile_picture": {"$arrayElemAt": ["$display_picture", 0]},
+    "average_rating": 1,
+    "city": 1,
+    "country": 1,
+    "merchant_category": 1,
+    "merchant_subcategory": 1,
+    "address": 1,
+    "business_hour": 1,
+    "promotions": 1,
+    "trending": 1,
+    "amenities": 1,
+    "cancellation_policy": 1,
+    "share_description": 1,
+    "years_in_business": YEARS_IN_BUSINESS_OPTIMIZED
+}
+
+# Fields for detailed merchant view
+DETAILED_FIELDS = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "business_url": 1,
+    "description": 1,
+    "display_picture": 1,
+    "profile_picture": {"$arrayElemAt": ["$display_picture", 0]},
+    "average_rating": 1,
+    "city": 1,
+    "country": 1,
+    "merchant_category": 1,
+    "merchant_subcategory": 1,
+    "address": 1,
+    "business_hour": 1,
+    "promotions": 1,
+    "trending": 1,
+    "amenities": 1,
+    "cancellation_policy": 1,
+    "share_description": 1,
+    "payment_modes": 1,
+    "contact_info": 1,
+    "social_media": 1,
+    "years_in_business": YEARS_IN_BUSINESS_OPTIMIZED
+}
+
+# Fields for recommended merchants (lightweight)
+RECOMMENDED_FIELDS_OPTIMIZED = {
+    "_id": 0,
+    "merchant_id": 1,
+    "address.formatted_address": 1,
+    "location_id": 1,
+    "business_name": 1,
+    "business_url": 1,
+    "description": 1,
+    "business_hour.weekdays": 1,  # Only weekdays for quick availability check
+    "promotions": 1,
+    "cancellation_policy": 1,
+    "amenities": 1,
+    "profile_picture": {"$arrayElemAt": ["$display_picture", 0]},
+    "average_rating": "$average_rating.value",
+    "share_description": 1,
+    "city": 1,
+    "country": 1,
+    "merchant_subcategory": 1,
+    "payment_modes": 1
+}
+
+# Fields for search results with geospatial data
+SEARCH_FIELDS_WITH_GEO = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "business_url": 1,
+    "description": 1,
+    "profile_picture": {"$arrayElemAt": ["$display_picture", 0]},
+    "average_rating": 1,
+    "city": 1,
+    "merchant_category": 1,
+    "merchant_subcategory": 1,
+    "address": 1,
+    "promotions": 1,
+    "distance": {
+        "$round": [
+            {
+                "$multiply": [
+                    {
+                        "$acos": {
+                            "$add": [
+                                {
+                                    "$multiply": [
+                                        {"$sin": {"$degreesToRadians": "$address.location.coordinates.1"}},
+                                        {"$sin": {"$degreesToRadians": "$$userLat"}}
+                                    ]
+                                },
+                                {
+                                    "$multiply": [
+                                        {"$cos": {"$degreesToRadians": "$address.location.coordinates.1"}},
+                                        {"$cos": {"$degreesToRadians": "$$userLat"}},
+                                        {"$cos": {"$degreesToRadians": {"$subtract": ["$address.location.coordinates.0", "$$userLng"]}}}
+                                    ]
+                                }
+                            ]
+                        }
+                    },
+                    6371000  # Earth's radius in meters
+                ]
+            },
+            0
+        ]
+    }
+}
+
+# Fields for catalogue and staff data (minimal for performance)
+CATALOGUE_MINIMAL_FIELDS = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "location_id": 1,
+    "catalogue": {
+        "$map": {
+            "input": {"$objectToArray": "$catalogue"},
+            "as": "cat",
+            "in": {
+                "category": "$$cat.k",
+                "services": {
+                    "$map": {
+                        "input": "$$cat.v",
+                        "as": "service",
+                        "in": {
+                            "service_id": "$$service.service_id",
+                            "service_name": "$$service.service_name",
+                            "price": {"$round": ["$$service.price", 2]},
+                            "currency": "$$service.currency",
+                            "duration": "$$service.duration",
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+STAFF_MINIMAL_FIELDS = {
+    "_id": 0,
+    "merchant_id": 1,
+    "business_name": 1,
+    "location_id": 1,
+    "staff": {
+        "$map": {
+            "input": "$staff",
+            "as": "s",
+            "in": {
+                "staff_id": "$$s.staff_id",
+                "name": "$$s.name",
+                "role": "$$s.role",
+                "rating": "$$s.rating",
+            }
+        }
+    }
+}
+
+# Performance monitoring fields
+PERFORMANCE_FIELDS = {
+    "_id": 0,
+    "merchant_id": 1,
+    "stats.total_bookings": 1,
+    "stats.response_time": 1,
+    "average_rating.total_reviews": 1,
+    "go_live_from": 1,
+    "last_updated": 1
+}

app/repositories/db_repository.py

@@ -5,6 +5,7 @@ from pymongo.errors import PyMongoError
 from bson import ObjectId
 import logging
 from bson.decimal128 import Decimal128
+from app.utils.performance_monitor import monitor_query_performance, log_pipeline_complexity
 
 logger = logging.getLogger(__name__)
 
@@ -37,11 +38,15 @@ def serialize_mongo_document(doc: Any) -> Any:
         return float(doc.to_decimal())  # Convert Decimal128 to float (or use str if preferred)
     return doc
 
+@monitor_query_performance
 async def execute_query(collection: str, pipeline: list) -> Any:
     """
     Execute MongoDB aggregation pipeline with error handling and serialization.
     """
     try:
+        # Log pipeline complexity for analysis
+        log_pipeline_complexity(pipeline, collection, "aggregation")
+        
         logger.info(f"Executing query on collection: {collection}")
         results = await db[collection].aggregate(pipeline).to_list(length=None)
         return serialize_mongo_document(results)
@@ -83,5 +88,5 @@ async def fetch_documents(
         }
     except PyMongoError as e:
         logger.error(f"MongoDB fetch error in collection '{collection}': {e}")
-        raise RuntimeError("Database fetch operation failed") from e    
+        raise RuntimeError("Database fetch operation failed") from e
 

app/services/helper.py

@@ -175,7 +175,7 @@ async def get_default_category_name() -> str:
     if result:
         return result[0]["name"]  # Return the category name
     else:
-        raise RuntimeError("No default category found")
+        raise HTTPException(status_code=404, detail="No default category found")
     
 async def fetch_business_categories_service(country: str = "in") -> Dict[str, Any]:
     """
@@ -213,7 +213,7 @@ async def fetch_business_categories_service(country: str = "in") -> Dict[str, An
 
     except Exception as e:
         logger.exception("Error in fetching business categories")
-        raise RuntimeError("Failed to fetch business categories") from e
+        raise HTTPException(status_code=500, detail="Failed to fetch business categories")
 
 
 async def fetch_filters_and_sort_service() -> Dict[str, List]:
@@ -363,6 +363,6 @@ async def fetch_live_at_service(country: str) -> List[Dict[str, Any]]:
 
     except Exception as e:
         logger.error(f"Failed to fetch live locations: {str(e)}")
-        raise RuntimeError(f"Failed to fetch live locations: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Failed to fetch live locations: {str(e)}")
 
 

app/services/merchant.py

@@ -7,11 +7,279 @@ from typing import Dict, List, Any
 from fastapi import HTTPException
 
 from app.repositories.db_repository import count_documents, execute_query, serialize_mongo_document
+from app.utils.performance_monitor import monitor_query_performance
 from app.models.merchant import SearchQuery, NewSearchQuery, COMMON_FIELDS, RECOMMENDED_FIELDS, MERCHANT_SCHEMA, LOCATION_TIMEZONE_MAPPING
 from .helper import get_default_category_name, process_free_text
- 
+from .search_helpers import (
+    _normalize_query_inputs, _build_base_criteria, _apply_free_text_filters,
+    _apply_availability_filters, _apply_amenity_filters, _apply_geo_filters,
+    _apply_additional_filters, _build_sort_criteria, _clean_criteria
+)
+from app.utils.constants import (
+    DEFAULT_RECENT_DAYS, DEFAULT_LIMIT, DEFAULT_SEARCH_RADIUS_METERS, 
+    EARTH_RADIUS_KM, EARTH_RADIUS_METERS, EARLY_OPENING_TIME, LATE_CLOSING_TIME,
+    ERROR_MERCHANT_NOT_FOUND, ERROR_BUSINESS_HOURS_NOT_FOUND, ERROR_BUSINESS_HOURS_UNAVAILABLE,
+    ERROR_FAILED_FETCH_MERCHANTS, ERROR_FAILED_FETCH_ADS, ERROR_FAILED_FETCH_SEARCH,
+    ERROR_FAILED_FETCH_DETAILS, ERROR_FAILED_FETCH_REVIEWS, ERROR_FAILED_FETCH_BUSINESS_HOURS,
+    HTTP_STATUS_NOT_FOUND, HTTP_STATUS_INTERNAL_ERROR, AVAILABILITY_NOW, AVAILABILITY_ALL,
+    AVAILABILITY_EARLY, AVAILABILITY_LATE
+)
+
 logger = logging.getLogger(__name__)
 
+# Import optimized projections
+from app.models.optimized_projections import (
+    MINIMAL_FIELDS,
+    CARD_FIELDS, 
+    COMMON_FIELDS_OPTIMIZED,
+    DETAILED_FIELDS,
+    RECOMMENDED_FIELDS_OPTIMIZED,
+    SEARCH_FIELDS_WITH_GEO,
+    CATALOGUE_MINIMAL_FIELDS,
+    STAFF_MINIMAL_FIELDS,
+    PERFORMANCE_FIELDS
+)
+from app.utils.performance_monitor import (
+    monitor_query_performance, 
+    performance_timer, 
+    log_pipeline_complexity,
+    get_performance_report
+)
+
+# Common aggregation stages
+def get_optimized_match_stage(criteria: Dict) -> Dict:
+    """
+    Returns an optimized $match stage with indexed fields first for better performance.
+    """
+    # Reorder criteria to put indexed fields first
+    indexed_fields = ["location_id", "merchant_category", "city", "go_live_from"]
+    optimized_criteria = {}
+    
+    # Add indexed fields first
+    for field in indexed_fields:
+        if field in criteria:
+            optimized_criteria[field] = criteria[field]
+    
+    # Add remaining fields
+    for field, value in criteria.items():
+        if field not in indexed_fields:
+            optimized_criteria[field] = value
+    
+    return {"$match": optimized_criteria}
+
+
+def get_go_live_from_normalized_stage() -> Dict:
+    """
+    Returns a reusable MongoDB aggregation stage for normalizing go_live_from field.
+    Handles both date and string types, with fallback to current time.
+    """
+    return {
+        "$addFields": {
+            "go_live_from_normalized": {
+                "$cond": {
+                    "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
+                    "then": "$go_live_from",
+                    "else": {
+                        "$cond": {
+                            "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
+                            "then": {
+                                "$dateFromString": {
+                                    "dateString": "$go_live_from",
+                                    "onError": {"$toDate": "$$NOW"}
+                                }
+                            },
+                            "else": {"$toDate": "$$NOW"}
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+
+def build_optimized_merchant_pipeline(
+    base_criteria: Dict, 
+    sort_criteria: Dict = None, 
+    limit: int = DEFAULT_LIMIT, 
+    offset: int = 0,
+    projection_fields: Dict = None,
+    include_distance: bool = False,
+    user_lat: float = None,
+    user_lng: float = None
+) -> List[Dict]:
+    """
+    Builds an optimized MongoDB aggregation pipeline for merchant queries.
+    Uses indexed fields first and context-specific projections.
+    """
+    pipeline = []
+    
+    # Use optimized match stage
+    pipeline.append(get_optimized_match_stage(base_criteria))
+    
+    # Add go_live_from normalization
+    pipeline.append(get_go_live_from_normalized_stage())
+    
+    # Add distance calculation if needed
+    if include_distance and user_lat and user_lng:
+        pipeline.append({
+            "$addFields": {
+                "distance": {
+                    "$round": [
+                        {
+                            "$multiply": [
+                                {
+                                    "$acos": {
+                                        "$add": [
+                                            {
+                                                "$multiply": [
+                                                    {"$sin": {"$degreesToRadians": "$address.location.coordinates.1"}},
+                                                    {"$sin": {"$degreesToRadians": user_lat}}
+                                                ]
+                                            },
+                                            {
+                                                "$multiply": [
+                                                    {"$cos": {"$degreesToRadians": "$address.location.coordinates.1"}},
+                                                    {"$cos": {"$degreesToRadians": user_lat}},
+                                                    {"$cos": {"$degreesToRadians": {"$subtract": ["$address.location.coordinates.0", user_lng]}}}
+                                                ]
+                                            }
+                                        ]
+                                    }
+                                },
+                                EARTH_RADIUS_METERS
+                            ]
+                        },
+                        0
+                    ]
+                }
+            }
+        })
+    
+    # Add sorting
+    if sort_criteria:
+        pipeline.append({"$sort": sort_criteria})
+    
+    # Add pagination
+    if offset > 0:
+        pipeline.append({"$skip": offset})
+    
+    pipeline.append({"$limit": limit})
+    
+    # Add projection (use optimized fields if not specified)
+    if projection_fields:
+        pipeline.append({"$project": projection_fields})
+    else:
+        pipeline.append({"$project": CARD_FIELDS})
+    
+    return pipeline
+
+
+def build_optimized_faceted_pipeline(
+    base_criteria: Dict,
+    recent_criteria: Dict,
+    limit: int = DEFAULT_LIMIT,
+    projection_fields: Dict = None
+) -> List[Dict]:
+    """
+    Builds an optimized faceted aggregation pipeline for recommended merchants.
+    Uses lightweight projections and optimized sorting.
+    """
+    if projection_fields is None:
+        projection_fields = RECOMMENDED_FIELDS_OPTIMIZED
+    
+    # Common pipeline stages for all facets
+    common_stages = [
+        get_go_live_from_normalized_stage(),
+        {"$limit": limit},
+        {"$project": projection_fields}
+    ]
+    
+    return [
+        {
+            "$facet": {
+                "newly_added": [
+                    get_optimized_match_stage(recent_criteria),
+                    *common_stages
+                ],
+                "top_rated": [
+                    get_optimized_match_stage(base_criteria),
+                    {"$sort": {"average_rating.value": -1, "average_rating.total_reviews": -1}},
+                    *common_stages
+                ],
+                "popular": [
+                    get_optimized_match_stage(base_criteria),
+                    {"$sort": {"stats.total_bookings": -1, "average_rating.value": -1}},
+                    *common_stages
+                ],
+                "trending": [
+                    get_optimized_match_stage(base_criteria),
+                    {"$sort": {"trending": -1, "stats.total_bookings": -1}},
+                    *common_stages
+                ]
+            }
+        }
+    ]
+
+
+def build_optimized_search_pipeline_variants(
+    search_criteria: Dict,
+    limit: int,
+    offset: int,
+    projection_fields: Dict = None,
+    include_distance: bool = False,
+    user_lat: float = None,
+    user_lng: float = None
+) -> Dict[str, List[Dict]]:
+    """
+    Builds optimized pipeline variants for different search types.
+    Uses context-specific projections and performance optimizations.
+    
+    Args:
+        search_criteria: Base search criteria
+        limit: Number of documents to return
+        offset: Pagination offset
+        projection_fields: Fields to project (defaults to CARD_FIELDS)
+        include_distance: Whether to include distance calculation
+        user_lat: User latitude for distance calculation
+        user_lng: User longitude for distance calculation
+    
+    Returns:
+        Dictionary of optimized pipeline variants
+    """
+    if projection_fields is None:
+        projection_fields = CARD_FIELDS
+    
+    # Common optimized stages
+    def build_variant_pipeline(sort_criteria: Dict) -> List[Dict]:
+        return build_optimized_merchant_pipeline(
+            base_criteria=search_criteria,
+            sort_criteria=sort_criteria,
+            limit=limit,
+            offset=offset,
+            projection_fields=projection_fields,
+            include_distance=include_distance,
+            user_lat=user_lat,
+            user_lng=user_lng
+        )
+    
+    return {
+        "top_rated": build_variant_pipeline({
+            "average_rating.value": -1,
+            "average_rating.total_reviews": -1
+        }),
+        "popular": build_variant_pipeline({
+            "stats.total_bookings": -1,
+            "average_rating.value": -1
+        }),
+        "trending": build_variant_pipeline({
+            "trending": -1,
+            "stats.total_bookings": -1
+        }),
+        "default": build_variant_pipeline({
+            "go_live_from": -1
+        })
+    }
+
 
 def get_timezone_from_location(location_id: str) -> str:
     """
@@ -121,187 +389,67 @@ async def construct_sort_criteria(query: SearchQuery) -> Dict:
 
 async def get_recommended_merchants(query: SearchQuery) -> Dict:
     """
-    Fetch recommended merchants based on search criteria.
+    Fetch recommended merchants based on search criteria with performance monitoring.
     :param query: SearchQuery containing filters for merchants.
     :return: Dictionary containing categorized merchant recommendations.
     """
-    try:
-        logger.info(f"Fetching recommended services for query: {query.dict()}")
-
-        # Construct merchant search criteria
-        search_criteria = await construct_search_criteria(query)
-
-        # Construct a separate search criteria for "go_live_from" in the last 15 days
-
-         
-        search_criteria_recent = {
-            **search_criteria,
-            "go_live_from_normalized": {
-                "$gte": datetime.now(timezone.utc) - timedelta(days=15),
-                "$lte": datetime.now(timezone.utc)
-                #"$gte": datetime(2024, 1, 1, tzinfo=timezone.utc),
-                #"$lte": datetime(2025, 10, 24, tzinfo=timezone.utc)
-            }
-        }
-        logger.info(f"Merchant search criteria: {search_criteria}")
-        logger.info(f"Recent go_live_from search criteria: {search_criteria_recent}")
-
-
-        # Merchant recommendation pipeline
-        merchant_pipeline = [
-            {
-                "$facet": {
-                    "newly_added": [
-                        {"$match": search_criteria_recent},  # Only merchants from last 15 days
-                        {"$addFields": {
-                            "go_live_from_normalized": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                                    "then": "$go_live_from",
-                                    "else": {
-                                        "$cond": {
-                                            "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                            "then": {
-                                                "$dateFromString": {
-                                                    "dateString": "$go_live_from",
-                                                    "onError": {"$toDate": "$$NOW"}
-                                                }
-                                            },
-                                            "else": {"$toDate": "$$NOW"}
-                                        }
-                                    }
-                                }
-                            }
-                        }},
-                        {"$sort": {"go_live_from": -1}},  
-                        {"$limit": query.limit},
-                        {"$project": RECOMMENDED_FIELDS},
-                    ],
-                    "top_rated": [
-                        {"$match": search_criteria},  # General search criteria
-                        {"$addFields": {
-                            "go_live_from_normalized": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                                    "then": "$go_live_from",
-                                    "else": {
-                                        "$cond": {
-                                            "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                            "then": {
-                                                "$dateFromString": {
-                                                    "dateString": "$go_live_from",
-                                                    "onError": {"$toDate": "$$NOW"}
-                                                }
-                                            },
-                                            "else": {"$toDate": "$$NOW"}
-                                        }
-                                    }
-                                }
-                            }
-                        }},
-                        {"$sort": {"average_rating.value": -1}},  
-                        {"$limit": query.limit},
-                        {"$project": RECOMMENDED_FIELDS},
-                    ],
-                    "popular": [
-                        {"$match": search_criteria},
-                        {"$addFields": {
-                            "go_live_from_normalized": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                                    "then": "$go_live_from",
-                                    "else": {
-                                        "$cond": {
-                                            "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                            "then": {
-                                                "$dateFromString": {
-                                                    "dateString": "$go_live_from",
-                                                    "onError": {"$toDate": "$$NOW"}
-                                                }
-                                            },
-                                            "else": {"$toDate": "$$NOW"}
-                                        }
-                                    }
-                                }
-                            }
-                        }},
-                        {"$sort": {"stats.total_bookings": -1}},  
-                        {"$limit": query.limit},
-                        {"$project": RECOMMENDED_FIELDS},
-                    ],
-                    "trending": [
-                        {"$match": {**search_criteria, "trending.is_trending": True}},  
-                        {"$addFields": {
-                            "go_live_from_normalized": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                                    "then": "$go_live_from",
-                                    "else": {
-                                        "$cond": {
-                                            "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                            "then": {
-                                                "$dateFromString": {
-                                                    "dateString": "$go_live_from",
-                                                    "onError": {"$toDate": "$$NOW"}
-                                                }
-                                            },
-                                            "else": {"$toDate": "$$NOW"}
-                                        }
-                                    }
-                                }
-                            }
-                        }},
-                        {"$sort": {"stats.total_bookings": -1}},  
-                        {"$limit": query.limit},
-                        {"$project": RECOMMENDED_FIELDS},
-                    ],
+    async with performance_timer("get_recommended_merchants"):
+        try:
+            logger.info(f"Fetching recommended services for query: {query.dict()}")
+
+            # Construct merchant search criteria
+            search_criteria = await construct_search_criteria(query)
+
+            # Construct a separate search criteria for "go_live_from" in the last 15 days
+            search_criteria_recent = {
+                **search_criteria,
+                "go_live_from": {
+                    "$gte": datetime.now(timezone.utc) - timedelta(days=DEFAULT_RECENT_DAYS),
+                    "$lte": datetime.now(timezone.utc)
                 }
-            },
-        ]
-
-        # Execute MongoDB query for merchants
-        merchant_results = await execute_query("merchants", merchant_pipeline)
+            }
+            logger.info(f"Merchant search criteria: {search_criteria}")
+            logger.info(f"Recent go_live_from search criteria: {search_criteria_recent}")
+
+            # Use the optimized faceted pipeline
+            merchant_pipeline = build_optimized_faceted_pipeline(
+                base_criteria=search_criteria,
+                recent_criteria=search_criteria_recent,
+                limit=query.limit,
+                projection_fields=RECOMMENDED_FIELDS_OPTIMIZED
+            )
+            
+            # Log pipeline complexity
+            log_pipeline_complexity(merchant_pipeline, "merchants", "get_recommended_merchants")
 
-        # Serialize merchant results
-        merchants = serialize_mongo_document(merchant_results[0]) if merchant_results else {}
+            # Execute MongoDB query for merchants
+            merchant_results = await execute_query("merchants", merchant_pipeline)
 
-        # Structure merchant recommendations
-        structured_merchants = []
+            # Serialize merchant results
+            merchants = serialize_mongo_document(merchant_results[0]) if merchant_results else {}
 
-        '''if merchants.get("top_rated"):
-            structured_merchants.append(
-                {"id": "top_rated", "title": "Highest Rated Gems", "services": merchants["top_rated"]}
-            )
-        if merchants.get("popular"):
-            structured_merchants.append(
-                {"id": "popular", "title": "Crowd Favorites", "services": merchants["popular"]}
-            )
-        if merchants.get("trending"):
-            structured_merchants.append(
-                {"id": "trending", "title": "Buzzing Hot Picks", "services": merchants["trending"]}
-            )'''
-        
-        merchant_mapping = {
-            "newly_added": "New Pop-Ups",
-            "top_rated": "Highest Rated Gems",
-            "popular": "Crowd Favorites",
-            "trending": "Buzzing Hot Picks"
-        }
+            # Structure merchant recommendations
+            merchant_mapping = {
+                "newly_added": "New Pop-Ups",
+                "top_rated": "Highest Rated Gems",
+                "popular": "Crowd Favorites",
+                "trending": "Buzzing Hot Picks"
+            }
 
-        # Iterate through mapping and append only if the key exists in merchants
-        structured_merchants = [
-            {"id": key, "title": title, "services": merchants[key]}
-            for key, title in merchant_mapping.items() if key in merchants
-        ]
+            # Iterate through mapping and append only if the key exists in merchants
+            structured_merchants = [
+                {"id": key, "title": title, "services": merchants[key]}
+                for key, title in merchant_mapping.items() if key in merchants
+            ]
 
-        # Combine results into a unified response
-        response = {"data": structured_merchants}
-        logger.info("Successfully fetched recommended merchants.")
-        return response
+            # Combine results into a unified response
+            response = {"data": structured_merchants}
+            logger.info("Successfully fetched recommended merchants.")
+            return response
 
-    except Exception as e:
-        logger.error(f"Error fetching recommended merchants: {e}")
-        raise HTTPException(status_code=500, detail="Failed to fetch recommended merchants")
+        except Exception as e:
+            logger.error(f"Error fetching recommended merchants: {e}")
+            raise HTTPException(status_code=500, detail="Failed to fetch recommended merchants")
 
 
 async def fetch_ads(location_id: str, city: str = None, merchant_category: str = None, latitude: float = None, longitude: float = None, radius: float = 10.0, limit: int = 10, offset: int = 0) -> Dict:
@@ -403,164 +551,46 @@ async def process_search_query(query: NewSearchQuery) -> Dict:
     try:
         logger.info(f"DEBUG: Processing search query: {query.dict()}")
         
-        # ✅ Normalize Inputs
-        location = query.location_id.upper()
-        city = query.city.lower() if query.city is not None else None
-        # First check if query is None, then check merchant_category
-        category = None
-        if query is not None and query.merchant_category is not None:
-            category = query.merchant_category.lower()
-
-        logger.info(f"DEBUG: Normalized inputs - location: {location}, city: {city}, category: {category}")
-
-        lat, lng, radius = None, None, None  # Initialize variables to avoid reference errors
-
-        # ✅ Extract geo parameters
-        if query.geo is not None:  # Ensure geo is provided
-            lat, lng, radius = query.geo.latitude, query.geo.longitude, query.geo.radius
-            logger.info(f"DEBUG: Geo parameters - lat: {lat}, lng: {lng}, radius: {radius}")
-
-        # ✅ Construct Search Criteria
-        search_criteria = {
-            "go_live_from": {"$lte": datetime.now(timezone.utc)},
-            "location_id": location,
-            "merchant_category": category,
-            "city": city  # Case-insensitive match  
-        }
-
-        # Process free_text if provided
-        if query.free_text:
-            logger.info(f"DEBUG: Processing free_text: {query.free_text}")
-            free_text_params = await process_free_text(query.free_text)
-            logger.info(f"DEBUG: Processed free_text parameters: {free_text_params}")
-            # ✅ Add free_text filters
-            if free_text_params:
-                search_criteria.update(free_text_params)
-
-        logger.info(f"Processing amenities #########: {query.amenities}")
-
-        # ✅ Handle business hours based on availability
-        now_time = datetime.now().strftime("%H:%M")  # Current time in HH:MM format
-        business_hour_filters = []
-
-        logger.info(f"Query 1 #########: {query}")
-
-        if query.merchant_subcategory is not None:
-            sub_category = query.merchant_subcategory.lower()
-            search_criteria["merchant_subcategory"] = sub_category
-
-        if "now" in query.availability:
-            business_hour_filters.append({"business_hour.weekdays": {"$elemMatch": {"closing_time": {"$gt": now_time}}}})
-
-        if "all" in query.availability:
-            business_hour_filters.append({"business_hour.weekly_holiday": {"$exists": False}})
-
-        if "early" in query.availability:
-            business_hour_filters.append({"business_hour.weekdays": {"$elemMatch": {"opening_time": {"$lt": "09:00"}}}})
-
-        if "late" in query.availability:
-            business_hour_filters.append({"business_hour.weekdays": {"$elemMatch": {"closing_time": {"$gt": "20:00"}}}})
-
-        # Merge availability filters
-        if business_hour_filters:
-            search_criteria["$and"] = business_hour_filters
-
-        # Handle amenities
-        if "amenities" in search_criteria and search_criteria["amenities"] is not None:
-            logger.info(f"Overriding existing amenities filter: {search_criteria['amenities']}")
-            
-            existing_amenities = search_criteria["amenities"]
-            
-            search_criteria.pop("amenities", None)
-            
-            if isinstance(existing_amenities, list):
-                combined_amenities = set(existing_amenities + query.amenities)
-            else:
-                combined_amenities = set(query.amenities)
-
-            regex_patterns = [
-                { "amenities": { "$regex": amenity, "$options": "i" } }
-                for amenity in combined_amenities
-            ]
-            search_criteria["$or"] = regex_patterns
-            
-            search_criteria.pop("amenities", None)
-
-        elif query.amenities and len(query.amenities) > 0:
-            logger.info(f"Adding new amenities filter: {query.amenities}")
-            
-            regex_patterns = [
-                { "amenities": { "$regex": amenity, "$options": "i" } }
-                for amenity in query.amenities
-            ]
-            search_criteria["$or"] = regex_patterns
-
-        else:
-            logger.info("No amenities filter applied.")
-
-        # ✅ Geospatial filter
-        if lat and lng:
-            # Use default radius of 50000 meters (50km) if not provided
-            search_radius = radius if radius is not None else 50000
-            # Convert meters to radians for $centerSphere (Earth radius = 6378100 meters)
-            radius_in_radians = search_radius / 6378100.0
-            search_criteria["address.location"] = {
-                "$geoWithin": {"$centerSphere": [[lng, lat], radius_in_radians]}
-            }
-
-            
-
-            if "radius" in search_criteria:
-                search_criteria.pop("radius")  # Remove radius field completely from criteria
-
-        # ✅ Additional filters
-        if query.business_name:
-            search_criteria["$text"] = {"$search": query.business_name}  # Full-text search
-
-        if query.average_rating:
-            search_criteria["average_rating.value"] = {"$gte": query.average_rating}
-
-        # ✅ Construct Sorting Criteria
-        sort_criteria = {}
-
-        # ✅ Sorting options
-        if query.sort_by == "recommended":
-            sort_criteria.update({
-                "average_rating.value": -1,
-                "average_rating.total_reviews": -1,
-                "recommendations.nearby_priority": -1,
-            })
-        elif query.sort_by == "price":
-            sort_criteria["average_price"] = 1 if query.sort_order == "asc" else -1
-        elif query.sort_by == "rating":
-            sort_criteria["average_rating.value"] = 1 if query.sort_order == "asc" else -1
-        elif query.sort_by == "distance" and lat and lng:
-            sort_criteria["address.location"] = {
-                "$nearSphere": {
-                    "$geometry": {
-                        "type": "Point",
-                        "coordinates": [lng, lat]
-                    }
-                }
-            }
-        elif query.sort_by == "popularity" or query.sort_by == "trending":
-            sort_criteria.update({
-                "stats.total_bookings": -1,
-                "average_rating.total_reviews": -1
-            })
-        elif query.sort_by == "recent":
-            sort_criteria["go_live_from"] = -1
-        else:
-            sort_criteria["go_live_from"] = -1  # Default sorting if nothing specified
-
-        # Remove None values from search and sort criteria
-        search_criteria = {k: v for k, v in search_criteria.items() if v is not None}
-        sort_criteria = {k: v for k, v in sort_criteria.items() if v is not None}
-
+        # Normalize inputs
+        normalized_inputs = _normalize_query_inputs(query)
+        
+        # Build base search criteria
+        search_criteria = _build_base_criteria(normalized_inputs)
+        
+        # Apply free text filters
+        search_criteria = await _apply_free_text_filters(search_criteria, query.free_text)
+        
+        # Apply availability filters
+        search_criteria = _apply_availability_filters(search_criteria, query.availability)
+        
+        # Apply amenity filters
+        search_criteria = _apply_amenity_filters(search_criteria, query.amenities)
+        
+        # Apply geospatial filters
+        search_criteria = _apply_geo_filters(
+            search_criteria, 
+            normalized_inputs["lat"], 
+            normalized_inputs["lng"], 
+            normalized_inputs["radius"]
+        )
+        
+        # Apply additional filters
+        search_criteria = _apply_additional_filters(search_criteria, query)
+        
+        # Build sort criteria
+        sort_criteria = _build_sort_criteria(
+            query, 
+            normalized_inputs["lat"], 
+            normalized_inputs["lng"]
+        )
+        
+        # Clean criteria by removing None values
+        search_criteria = _clean_criteria(search_criteria)
+        sort_criteria = _clean_criteria(sort_criteria)
+        
         logger.info(f"DEBUG: Final search criteria: {search_criteria}")
         logger.info(f"DEBUG: Final sort criteria: {sort_criteria}")
-
-        # ✅ Final Output
+        
         return {
             "search_criteria": search_criteria,
             "sort_criteria": sort_criteria
@@ -576,176 +606,94 @@ async def process_search_query(query: NewSearchQuery) -> Dict:
 
 async def fetch_search_list(query: NewSearchQuery) -> Dict:
     """
-    Fetch merchants based on search criteria
+    Fetch merchants based on search criteria with performance monitoring
     """
-    try:
-        logger.info(f"Fetching search list for query: {query.dict()}")
-        
-        # Get search and sort criteria
-        criteria_result = await process_search_query(query)
-        search_criteria = criteria_result["search_criteria"]
-        sort_criteria = criteria_result["sort_criteria"]
-        
-        logger.info(f"Final search criteria: {search_criteria}")
-        logger.info(f"Final sort criteria: {sort_criteria}")
-
-        # ✅ Define pipelines for different cases
-        pipelines = {
-            "top_rated": [
-                {"$match": search_criteria},
-                {"$addFields": {
-                    "go_live_from_normalized": {
-                        "$cond": {
-                            "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                            "then": "$go_live_from",
-                            "else": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                    "then": {
-                                        "$dateFromString": {
-                                            "dateString": "$go_live_from",
-                                            "onError": {"$toDate": "$$NOW"}
-                                        }
-                                    },
-                                    "else": {"$toDate": "$$NOW"}
-                                }
-                            }
-                        }
-                    }
-                }},
-                {"$sort": {"average_rating.value": -1}},
-                {"$skip": query.offset},
-                {"$limit": query.limit},
-                {"$project": COMMON_FIELDS},
-            ],
-            "popular": [
-                {"$match": search_criteria},
-                {"$addFields": {
-                    "go_live_from_normalized": {
-                        "$cond": {
-                            "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                            "then": "$go_live_from",
-                            "else": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                    "then": {
-                                        "$dateFromString": {
-                                            "dateString": "$go_live_from",
-                                            "onError": {"$toDate": "$$NOW"}
-                                        }
-                                    },
-                                    "else": {"$toDate": "$$NOW"}
-                                }
-                            }
-                        }
-                    }
-                }},
-                {"$sort": {"stats.total_bookings": -1}},
-                {"$skip": query.offset},
-                {"$limit": query.limit},
-                {"$project": COMMON_FIELDS},
-            ],
-            "trending": [
-                {"$match": {**search_criteria, "trending.is_trending": True}},
-                {"$addFields": {
-                    "go_live_from_normalized": {
-                        "$cond": {
-                            "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                            "then": "$go_live_from",
-                            "else": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                    "then": {
-                                        "$dateFromString": {
-                                            "dateString": "$go_live_from",
-                                            "onError": {"$toDate": "$$NOW"}
-                                        }
-                                    },
-                                    "else": {"$toDate": "$$NOW"}
-                                }
-                            }
-                        }
-                    }
-                }},
-                {"$sort": {"stats.total_bookings": -1}},
-                {"$skip": query.offset},
-                {"$limit": query.limit},
-                {"$project": COMMON_FIELDS},
-            ],
-            "default": [
-                {"$match": search_criteria},
-                {"$addFields": {
-                    "go_live_from_normalized": {
-                        "$cond": {
-                            "if": {"$eq": [{"$type": "$go_live_from"}, "date"]},
-                            "then": "$go_live_from",
-                            "else": {
-                                "$cond": {
-                                    "if": {"$eq": [{"$type": "$go_live_from"}, "string"]},
-                                    "then": {
-                                        "$dateFromString": {
-                                            "dateString": "$go_live_from",
-                                            "onError": {"$toDate": "$$NOW"}
-                                        }
-                                    },
-                                    "else": {"$toDate": "$$NOW"}
-                                }
-                            }
-                        }
-                    }
-                }},
-                {"$sort": sort_criteria if not (query.top_rated or query.popular or query.trending) else {"go_live_from": -1}},  
-                {"$skip": query.offset},
-                {"$limit": query.limit},
-                {"$project": COMMON_FIELDS},
-            ],
-        }
-
-        # ✅ Select the pipeline
-        selected_case = (
-            "top_rated" if query.top_rated else
-            "popular" if query.popular else
-            "trending" if query.trending else
-            "default"
-        )
-        logger.info(f"Selected case for merchant search: {selected_case}")
+    async with performance_timer("fetch_search_list"):
+        try:
+            logger.info(f"Fetching search list for query: {query.dict()}")
+            
+            # Get search and sort criteria
+            criteria_result = await process_search_query(query)
+            search_criteria = criteria_result["search_criteria"]
+            sort_criteria = criteria_result["sort_criteria"]
+            
+            logger.info(f"Final search criteria: {search_criteria}")
+            logger.info(f"Final sort criteria: {sort_criteria}")
+
+            # Use the optimized pipeline variants with distance calculation if needed
+            include_distance = query.geo and query.geo.latitude and query.geo.longitude
+            pipelines = build_optimized_search_pipeline_variants(
+                search_criteria=search_criteria,
+                limit=query.limit,
+                offset=query.offset,
+                projection_fields=CARD_FIELDS,
+                include_distance=include_distance,
+                user_lat=query.geo.latitude if query.geo else None,
+                user_lng=query.geo.longitude if query.geo else None
+            )
+            
+            # Override the default pipeline to use the custom sort criteria when needed
+            if not (query.top_rated or query.popular or query.trending):
+                pipelines["default"] = build_optimized_merchant_pipeline(
+                    base_criteria=search_criteria,
+                    sort_criteria=sort_criteria,
+                    limit=query.limit,
+                    offset=query.offset,
+                    projection_fields=CARD_FIELDS,
+                    include_distance=include_distance,
+                    user_lat=query.geo.latitude if query.geo else None,
+                    user_lng=query.geo.longitude if query.geo else None
+                )
+
+            # ✅ Select the pipeline
+            selected_case = (
+                "top_rated" if query.top_rated else
+                "popular" if query.popular else
+                "trending" if query.trending else
+                "default"
+            )
+            logger.info(f"Selected case for merchant search: {selected_case}")
 
-        # ✅ Execute the pipeline
-        pipeline = pipelines[selected_case]
-        merchants = await execute_query("merchants", pipeline)
+            # ✅ Execute the pipeline
+            pipeline = pipelines[selected_case]
+            
+            # Log pipeline complexity
+            log_pipeline_complexity(pipeline, "merchants", "fetch_search_list")
+            
+            merchants = await execute_query("merchants", pipeline)
 
-     
-        total = await count_documents("merchants", search_criteria)
-        has_more = query.offset + len(merchants) < total
+         
+            total = await count_documents("merchants", search_criteria)
+            has_more = query.offset + len(merchants) < total
+
+            # ✅ Format the results in a categorized structure
+            structured_results = [
+                {
+                    "id": selected_case,
+                    "title": (
+                        "Highest Rated Gems" if selected_case == "top_rated" else
+                        "Crowd Favorites" if selected_case == "popular" else
+                        "Buzzing Hot Picks" if selected_case == "trending" else
+                        "Advance Search Results" # Default title
+                    ),
+                    "services": merchants,
+                }
+            ]
 
-        # ✅ Format the results in a categorized structure
-        structured_results = [
-            {
-                "id": selected_case,
-                "title": (
-                    "Highest Rated Gems" if selected_case == "top_rated" else
-                    "Crowd Favorites" if selected_case == "popular" else
-                    "Buzzing Hot Picks" if selected_case == "trending" else
-                    "Advance Search Results" # Default title
-                ),
-                "services": merchants,
+            # ✅ Include pagination metadata in the response
+            return {
+                "pagination": {
+                    "total": total,
+                    "has_more": has_more,
+                    "offset": query.offset,
+                    "limit": query.limit,
+                },
+                "data": structured_results,
             }
-        ]
-
-        # ✅ Include pagination metadata in the response
-        return {
-            "pagination": {
-                "total": total,
-                "has_more": has_more,
-                "offset": query.offset,
-                "limit": query.limit,
-            },
-            "data": structured_results,
-        }
 
-    except Exception as e:
-        logger.error(f"Error fetching search list: {e}")
-        raise HTTPException(status_code=500, detail="Failed to fetch search list")
+        except Exception as e:
+            logger.error(f"Error fetching search list: {e}")
+            raise HTTPException(status_code=500, detail="Failed to fetch search list")
 
 
 async def fetch_merchant_details(merchant_id: str, location_id: str) -> Dict:
@@ -769,7 +717,7 @@ async def fetch_merchant_details(merchant_id: str, location_id: str) -> Dict:
 
         if not merchant_details:
             logger.warning(f"No merchant found for merchant_id={merchant_id}, location_id={location_id}")
-            raise RuntimeError("Merchant not found")
+            raise HTTPException(status_code=404, detail="Merchant not found")
 
         # Return the first document from the query results
         response = merchant_details[0]
@@ -779,35 +727,26 @@ async def fetch_merchant_details(merchant_id: str, location_id: str) -> Dict:
 
     except Exception as e:
         logger.error(f"Error fetching details for merchant_id={merchant_id}: {e}")
-        raise RuntimeError(f"Failed to fetch merchant details: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to fetch merchant details: {e}")
 
 
 
 
-async def fetch_merchant_catalogues(merchant_id: str, location_id: str) -> Dict:
+async def fetch_merchant_catalogues_optimized(merchant_id: str, location_id: str) -> Dict:
     """
-    Fetch staff and catalogue for a specific merchant and location efficiently using a single aggregation pipeline.
+    Optimized version that fetches staff and catalogue data using minimal projections
+    and a single efficient aggregation pipeline.
     """
     try:
-        logger.info(f"Fetching details for merchant_id={merchant_id}, location_id={location_id}")
+        logger.info(f"Fetching optimized details for merchant_id={merchant_id}, location_id={location_id}")
 
-        # Use MongoDB's $facet to perform multiple aggregations in a single query
+        # Use optimized $facet with minimal projections
         combined_pipeline = [
-            {"$match": {"merchant_id": merchant_id, "location_id": location_id}},
+            get_optimized_match_stage({"merchant_id": merchant_id, "location_id": location_id}),
             {
                 "$facet": {
                     "catalogue_data": [
-                        {
-                            "$project": {
-                                "_id": 0,
-                                "merchant_id": 1,
-                                "business_name": 1,
-                                "location_id": 1,
-                                "catalogue": {
-                                    "$map": MERCHANT_SCHEMA["catalogue_projection"]
-                                }
-                            }
-                        }
+                        {"$project": CATALOGUE_MINIMAL_FIELDS}
                     ],
                     "staff_data": [
                         {
@@ -815,45 +754,26 @@ async def fetch_merchant_catalogues(merchant_id: str, location_id: str) -> Dict:
                                 "from": "staff",
                                 "let": {"m_id": "$merchant_id", "l_id": "$location_id"},
                                 "pipeline": [
-                                    {
-                                        "$match": {
-                                            "$expr": {
-                                                "$and": [
-                                                    {"$eq": ["$merchant_id", "$$m_id"]},
-                                                    {"$eq": ["$location_id", "$$l_id"]}
-                                                ]
-                                            }
+                                    get_optimized_match_stage({
+                                        "$expr": {
+                                            "$and": [
+                                                {"$eq": ["$merchant_id", "$$m_id"]},
+                                                {"$eq": ["$location_id", "$$l_id"]}
+                                            ]
                                         }
-                                    },
-                                    {
-                                        "$project": {
-                                            "_id": 0,
-                                            "staff": {
-                                                "$map": MERCHANT_SCHEMA["staff_projection"]
-                                            }
-                                        }
-                                    }
+                                    }),
+                                    {"$project": STAFF_MINIMAL_FIELDS}
                                 ],
-                                "as": "staff_info"
+                                "as": "staff"
                             }
                         },
-                        {
-                            "$project": {
-                                "staff": {
-                                    "$cond": {
-                                        "if": {"$gt": [{"$size": "$staff_info"}, 0]},
-                                        "then": {"$arrayElemAt": ["$staff_info.staff", 0]},
-                                        "else": []
-                                    }
-                                }
-                            }
-                        }
+                        {"$project": STAFF_MINIMAL_FIELDS}
                     ]
                 }
             }
         ]
 
-        # Execute the combined query
+        # Execute the optimized query
         result = await execute_query("catalogues", combined_pipeline)
         combined_data = serialize_mongo_document(result[0]) if result else {}
 
@@ -865,7 +785,7 @@ async def fetch_merchant_catalogues(merchant_id: str, location_id: str) -> Dict:
             logger.warning(f"No details found for merchant_id={merchant_id}, location_id={location_id}")
             raise HTTPException(status_code=404, detail="Merchant details not found")
 
-        # Build response
+        # Build optimized response
         response = {
             "merchant_id": merchant_id,
             "business_name": catalogue_data.get("business_name"),
@@ -877,10 +797,9 @@ async def fetch_merchant_catalogues(merchant_id: str, location_id: str) -> Dict:
         return response
 
     except HTTPException:
-        # Re-raise HTTP exceptions
         raise
     except Exception as e:
-        logger.error(f"Error fetching details for merchant_id={merchant_id}: {e}")
+        logger.error(f"Error fetching optimized details for merchant_id={merchant_id}: {e}")
         raise HTTPException(status_code=500, detail=f"Failed to fetch merchant details: {str(e)}")
 
 
@@ -908,7 +827,7 @@ async def fetch_merchant_info(merchant_id: str, location_id: str) -> Dict:
 
         if not merchant_info:
             logger.warning(f"No merchant found for merchant_id={merchant_id}, location_id={location_id}")
-            raise RuntimeError("Merchant not found")
+            raise HTTPException(status_code=404, detail="Merchant not found")
 
         # Return the first document from the query results
         response = merchant_info[0]
@@ -918,9 +837,9 @@ async def fetch_merchant_info(merchant_id: str, location_id: str) -> Dict:
 
     except Exception as e:
         logger.error(f"Error fetching details for merchant_id={merchant_id}: {e}")
-        raise RuntimeError(f"Failed to fetch merchant details: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to fetch merchant details: {e}")
 
-async def fetch_merchant_reviews(
+async def fetch_merchant_reviews_optimized(
     merchant_id: str,
     location_id: str,
     limit: int = 10,
@@ -931,72 +850,133 @@ async def fetch_merchant_reviews(
     verified_purchase: bool = None
 ) -> Dict[str, Any]:
     """
-    Fetch paginated, sorted, and filtered merchant reviews.
-    Only fetch summary when offset is 0.
+    Optimized version that fetches reviews and summary using a single aggregation pipeline.
     """
     try:
-        logger.info(f"Fetching reviews: merchant_id={merchant_id}, location_id={location_id}, "
+        logger.info(f"Fetching optimized reviews: merchant_id={merchant_id}, location_id={location_id}, "
                     f"limit={limit}, offset={offset}, sort_by={sort_by}, sort_order={sort_order}, "
                     f"filter_ratings={filter_ratings}, verified_purchase={verified_purchase}")
 
-        summary = {}
-        logger.info(f"Fetching reviews for merchant_id={merchant_id}, location_id={location_id}, limit={limit}, offset={offset}")
-        if offset == 0:
-            # Step 1: Fetch Summary (only on first page)
-            summary_pipeline = [
-                {"$match": {"merchant_id": merchant_id, "location_id": location_id}},
-                {"$project": {
-                    "_id": 0,
-                    "ai_review_summary": 1,
-                    "total_reviews": 1,
-                    "overall_rating": 1,
-                    "rating_distribution": 1
-                }}
-            ]
-            summary_result = await execute_query("merchant_review_summary", summary_pipeline)
-            summary = summary_result[0] if summary_result else {
-                "ai_review_summary": {},
-                "total_reviews": 0,
-                "overall_rating": 0.0,
-                "rating_distribution": {"1": 0, "2": 0, "3": 0, "4": 0, "5": 0}
-            }
-
-        # Step 2: Build Match Filters
+        # Build Match Filters
         match_filter = {"merchant_id": merchant_id, "location_id": location_id}
         if filter_ratings:
             match_filter["rating"] = {"$in": filter_ratings}
         if verified_purchase is not None:
             match_filter["verified_purchase"] = verified_purchase
 
-        # Step 3: Build Sort
+        # Build Sort
         valid_sort_fields = {"review_date": "review_date", "rating": "rating"}
         sort_field = valid_sort_fields.get(sort_by, "review_date")
         sort_dir = -1 if sort_order == "desc" else 1
 
-        # Step 4: Fetch paginated, sorted, filtered reviews
-        reviews_pipeline = [
-            {"$match": match_filter},
-            {"$sort": {sort_field: sort_dir}},
-            {"$skip": offset},
-            {"$limit": limit},
-            {"$project": {
-                "_id": 0,
-                "user_name": 1,
-                "rating": 1,
-                "review_text": 1,
-                "review_date": 1,
-                "verified_purchase": 1
-            }}
+        # Single optimized aggregation pipeline using $facet
+        combined_pipeline = [
+            get_optimized_match_stage(match_filter),
+            {
+                "$facet": {
+                    "reviews": [
+                        {"$sort": {sort_field: sort_dir}},
+                        {"$skip": offset},
+                        {"$limit": limit},
+                        {
+                            "$project": {
+                                "_id": 0,
+                                "user_name": 1,
+                                "rating": 1,
+                                "review_text": 1,
+                                "review_date": 1,
+                                "verified_purchase": 1
+                            }
+                        }
+                    ],
+                    "summary": [
+                        {
+                            "$group": {
+                                "_id": None,
+                                "total_reviews": {"$sum": 1},
+                                "overall_rating": {"$avg": "$rating"},
+                                "rating_distribution": {
+                                    "$push": {
+                                        "$switch": {
+                                            "branches": [
+                                                {"case": {"$eq": ["$rating", 5]}, "then": "5"},
+                                                {"case": {"$eq": ["$rating", 4]}, "then": "4"},
+                                                {"case": {"$eq": ["$rating", 3]}, "then": "3"},
+                                                {"case": {"$eq": ["$rating", 2]}, "then": "2"},
+                                                {"case": {"$eq": ["$rating", 1]}, "then": "1"}
+                                            ],
+                                            "default": "0"
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                        {
+                            "$project": {
+                                "_id": 0,
+                                "total_reviews": 1,
+                                "overall_rating": {"$round": ["$overall_rating", 2]},
+                                "rating_distribution": {
+                                    "5": {
+                                        "$size": {
+                                            "$filter": {
+                                                "input": "$rating_distribution",
+                                                "cond": {"$eq": ["$$this", "5"]}
+                                            }
+                                        }
+                                    },
+                                    "4": {
+                                        "$size": {
+                                            "$filter": {
+                                                "input": "$rating_distribution",
+                                                "cond": {"$eq": ["$$this", "4"]}
+                                            }
+                                        }
+                                    },
+                                    "3": {
+                                        "$size": {
+                                            "$filter": {
+                                                "input": "$rating_distribution",
+                                                "cond": {"$eq": ["$$this", "3"]}
+                                            }
+                                        }
+                                    },
+                                    "2": {
+                                        "$size": {
+                                            "$filter": {
+                                                "input": "$rating_distribution",
+                                                "cond": {"$eq": ["$$this", "2"]}
+                                            }
+                                        }
+                                    },
+                                    "1": {
+                                        "$size": {
+                                            "$filter": {
+                                                "input": "$rating_distribution",
+                                                "cond": {"$eq": ["$$this", "1"]}
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    ]
+                }
+            }
         ]
-        reviews = await execute_query("merchant_reviews", reviews_pipeline)
 
-        # Step 5: Count filtered total (for pagination)
-        count_pipeline = [{"$match": match_filter}, {"$count": "total"}]
-        count_result = await execute_query("merchant_reviews", count_pipeline)
-        filtered_total = count_result[0]["total"] if count_result else 0
+        # Execute the combined query
+        result = await execute_query("merchant_reviews", combined_pipeline)
+        combined_data = serialize_mongo_document(result[0]) if result else {}
+
+        # Extract data from facet results
+        reviews = combined_data.get("reviews", [])
+        summary_data = combined_data.get("summary", [{}])[0]
+        
+        filtered_total = summary_data.get("total_reviews", 0)
         has_more = offset + len(reviews) < filtered_total
 
-        # Step 6: Prepare response
+        # Build optimized response
         response = {
             "merchant_id": merchant_id,
             "location_id": location_id,
@@ -1011,15 +991,14 @@ async def fetch_merchant_reviews(
 
         if offset == 0:
             response.update({
-                "ai_review_summary": summary.get("ai_review_summary", {}),
-                "overall_rating": summary.get("overall_rating", 0.0),
-                "rating_distribution": summary.get("rating_distribution", {})
+                "overall_rating": summary_data.get("overall_rating", 0.0),
+                "rating_distribution": summary_data.get("rating_distribution", {})
             })
 
         return response
 
     except Exception as e:
-        logger.error(f"Error fetching flat reviews: {e}")
+        logger.error(f"Error fetching optimized reviews: {e}")
         raise HTTPException(status_code=500, detail=f"Failed to fetch merchant reviews: {str(e)}")
 
 
@@ -1044,17 +1023,17 @@ def generate_time_slots(opening_time: str, closing_time: str) -> List[str]:
     return slots
 
 
-async def fetch_merchant_business_hours(merchant_id: str, location_id: str) -> Dict:
+async def fetch_merchant_business_hours_optimized(merchant_id: str, location_id: str) -> Dict:
     """
-    Fetch business hours for a specific merchant and location, and generate a schedule in a UI-friendly structure.
+    Optimized version that fetches business hours with minimal projection and generates a schedule in a UI-friendly structure.
     """
     try:
-        logger.info(f"Fetching business hours for merchant_id={merchant_id}, location_id={location_id}")
+        logger.info(f"Fetching optimized business hours for merchant_id={merchant_id}, location_id={location_id}")
         
-        # Fetch business hours from the "merchants" collection
-        logger.info("Executing query to fetch business hours from merchants collection")
+        # Use optimized match stage and fetch business hours from the "merchants" collection
+        logger.info("Executing optimized query to fetch business hours from merchants collection")
         business_hour_info = await execute_query("merchants", [
-            {"$match": {"merchant_id": merchant_id, "location_id": location_id}},
+            get_optimized_match_stage({"merchant_id": merchant_id, "location_id": location_id}),
             {
                 "$project": {
                     "_id": 0,
@@ -1150,11 +1129,13 @@ async def fetch_merchant_business_hours(merchant_id: str, location_id: str) -> D
             schedule.append(day_data)
             logger.info(f"Processed schedule for {date_label}: {day_data}")
 
-        logger.info(f"Successfully fetched business hours and generated schedule for merchant_id={merchant_id}, location_id={location_id}")
+        logger.info(f"Successfully fetched optimized business hours and generated schedule for merchant_id={merchant_id}, location_id={location_id}")
         return {"days": schedule}
 
+    except HTTPException:
+        raise
     except Exception as e:
-        logger.error(f"Error fetching business hours for merchant_id={merchant_id}, location_id={location_id}: {e}")
+        logger.error(f"Error fetching optimized business hours for merchant_id={merchant_id}, location_id={location_id}: {e}")
         raise HTTPException(status_code=500, detail=f"Failed to fetch business hours: {e}")
 
 

app/services/search_helpers.py

@@ -0,0 +1,305 @@
+"""
+Helper functions for search query processing.
+This module contains smaller, focused functions that were extracted from the large process_search_query function.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Dict, List, Any, Optional
+
+from app.models.merchant import NewSearchQuery
+from app.utils.constants import (
+    DEFAULT_SEARCH_RADIUS_METERS, EARTH_RADIUS_METERS, EARLY_OPENING_TIME, LATE_CLOSING_TIME,
+    AVAILABILITY_NOW, AVAILABILITY_ALL, AVAILABILITY_EARLY, AVAILABILITY_LATE
+)
+from .helper import process_free_text
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_query_inputs(query: NewSearchQuery) -> Dict[str, Any]:
+    """
+    Normalize and extract basic query inputs.
+    
+    Args:
+        query: The search query object
+        
+    Returns:
+        Dict containing normalized inputs
+    """
+    location = query.location_id.upper()
+    city = query.city.lower() if query.city is not None else None
+    category = None
+    if query is not None and query.merchant_category is not None:
+        category = query.merchant_category.lower()
+    
+    sub_category = None
+    if query.merchant_subcategory is not None:
+        sub_category = query.merchant_subcategory.lower()
+    
+    # Extract geo parameters
+    lat, lng, radius = None, None, None
+    if query.geo is not None:
+        lat, lng, radius = query.geo.latitude, query.geo.longitude, query.geo.radius
+    
+    logger.info(f"DEBUG: Normalized inputs - location: {location}, city: {city}, category: {category}")
+    if lat and lng:
+        logger.info(f"DEBUG: Geo parameters - lat: {lat}, lng: {lng}, radius: {radius}")
+    
+    return {
+        "location": location,
+        "city": city,
+        "category": category,
+        "sub_category": sub_category,
+        "lat": lat,
+        "lng": lng,
+        "radius": radius
+    }
+
+
+def _build_base_criteria(normalized_inputs: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Build the base search criteria from normalized inputs.
+    
+    Args:
+        normalized_inputs: Dictionary of normalized query inputs
+        
+    Returns:
+        Base search criteria dictionary
+    """
+    search_criteria = {
+        "go_live_from": {"$lte": datetime.now(timezone.utc)},
+        "location_id": normalized_inputs["location"],
+        "merchant_category": normalized_inputs["category"],
+        "city": normalized_inputs["city"]
+    }
+    
+    # Add subcategory if provided
+    if normalized_inputs["sub_category"]:
+        search_criteria["merchant_subcategory"] = normalized_inputs["sub_category"]
+    
+    return search_criteria
+
+
+async def _apply_free_text_filters(search_criteria: Dict[str, Any], free_text: Optional[str]) -> Dict[str, Any]:
+    """
+    Apply free text search filters to the search criteria.
+    
+    Args:
+        search_criteria: Current search criteria
+        free_text: Free text search string
+        
+    Returns:
+        Updated search criteria with free text filters
+    """
+    if free_text:
+        logger.info(f"DEBUG: Processing free_text: {free_text}")
+        free_text_params = await process_free_text(free_text)
+        logger.info(f"DEBUG: Processed free_text parameters: {free_text_params}")
+        
+        if free_text_params:
+            search_criteria.update(free_text_params)
+    
+    return search_criteria
+
+
+def _apply_availability_filters(search_criteria: Dict[str, Any], availability: List[str]) -> Dict[str, Any]:
+    """
+    Apply availability filters based on business hours.
+    
+    Args:
+        search_criteria: Current search criteria
+        availability: List of availability options
+        
+    Returns:
+        Updated search criteria with availability filters
+    """
+    now_time = datetime.now().strftime("%H:%M")
+    business_hour_filters = []
+    
+    if AVAILABILITY_NOW in availability:
+        business_hour_filters.append({
+            "business_hour.weekdays": {
+                "$elemMatch": {"closing_time": {"$gt": now_time}}
+            }
+        })
+    
+    if AVAILABILITY_ALL in availability:
+        business_hour_filters.append({
+            "business_hour.weekly_holiday": {"$exists": False}
+        })
+    
+    if AVAILABILITY_EARLY in availability:
+        business_hour_filters.append({
+            "business_hour.weekdays": {
+                "$elemMatch": {"opening_time": {"$lt": EARLY_OPENING_TIME}}
+            }
+        })
+    
+    if AVAILABILITY_LATE in availability:
+        business_hour_filters.append({
+            "business_hour.weekdays": {
+                "$elemMatch": {"closing_time": {"$gt": LATE_CLOSING_TIME}}
+            }
+        })
+    
+    # Merge availability filters
+    if business_hour_filters:
+        search_criteria["$and"] = business_hour_filters
+    
+    return search_criteria
+
+
+def _apply_amenity_filters(search_criteria: Dict[str, Any], amenities: List[str]) -> Dict[str, Any]:
+    """
+    Apply amenity filters to the search criteria.
+    
+    Args:
+        search_criteria: Current search criteria
+        amenities: List of amenities to filter by
+        
+    Returns:
+        Updated search criteria with amenity filters
+    """
+    logger.info(f"Processing amenities: {amenities}")
+    
+    # Handle existing amenities in search criteria
+    if "amenities" in search_criteria and search_criteria["amenities"] is not None:
+        logger.info(f"Overriding existing amenities filter: {search_criteria['amenities']}")
+        
+        existing_amenities = search_criteria["amenities"]
+        search_criteria.pop("amenities", None)
+        
+        if isinstance(existing_amenities, list):
+            combined_amenities = set(existing_amenities + amenities)
+        else:
+            combined_amenities = set(amenities)
+        
+        regex_patterns = [
+            {"amenities": {"$regex": amenity, "$options": "i"}}
+            for amenity in combined_amenities
+        ]
+        search_criteria["$or"] = regex_patterns
+    
+    elif amenities and len(amenities) > 0:
+        logger.info(f"Adding new amenities filter: {amenities}")
+        
+        regex_patterns = [
+            {"amenities": {"$regex": amenity, "$options": "i"}}
+            for amenity in amenities
+        ]
+        search_criteria["$or"] = regex_patterns
+    
+    else:
+        logger.info("No amenities filter applied.")
+    
+    return search_criteria
+
+
+def _apply_geo_filters(search_criteria: Dict[str, Any], lat: Optional[float], lng: Optional[float], radius: Optional[float]) -> Dict[str, Any]:
+    """
+    Apply geospatial filters to the search criteria.
+    
+    Args:
+        search_criteria: Current search criteria
+        lat: Latitude coordinate
+        lng: Longitude coordinate
+        radius: Search radius in meters
+        
+    Returns:
+        Updated search criteria with geo filters
+    """
+    if lat and lng:
+        # Use default radius if not provided
+        search_radius = radius if radius is not None else DEFAULT_SEARCH_RADIUS_METERS
+        # Convert meters to radians for $centerSphere
+        radius_in_radians = search_radius / EARTH_RADIUS_METERS
+        
+        search_criteria["address.location"] = {
+            "$geoWithin": {"$centerSphere": [[lng, lat], radius_in_radians]}
+        }
+        
+        # Remove radius field from criteria if it exists
+        if "radius" in search_criteria:
+            search_criteria.pop("radius")
+    
+    return search_criteria
+
+
+def _apply_additional_filters(search_criteria: Dict[str, Any], query: NewSearchQuery) -> Dict[str, Any]:
+    """
+    Apply additional filters like business name and rating.
+    
+    Args:
+        search_criteria: Current search criteria
+        query: The search query object
+        
+    Returns:
+        Updated search criteria with additional filters
+    """
+    if query.business_name:
+        search_criteria["$text"] = {"$search": query.business_name}
+    
+    if query.average_rating:
+        search_criteria["average_rating.value"] = {"$gte": query.average_rating}
+    
+    return search_criteria
+
+
+def _build_sort_criteria(query: NewSearchQuery, lat: Optional[float], lng: Optional[float]) -> Dict[str, Any]:
+    """
+    Build sorting criteria based on query parameters.
+    
+    Args:
+        query: The search query object
+        lat: Latitude coordinate for distance sorting
+        lng: Longitude coordinate for distance sorting
+        
+    Returns:
+        Sort criteria dictionary
+    """
+    sort_criteria = {}
+    
+    if query.sort_by == "recommended":
+        sort_criteria.update({
+            "average_rating.value": -1,
+            "average_rating.total_reviews": -1,
+            "recommendations.nearby_priority": -1,
+        })
+    elif query.sort_by == "price":
+        sort_criteria["average_price"] = 1 if query.sort_order == "asc" else -1
+    elif query.sort_by == "rating":
+        sort_criteria["average_rating.value"] = 1 if query.sort_order == "asc" else -1
+    elif query.sort_by == "distance" and lat and lng:
+        sort_criteria["address.location"] = {
+            "$nearSphere": {
+                "$geometry": {
+                    "type": "Point",
+                    "coordinates": [lng, lat]
+                }
+            }
+        }
+    elif query.sort_by == "popularity" or query.sort_by == "trending":
+        sort_criteria.update({
+            "stats.total_bookings": -1,
+            "average_rating.total_reviews": -1
+        })
+    elif query.sort_by == "recent":
+        sort_criteria["go_live_from"] = -1
+    else:
+        sort_criteria["go_live_from"] = -1  # Default sorting
+    
+    return sort_criteria
+
+
+def _clean_criteria(criteria: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Remove None values from criteria dictionary.
+    
+    Args:
+        criteria: Dictionary to clean
+        
+    Returns:
+        Cleaned dictionary without None values
+    """
+    return {k: v for k, v in criteria.items() if v is not None}

app/utils/constants.py

@@ -0,0 +1,56 @@
+"""
+Constants for the merchant hub service.
+This file contains all magic numbers and hardcoded values used throughout the application.
+"""
+
+# Time-related constants
+DEFAULT_RECENT_DAYS = 15
+EARLY_OPENING_TIME = "09:00"
+LATE_CLOSING_TIME = "20:00"
+
+# Pagination and limits
+DEFAULT_LIMIT = 10
+DEFAULT_OFFSET = 0
+
+# Geospatial constants
+DEFAULT_SEARCH_RADIUS_METERS = 50000  # 50km default search radius
+EARTH_RADIUS_KM = 6378.1
+EARTH_RADIUS_METERS = 6378100.0
+
+# Rating constants
+MIN_RATING = 1
+MAX_RATING = 5
+
+# Business hours constants
+BUSINESS_HOURS_FORMAT = "%H:%M"
+
+# Search and sorting constants
+DEFAULT_SORT_ORDER = "desc"
+VALID_SORT_FIELDS = ["recommended", "price", "rating", "distance", "popularity", "trending", "recent"]
+VALID_SORT_ORDERS = ["asc", "desc"]
+
+# Availability options
+AVAILABILITY_NOW = "now"
+AVAILABILITY_ALL = "all"
+AVAILABILITY_EARLY = "early"
+AVAILABILITY_LATE = "late"
+VALID_AVAILABILITY_OPTIONS = [AVAILABILITY_NOW, AVAILABILITY_ALL, AVAILABILITY_EARLY, AVAILABILITY_LATE]
+
+# Error messages
+ERROR_MERCHANT_NOT_FOUND = "Merchant not found"
+ERROR_BUSINESS_HOURS_NOT_FOUND = "Business hours not found"
+ERROR_BUSINESS_HOURS_UNAVAILABLE = "Business hours data is unavailable"
+ERROR_FAILED_FETCH_MERCHANTS = "Failed to fetch recommended merchants"
+ERROR_FAILED_FETCH_ADS = "Failed to fetch ad campaigns"
+ERROR_FAILED_FETCH_SEARCH = "Failed to fetch search list"
+ERROR_FAILED_FETCH_DETAILS = "Failed to fetch merchant details"
+ERROR_FAILED_FETCH_REVIEWS = "Failed to fetch merchant reviews"
+ERROR_FAILED_FETCH_BUSINESS_HOURS = "Failed to fetch business hours"
+ERROR_NO_DEFAULT_CATEGORY = "No default category found"
+ERROR_FAILED_FETCH_CATEGORIES = "Failed to fetch business categories"
+ERROR_FAILED_FETCH_LOCATIONS = "Failed to fetch live locations"
+
+# HTTP Status codes
+HTTP_STATUS_OK = 200
+HTTP_STATUS_NOT_FOUND = 404
+HTTP_STATUS_INTERNAL_ERROR = 500

app/utils/performance_monitor.py

@@ -0,0 +1,167 @@
+"""
+Performance monitoring utilities for tracking query execution times and database operations.
+"""
+import time
+import logging
+from functools import wraps
+from typing import Dict, Any, Optional
+from contextlib import asynccontextmanager
+
+logger = logging.getLogger(__name__)
+
+class PerformanceMetrics:
+    """Class to track and store performance metrics."""
+    
+    def __init__(self):
+        self.query_times = []
+        self.slow_queries = []
+        self.total_queries = 0
+        self.total_time = 0.0
+    
+    def add_query_time(self, collection: str, pipeline_length: int, execution_time: float, query_type: str = "aggregation"):
+        """Add a query execution time to metrics."""
+        self.query_times.append({
+            "collection": collection,
+            "pipeline_length": pipeline_length,
+            "execution_time": execution_time,
+            "query_type": query_type,
+            "timestamp": time.time()
+        })
+        
+        self.total_queries += 1
+        self.total_time += execution_time
+        
+        # Track slow queries (> 1 second)
+        if execution_time > 1.0:
+            self.slow_queries.append({
+                "collection": collection,
+                "pipeline_length": pipeline_length,
+                "execution_time": execution_time,
+                "query_type": query_type,
+                "timestamp": time.time()
+            })
+            logger.warning(f"Slow query detected: {collection} took {execution_time:.3f}s")
+    
+    def get_average_time(self) -> float:
+        """Get average query execution time."""
+        return self.total_time / self.total_queries if self.total_queries > 0 else 0.0
+    
+    def get_slow_query_count(self) -> int:
+        """Get count of slow queries."""
+        return len(self.slow_queries)
+    
+    def get_metrics_summary(self) -> Dict[str, Any]:
+        """Get a summary of performance metrics."""
+        return {
+            "total_queries": self.total_queries,
+            "total_time": round(self.total_time, 3),
+            "average_time": round(self.get_average_time(), 3),
+            "slow_queries": self.get_slow_query_count(),
+            "recent_queries": self.query_times[-10:] if self.query_times else []
+        }
+
+# Global performance metrics instance
+performance_metrics = PerformanceMetrics()
+
+def monitor_query_performance(func):
+    """Decorator to monitor query performance."""
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        start_time = time.time()
+        
+        try:
+            result = await func(*args, **kwargs)
+            execution_time = time.time() - start_time
+            
+            # Extract collection and pipeline info from args
+            collection = args[0] if args else "unknown"
+            pipeline_length = len(args[1]) if len(args) > 1 and isinstance(args[1], list) else 0
+            
+            performance_metrics.add_query_time(
+                collection=collection,
+                pipeline_length=pipeline_length,
+                execution_time=execution_time,
+                query_type="aggregation"
+            )
+            
+            logger.info(f"Query executed: {collection} in {execution_time:.3f}s (pipeline length: {pipeline_length})")
+            
+            return result
+            
+        except Exception as e:
+            execution_time = time.time() - start_time
+            logger.error(f"Query failed after {execution_time:.3f}s: {str(e)}")
+            raise
+    
+    return wrapper
+
+@asynccontextmanager
+async def performance_timer(operation_name: str):
+    """Context manager for timing operations."""
+    start_time = time.time()
+    try:
+        yield
+    finally:
+        execution_time = time.time() - start_time
+        logger.info(f"Operation '{operation_name}' completed in {execution_time:.3f}s")
+
+def log_pipeline_complexity(pipeline: list, collection: str, operation: str):
+    """Log pipeline complexity metrics."""
+    complexity_score = 0
+    stage_counts = {}
+    
+    for stage in pipeline:
+        stage_type = list(stage.keys())[0] if stage else "unknown"
+        stage_counts[stage_type] = stage_counts.get(stage_type, 0) + 1
+        
+        # Assign complexity scores to different stages
+        complexity_weights = {
+            "$match": 1,
+            "$project": 1,
+            "$sort": 2,
+            "$group": 3,
+            "$lookup": 4,
+            "$facet": 5,
+            "$unwind": 2,
+            "$addFields": 1,
+            "$limit": 1,
+            "$skip": 1
+        }
+        
+        complexity_score += complexity_weights.get(stage_type, 2)
+    
+    logger.info(f"Pipeline complexity for {operation} on {collection}: "
+                f"score={complexity_score}, stages={len(pipeline)}, "
+                f"breakdown={stage_counts}")
+    
+    # Warn about high complexity
+    if complexity_score > 15:
+        logger.warning(f"High complexity pipeline detected: {operation} on {collection} "
+                      f"(score: {complexity_score})")
+    
+    return complexity_score
+
+def get_performance_report() -> Dict[str, Any]:
+    """Get a comprehensive performance report."""
+    return {
+        "metrics": performance_metrics.get_metrics_summary(),
+        "recommendations": _generate_recommendations()
+    }
+
+def _generate_recommendations() -> list:
+    """Generate performance recommendations based on metrics."""
+    recommendations = []
+    
+    avg_time = performance_metrics.get_average_time()
+    slow_query_count = performance_metrics.get_slow_query_count()
+    
+    if avg_time > 0.5:
+        recommendations.append("Consider adding indexes for frequently queried fields")
+    
+    if slow_query_count > 0:
+        recommendations.append(f"Optimize {slow_query_count} slow queries detected")
+    
+    if performance_metrics.total_queries > 100:
+        recommendations.append("Consider implementing query result caching")
+    
+    return recommendations