Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
CoolTools is a modern web application built with Next.js, designed to provide a comprehensive platform for comparing mobile devices. The architecture leverages a client-side heavy React approach with an external mobile specifications API for data retrieval, supported by a PostgreSQL database managed via Drizzle ORM for local data persistence and features like user reviews and price history tracking.
The system is structured into a modular directory layout following Next.js 15 conventions, utilizing the App Router for navigation and Tailwind CSS for styling. It focuses on high performance through API response caching and request deduplication to handle large volumes of technical specifications efficiently.
Sources: cooltools/README.md, cooltools/package.json:20-30, cooltools/app/layout.tsx:28-60
System Architecture
The project follows a typical Next.js full-stack architecture where the frontend communicates with both an external Specifications API and a local database.
High-Level Component Flow
This diagram illustrates the flow from a user request through the Next.js routing system, the API integration layer with its caching mechanism, and the database persistence layer.
Sources: cooltools/lib/phoneApi.ts:6-15, cooltools/shared/schema.ts:3-5, cooltools/app/layout.tsx:45-55
Core Components and Technologies
Technology Stack
| Category | Technology | Purpose |
|---|---|---|
| Framework | Next.js 15.5.4 | React framework for SSR and routing |
| Language | TypeScript | Static typing and code quality |
| Styling | Tailwind CSS 4 | Utility-first CSS framework |
| Database | PostgreSQL | Relational data storage |
| ORM | Drizzle ORM / Prisma | Database schema and query management |
| Icons | Lucide React | Consistent UI iconography |
Sources: cooltools/package.json:15-40, cooltools/app/globals.css:1-15
API Integration and Caching
The application centralizes its data fetching logic in phoneApi.ts. To optimize performance and reduce external API load, it implements an in-memory cache with a Time-To-Live (TTL) of 5 minutes and a request deduplication mechanism using a pendingRequests Map.
Data Model and Schema
The application uses Drizzle ORM to define the structure of its PostgreSQL database. The schema is designed to store both normalized technical specifications and unstructured metadata via JSONB.
Key Database Entities
- Phones: Stores primary device data including brands, models, and technical specs (display, performance, camera, battery).
- Comparisons: Stores user-saved comparison lists using
jsonbto hold arrays of phone IDs. - Price History: Tracks historical pricing data for specific devices across different retailers.
- Benchmarks: Stores scores from various testing platforms like AnTuTu and Geekbench.
Sources: cooltools/shared/schema.ts:4-110
Entity Relationship Diagram
Sources: cooltools/shared/schema.ts:4-110
Middleware and Security
The application implements a global middleware to enforce security best practices. It intercepts requests (excluding static assets and internal Next.js paths) to inject security headers into the response.
Implemented Security Headers
X-Content-Type-Options: nosniff: Prevents MIME type sniffing.X-Frame-Options: DENY: Protects against clickjacking.X-XSS-Protection: 1; mode=block: Enables browser XSS filtering.Referrer-Policy: strict-origin-when-cross-origin: Controls referrer information sent with requests.
Sources: cooltools/middleware.ts:4-20
Frontend Routing and Feature Modules
The application uses the Next.js App Router for feature-based organization.
- Home (
/): Features a trending carousel, animated stats, and quick links to categories. - Search (
/search): Implements advanced filtering logic for specs like RAM, price, and display size. - Compare (
/compare): A dedicated interface allowing users to select up to 4 phones for side-by-side spec comparison. - Details (
/phones/[slug]): Tabbed interface for deep-diving into Specifications, Features, and Network technology.
Sources: cooltools/app/page.tsx:180-250, cooltools/app/search/page.tsx:10-50, cooltools/app/compare/page.tsx:120-150, cooltools/app/phones/[slug]/page.tsx:130-160
Summary
CoolTools architecture is designed for a data-intensive user experience. By combining a robust API integration layer with a flexible relational database schema, it supports complex features like multi-device comparison and historical price tracking while maintaining high performance through strategic caching and modern frontend rendering techniques.