Introduction
Relevant source files
The following files were used as context for generating this wiki page:
CoolTools is a comprehensive phone comparison platform built with Next.js, designed to provide users with detailed specifications, performance benchmarks, and side-by-side comparisons for over 10,000 mobile devices. The platform aggregates data from over 25 sources, including GSMArena and DXOMARK, covering more than 150 unique features per device. Sources: cooltools/app/layout.tsx:18-21, cooltools/app/page.tsx:43-60
The system architecture utilizes a modern web stack featuring React 19, Next.js 15, and a PostgreSQL database managed via Drizzle ORM and Prisma. It integrates with external mobile specification APIs to fetch real-time data while maintaining a local schema for user-generated content such as reviews, comparisons, and price history tracking. Sources: cooltools/package.json:14-25, cooltools/shared/schema.ts:3-100
Core Platform Architecture
The application follows the Next.js App Router architecture. The frontend is built using "client-side first" components for interactive features like carousels, searches, and comparison tables, while the backend logic handles data persistence and API orchestration. Sources: cooltools/app/page.tsx:1, cooltools/app/compare/page.tsx:1, cooltools/package.json:18
System Components
The platform is divided into several functional modules:
- Discovery Engine: Handles trending phones, latest releases, and category-based browsing (Gaming, Camera, Battery). Sources: cooltools/app/page.tsx:94-110
- Comparison Engine: Allows users to select up to 4 devices for detailed side-by-side analysis of display, performance, camera, and battery specs. Sources: cooltools/app/compare/page.tsx:96-100
- Data Layer: Manages external API calls with built-in caching and request deduplication to optimize performance and prevent rate limiting. Sources: cooltools/lib/phoneApi.ts:6-15
- Persistence Layer: Uses Drizzle ORM to define schemas for phones, price history, user reviews, and benchmarks. Sources: cooltools/shared/schema.ts:4-110
Data Flow Diagram
The following diagram illustrates how device data flows from external APIs through the internal library to the user interface.
Database Schema and Data Models
The system maintains a structured relational database to store comprehensive device specifications and user interaction data.
Primary Entities
| Entity | Description | Key Fields |
|---|---|---|
| Phones | Central repository for device specs. | brand, model, slug, chipset, full_specs (JSONB) |
| Comparisons | User-saved phone comparison groups. | user_id, phone_ids (JSONB), name |
| Price History | Tracks historical pricing across retailers. | phone_id, price, retailer, recorded_at |
| Benchmarks | Stores scores for AnTuTu, Geekbench, etc. | phone_id, benchmark_type, score |
Sources: cooltools/shared/schema.ts:4-113
Entity Relationship Diagram
The diagram below represents the relationships between the core data entities defined in the schema.
Sources: cooltools/shared/schema.ts:4-113
External API Integration
The phoneApi.ts library serves as the primary gateway to external mobile data. It implements a robust fetching strategy to ensure high availability and performance.
API Features
- Caching: Implements an in-memory
Mapcache with a 5-minute Time-To-Live (TTL). Sources: cooltools/lib/phoneApi.ts:8-9 - Request Deduplication: Uses a
pendingRequestsMap to prevent redundant concurrent calls for the same resource. Sources: cooltools/lib/phoneApi.ts:12 - Retry Logic: The
getPhoneDetailsfunction includes a retry mechanism (defaulting to 2 attempts) for resilient data fetching. Sources: cooltools/lib/phoneApi.ts:153-155
Sources: cooltools/lib/phoneApi.ts:6-170
Comparison Logic
The Comparison Engine manages the selection and side-by-side display of multiple devices. It supports up to 4 phones simultaneously.
Functional Workflow
- Selection: Users search and add phones via the
addPhonefunction, which validates the limit (max 4). Sources: cooltools/app/compare/page.tsx:88-100 - Detail Aggregation: Once phones are selected, the system fetches detailed specifications for each slug using
Promise.allSettledto handle partial failures gracefully. Sources: cooltools/app/compare/page.tsx:48-60 - URL Sync: Comparison states can be shared via URL parameters (e.g.,
?phones=slug1,slug2). Sources: cooltools/app/compare/page.tsx:23-28
Tech Stack Summary
The project utilizes the following technologies for development and deployment:
| Technology | Usage | Version |
|---|---|---|
| Next.js | Framework (App Router, Turbopack) | 15.5.4 |
| React | UI Library | 19.1.0 |
| Drizzle ORM | Type-safe SQL ORM | 0.44.6 |
| PostgreSQL | Database Engine | ^8.16.3 |
| TailwindCSS | Utility-first CSS | ^4 |
| Lucide React | Iconography | ^0.545.0 |
Sources: cooltools/package.json:14-38, cooltools/README.md:1-5
Conclusion
CoolTools is an architecturally sound platform designed for scalability and performance in the niche of mobile hardware comparison. By combining a robust persistence layer for user data with a high-performance external API integration layer, it provides a comprehensive toolset for consumers to make informed purchasing decisions based on technical data and historical trends.