Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The CoolTools platform is a comprehensive phone comparison application built with Next.js. It allows users to browse, search, and compare over 10,000 phone models using data aggregated from various industry-leading sources like GSMArena and DXOMARK. The project leverages a modern tech stack including React 19, Tailwind CSS 4, and Drizzle ORM for data persistence.
This guide provides the necessary technical overview to set up the development environment, understand the system architecture, and navigate the codebase. The application is structured around a central API integration layer that interfaces with the MobileSpecs API while maintaining a local database for extended features like price history and user reviews.
Sources: cooltools/app/layout.tsx:18-21, cooltools/app/page.tsx:32-52, cooltools/README.md:1-5
Environment Setup and Installation
The project is bootstrapped with create-next-app and uses TypeScript for type safety. Development requires Node.js and a package manager (npm, yarn, pnpm, or bun).
Development Commands
The following scripts are defined to manage the development lifecycle:
| Command | Description |
|---|---|
npm run dev | Starts the Next.js development server on port 5000 with Turbopack enabled. |
npm run build | Compiles the application for production using Turbopack. |
npm run start | Runs the compiled production build on port 5000. |
npm run db:push | Syncs the Drizzle schema with the local PostgreSQL database. |
npm run db:studio | Opens the Drizzle Kit GUI for database exploration. |
Sources: cooltools/package.json:6-13, cooltools/README.md:7-18
Technical Requirements
- Runtime: Node.js (Version compatibility indicated by
@types/node: ^20). - Framework: Next.js 15.5.4 (App Router).
- Database: PostgreSQL with Drizzle ORM.
- Styling: Tailwind CSS 4.0.
Sources: cooltools/package.json:16-41, cooltools/tsconfig.json:1-24
System Architecture
The application follows a standard Next.js App Router architecture. It separates concerns between the UI components, the data fetching logic (API client), and the database schema definitions.
Component Overview
- Layout Layer: Defines the global navigation and root structure, including font optimization using
GeistandGeist Mono. - API Client (
phoneApi.ts): Manages external requests to the MobileSpecs API, implementing an in-memory cache and request deduplication. - Data Models (
schema.ts): Defines the PostgreSQL table structures using Drizzle ORM for local data management.
Data Flow Diagram
The following diagram illustrates how the application fetches and processes phone data from the external API to the user interface.
The diagram shows the dual-path data flow: external data is fetched via a cached API client, while local features (reviews, history) are managed through the Drizzle ORM layer.
Sources: cooltools/lib/phoneApi.ts:6-20, cooltools/shared/schema.ts:4-100, cooltools/app/layout.tsx:30-70
Data Models and Schema
Local data persistence is handled by Drizzle ORM. The schema covers core entities required for advanced comparison features that go beyond simple spec listing.
Core Tables Summary
| Table | Purpose | Key Fields |
|---|---|---|
phones | Primary cache for phone specifications. | slug, brand, model, fullSpecs (JSONB) |
comparisons | Saved user comparison lists. | userId, phoneIds (JSONB) |
price_history | Historical price data tracking. | phoneId, price, retailer |
reviews | User-generated content. | rating, content, prosAndCons (JSONB) |
benchmarks | Performance scores (AnTuTu, etc.). | benchmarkType, score, details |
Sources: cooltools/shared/schema.ts:4-105
Database Entity Relationship Diagram
The schema allows for complex relationships between phones and their metadata.
The ER diagram displays the central role of the phones table as the anchor for reviews, pricing, and benchmarks.
Sources: cooltools/shared/schema.ts:4-105
Core Implementation Details
API Integration Strategy
The phoneApi.ts module implements an efficient fetching mechanism to handle high-frequency requests during comparisons:
- Caching: Uses a
Mapwith a Time-To-Live (TTL) of 5 minutes (300,000ms). - Deduplication: Tracks
pendingRequeststo prevent duplicate concurrent network calls for the same phone slug. - Retry Logic:
getPhoneDetailsincludes a configurable retry mechanism (default 2 retries) with exponential backoff.
// lib/phoneApi.ts:161-165
export async function getPhoneDetails(slug: string, retries = 2): Promise<PhoneSpec | null> {
const cacheKey = `phone-${slug}`;
const cached = getCached<PhoneSpec>(cacheKey);
if (cached) return cached;
// ... deduplication and fetch logic
}
Sources: cooltools/lib/phoneApi.ts:8-18, cooltools/lib/phoneApi.ts:161-190
Routing and Navigation
The application uses the Next.js App Router with several primary entry points accessible via the root layout:
/: Landing page with trending phones and stats./phones: List view of latest releases and brand browsing./compare: Side-by-side comparison engine (supports up to 4 devices)./search: Advanced filtering system with 150+ criteria.
Sources: cooltools/app/layout.tsx:47-65, cooltools/app/page.tsx:135-155
Summary
To get started with CoolTools, developers should install dependencies, run npm run dev to start the server on port 5000, and ensure a PostgreSQL instance is available for Drizzle ORM operations. The project's architecture emphasizes performance through API caching and a robust data model designed for extensive technical comparisons and historical tracking.