Next.js App Router Structure

Relevant source files

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

• cooltools/app/layout.tsx
• cooltools/app/page.tsx
• cooltools/app/phones/[slug]/page.tsx
• cooltools/app/compare/page.tsx
• cooltools/app/search/page.tsx
• cooltools/app/phones/page.tsx
• cooltools/app/not-found.tsx
• cooltools/app/error.tsx
• cooltools/middleware.ts

The "CoolTools" project is built using the Next.js App Router architecture, providing a modular and scalable structure for the phone comparison platform. This architecture leverages file-based routing, specialized files for error handling and layouts, and dynamic segments to manage a large database of mobile devices.

The application is structured within the cooltools/app directory, utilizing layout.tsx for persistent UI elements, page.tsx files for route segments, and dynamic folders (e.g., [slug]) for resource-specific views.

Core Architecture and Routing

The project follows the standard Next.js App Router convention where folders define routes and page.tsx defines the UI for those routes.

Route Hierarchy

Route	File Path	Description
/	cooltools/app/page.tsx	The landing page featuring trending phones, features, and statistics.
/phones	cooltools/app/phones/page.tsx	Directory of all available phone models with brand-based navigation.
/phones/[slug]	cooltools/app/phones/[slug]/page.tsx	Dynamic route for detailed technical specifications of a specific phone.
/compare	cooltools/app/compare/page.tsx	Side-by-side comparison interface for up to four devices.
/search	cooltools/app/search/page.tsx	Advanced search interface with 150+ filtering options.

Sources: cooltools/app/layout.tsx:43-66, cooltools/app/phones/page.tsx:1-5, cooltools/app/compare/page.tsx:1-8

Global Layout and Middleware

The RootLayout in cooltools/app/layout.tsx defines the HTML structure, global fonts (Geist Sans and Geist Mono), and the persistent navigation bar used across all pages.

The middleware.ts file intercepts requests to apply security headers such as X-Frame-Options and X-Content-Type-Options to all routes except static assets and API calls.
Sources: cooltools/app/layout.tsx:24-69, cooltools/middleware.ts:4-16

Data Flow and Component Logic

The application relies on Client Components ('use client') to manage interactive states, such as search filtering, carousels, and comparison lists. Data is fetched from an external API (Mobilespecs API) via the phoneApi.ts library.

Component Interaction Flow

1. User Interaction: Users interact with search bars or filter dropdowns (e.g., in search/page.tsx).
2. State Management: Local React state (useState) tracks query parameters and selected items.
3. API Integration: Asynchronous calls are made to getPhoneDetails, getLatestPhones, or searchPhones.
4. UI Update: The page rerenders with data fetched from the API.

Specialized System Files

Next.js provides specific file naming conventions to handle common application states:

Error and Not Found Handling

• error.tsx: A client-side boundary that catches unexpected errors in the route segment and provides a "Try again" functionality.
• not-found.tsx: A custom 404 page that provides navigation options back to the home or phone directory when a route or resource does not exist.

Sources: cooltools/app/error.tsx:10-34, cooltools/app/not-found.tsx:5-30

Comparison Engine

The comparison module in cooltools/app/compare/page.tsx manages a list of up to four PhoneListItem objects. It dynamically fetches PhoneSpec data for each selected slug to populate the comparison table.

Navigation and Search

The project uses next/link for client-side navigation and next/navigation (specifically useSearchParams and useRouter) to handle complex filtering states in the URL.

• Breadcrumbs: Pages like [slug]/page.tsx include "Back" navigation using Link components.
• Search Parameters: The search/page.tsx module synchronizes its local filter state with URL parameters, allowing for shareable search results.

Sources: cooltools/app/phones/[slug]/page.tsx:75-82, cooltools/app/search/page.tsx:26-38

The Next.js App Router structure in this project efficiently separates concerns between global layouts, route-specific logic, and centralized data fetching, while ensuring security through middleware and robust error handling.