Search Functionality

Relevant source files

The following files were used as context for generating this wiki page:

• cooltools/app/search/page.tsx
• cooltools/app/page.tsx
• cooltools/app/compare/page.tsx
• cooltools/app/phones/page.tsx
• cooltools/lib/phoneApi.ts
• cooltools/shared/schema.ts
• cooltools/lib/utils.ts

The Search Functionality in the CoolTools platform is a multi-faceted system designed to help users locate mobile devices through various entry points, including advanced filtering, real-time text queries, and category-based discovery. It serves as the primary discovery mechanism for a database containing over 10,000 phone models with 150+ features per device.

The system is implemented across several layers: a frontend UI using React state and Next.js navigation, a utility layer for performance optimization, and an API integration layer that communicates with a remote mobile specifications backend.

Architecture and Components

Advanced Search and Filtering

The advanced search interface allows users to narrow down devices using specific hardware criteria. This module manages a complex filter state and synchronizes it with the browser's URL to allow for shareable search results.

• State Management: Uses a filters object to track criteria such as brand, priceMin, ramMin, displaySize, and refreshRate.
• URL Synchronization: The useEffect hook reads searchParams on mount to pre-populate filters, while the handleSearch function serializes current filters into a query string and navigates to the updated URL.
• Active Filter Tracking: A derived count of active filters provides visual feedback to the user.

Sources: cooltools/app/search/page.tsx:8-42, cooltools/app/page.tsx:35-39

Real-time Comparison Search

Used within the comparison tool, this component provides an "as-you-type" experience to find devices to add to a side-by-side view.

• Search Trigger: Employs a setTimeout (300ms) within a useEffect hook to implement basic debouncing, preventing excessive API calls during rapid typing.
• Results Handling: Fetches data through the searchPhones API utility and updates a local searchResults state.

Sources: cooltools/app/compare/page.tsx:55-70, cooltools/lib/utils.ts:3-16

Data Flow for Search Operations

The following diagram illustrates how a user query moves from the UI through the API layer.

A visual representation of the data flow from user interaction to external API retrieval.
Sources: cooltools/app/search/page.tsx:35-42, cooltools/lib/phoneApi.ts:151-160

API Integration

The search functionality relies on the phoneApi.ts module, which abstracts the communication with https://api-mobilespecs.azharimm.dev.

Key Search Methods

Function	Endpoint	Description
searchPhones(query)	/search	Performs a text-based search for phone models.
getPhonesByBrand(slug)	/brands/{slug}	Filters results by a specific manufacturer.
getLatestPhones()	/latest	Retrieves the most recent additions to the database.
getTopPhones()	/top-by-interest	Returns phones currently trending among users.

Sources: cooltools/lib/phoneApi.ts:100-112, cooltools/lib/phoneApi.ts:151-171

Comparison Search Sequence

The sequence of events during a live search within the comparison tool.
Sources: cooltools/app/compare/page.tsx:55-78, cooltools/lib/phoneApi.ts:151-160

Data Models and Schema

Search results are typically returned as PhoneListItem objects before the full PhoneSpec is requested for detailed views. The database schema in schema.ts reflects the fields available for searching.

Phone Data Schema (Searchable Fields)

Field	Type	Description
brand	Text	Manufacturer name (e.g., Apple, Samsung).
model	Text	Specific model name.
ram	Integer	System memory in GB.
chipset	Text	The SoC used in the device.
refreshRate	Integer	Display refresh rate in Hz.
price	Integer	Price value used for range filtering.

Sources: cooltools/shared/schema.ts:4-30, cooltools/lib/phoneApi.ts:85-90

Category-Based Search

The system supports predefined category searches linked directly from the landing page. These use specific query parameters to filter devices by hardware strengths.

• Gaming Phones: search?category=gaming
• Camera Champions: search?category=camera
• Battery Kings: search?category=battery
• Flagship Devices: search?category=flagship

Sources: cooltools/app/page.tsx:112-117

Implementation Details

Debounce Utility

The project includes a generic debounce utility to optimize search inputs, although ComparePage currently implements a local version of this logic using setTimeout.

export function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
): (...args: Parameters<T>) => void {
  let timeout: NodeJS.Timeout;
  return function executedFunction(...args: Parameters<T>) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
}

Sources: cooltools/lib/utils.ts:3-16

Search Logic in Listings

On the general phones listing page, a client-side filter is applied to the already loaded phones state for immediate feedback without additional network requests for the initial set.

const filteredPhones = searchQuery.trim() 
  ? phones.filter(phone =>
      phone.phone_name.toLowerCase().includes(searchQuery.toLowerCase())
    )
  : phones;

Sources: cooltools/app/phones/page.tsx:43-48

Summary

The Search Functionality provides a robust gateway to the platform's device data. By combining URL-driven advanced filters for power users, debounced live search for comparison tasks, and category-based quick links for discovery, the system ensures high performance and usability across different device identification workflows.