> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/igorek05m/daily-geogame/llms.txt
> Use this file to discover all available pages before exploring further.

# Technology stack

> Detailed breakdown of frameworks, libraries, and tools used in Daily GeoGame

Daily GeoGame is built with modern web technologies optimized for developer experience and performance.

## Framework

### Next.js 15

The application uses Next.js 15 with the App Router for full-stack React development.

**Why Next.js?**

* Server and client components in one codebase
* Built-in API routes for backend logic
* Automatic code splitting and optimization
* Zero-config TypeScript support
* Server-side rendering for better SEO

**Key features used:**

* App Router for file-based routing (`app/` directory)
* Server Actions for data mutations
* React Server Components for initial data fetching
* API routes for backend endpoints (`app/api/`)
* Middleware for request interception
* Turbopack for faster development builds

Reference: `package.json:18`

```json theme={null}
"next": "15.5.9"
```

Build scripts use the `--turbopack` flag for improved performance:

```bash theme={null}
npm run dev    # Uses Turbopack
npm run build  # Production build with Turbopack
```

Reference: `package.json:6-7`

## UI framework

### React 19

The frontend is built with React 19, using hooks and functional components throughout.

**Key patterns:**

* **Hooks**: `useState`, `useEffect`, `useRouter` for state management
* **Suspense**: Loading states with `<Suspense>` boundaries
* **Client components**: Marked with `"use client"` directive
* **Composition**: Small, reusable components

Reference: `package.json:19-20`

**Why React 19?**

* Improved Suspense support
* Better concurrent rendering
* Server Component integration with Next.js
* Enhanced TypeScript support

### Tailwind CSS

All styling is done with Tailwind CSS utility classes.

**Configuration:**

* Tailwind CSS v4 with PostCSS plugin
* Dark theme by default (`bg-[#121212]`)
* Custom color palette for game UI
* Responsive design with mobile-first approach

Reference: `package.json:27,34`

**Example usage:**

```tsx theme={null}
<div className="min-h-screen bg-[#121212] text-[#e0e0e0] font-mono">
  <div className="w-full max-w-4xl flex-grow p-4 flex flex-col gap-6">
    {/* Game content */}
  </div>
</div>
```

Reference: `app/page.tsx:55-57`

### Framer Motion

Used for animations and transitions throughout the UI.

**Use cases:**

* Hint reveal animations
* Modal transitions (stats modal)
* Guess list animations
* Map country highlighting

Reference: `package.json:15`

```json theme={null}
"framer-motion": "^12.34.1"
```

### Lucide React

Icon library for consistent, lightweight icons.

**Examples:**

* Navigation arrows
* Stats icons
* Game UI elements

Reference: `package.json:16`

## Language

### TypeScript

The entire codebase is written in TypeScript with strict type checking.

**Type definitions:**

```typescript theme={null}
export type Country = {
  name: string;
  alpha2Code: string;
  alpha3Code: string;
  latlng: [number, number];
  borders?: string[];
  area?: number;
  population?: number;
  flag?: string;
  region?: string;
  subregion?: string;
  distance?: number;
  bearing?: number;
  connection?: "guess" | "neighbor" | "subregion" | "region" | "none";
};

export type HintPackage = {
  title: string;
  hints: { label: string; value: string }[];
};

export type GlobalStats = {
  totalPlayers: number;
  totalWinners: number;
  winRate: number;
  guessDistribution?: Record<string, number>;
};
```

Reference: `app/types.ts:3-45`

**Why TypeScript?**

* Catch errors at compile time
* Better IDE autocomplete
* Self-documenting code
* Safer refactoring
* Improved maintainability

Reference: `package.json:35`

## Database

### MongoDB Atlas

Persistent storage using MongoDB's cloud database service.

**Collections:**

* `daily_games`: One document per date with target country and hints
* `user_progress`: Progress tracking per session and date

**Driver:**

```json theme={null}
"mongodb": "^6.19.0"
```

Reference: `package.json:17`

**Connection management:**

Singleton pattern with connection pooling:

```typescript theme={null}
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URI);
const clientPromise = client.connect();

export default clientPromise;
```

Reference: `app/lib/mongodb.ts:1-22`

**Why MongoDB?**

* Flexible schema for country data
* Easy to store nested hint packages
* Fast document queries by date
* Free tier on Atlas for small projects
* JSON-like document structure matches JavaScript

## External APIs

### RestCountries API

Provides comprehensive country data including:

* Country names and codes
* Flags (SVG URLs)
* Geographic coordinates
* Border countries
* Population and area
* Regions and subregions

**Endpoint used:**

```typescript theme={null}
const res = await fetch(`https://restcountries.com/v3.1/alpha/${alpha2}`, {
  cache: 'force-cache'
});
```

Reference: `app/api/daily/route.ts:12-13`

**Data shape:**

```json theme={null}
{
  "name": { "common": "France" },
  "cca2": "FR",
  "cca3": "FRA",
  "latlng": [46, 2],
  "borders": ["BEL", "DEU", "ESP", "ITA", "LUX", "MCO", "CHE"],
  "area": 551695,
  "population": 67391582,
  "flags": { "svg": "https://flagcdn.com/fr.svg" },
  "region": "Europe",
  "subregion": "Western Europe"
}
```

### CIA World Factbook

JSON version hosted on GitHub provides detailed country information for hints.

**Base URL:**

```typescript theme={null}
const BASE_URL = "https://raw.githubusercontent.com/factbook/factbook.json/master";
```

Reference: `app/lib/factbook.ts:19`

**Data extracted:**

* Climate descriptions
* Terrain information
* Natural resources
* Export commodities
* Demographics and religions
* Flag descriptions
* National symbols

**Regional structure:**

```typescript theme={null}
const REGIONS = [
  "africa", "antarctica", "australia-oceania",
  "central-america-n-caribbean", "central-asia",
  "east-n-southeast-asia", "europe", "middle-east",
  "north-america", "south-america", "south-asia"
];
```

Reference: `app/lib/factbook.ts:5-17`

**HTTP client:**

```json theme={null}
"axios": "^1.11.0"
```

Reference: `package.json:12`

Axios is used for Factbook requests due to better error handling:

```typescript theme={null}
const response = await axios.get(url);
if (response.status === 200) {
  return response.data;
}
```

Reference: `app/lib/factbook.ts:33-35`

## Map visualization

### D3-geo

Core library for geographic projections and path generation.

```json theme={null}
"d3-geo": "^3.1.1",
"@types/d3-geo": "^3.1.0"
```

Reference: `package.json:14,28`

**Usage:**

* Mercator projection for world map
* Path generation from GeoJSON
* Coordinate transformations

### react-svg

Loads and renders SVG map files dynamically.

```json theme={null}
"react-svg": "^16.3.0"
```

Reference: `package.json:21`

### react-zoom-pan-pinch

Enables interactive map controls:

```json theme={null}
"react-zoom-pan-pinch": "^3.7.0"
```

Reference: `package.json:22`

**Features:**

* Mouse wheel zoom
* Click and drag panning
* Touch gestures on mobile
* Programmatic zoom/pan controls

## Session management

### cookies-next

Server and client cookie handling for Next.js:

```json theme={null}
"cookies-next": "^6.1.1"
```

Reference: `package.json:13`

**Usage:**

```typescript theme={null}
import { cookies } from 'next/headers';

const cookieStore = await cookies();
const sessionId = cookieStore.get('geo_session')?.value;
```

Reference: `app/api/progress/route.ts:4,17-18`

### uuid

Generates unique session identifiers:

```json theme={null}
"uuid": "^13.0.0"
```

Reference: `package.json:23`

```typescript theme={null}
import { v4 as uuidv4 } from 'uuid';

const sessionId = uuidv4();
```

Reference: `app/api/progress/route.ts:3,21`

## Utilities

### Geographic calculations

Custom utilities for distance and bearing calculations:

```typescript theme={null}
// Haversine formula for distance
export function getDistanceFromLatLonInKm(
  lat1: number, lon1: number,
  lat2: number, lon2: number
) {
  const R = 6371; // Earth radius in km
  // ... calculation
  return Math.round(d);
}

// Bearing angle from one point to another
export function getBearingAngle(
  lat1: number, lon1: number,
  lat2: number, lon2: number
) {
  // ... calculation
  return brng; // 0-360 degrees
}
```

Reference: `app/lib/geoUtils.ts:5-44`

## Development tools

### ESLint

Code linting with Next.js configuration:

```json theme={null}
"eslint": "^9",
"eslint-config-next": "15.5.2"
```

Reference: `package.json:32-33`

### pnpm

Package manager for faster installs and better disk efficiency.

**Why pnpm?**

* Faster than npm/yarn
* Saves disk space with content-addressable storage
* Strict dependency resolution

Reference: `README.md:32-34`

## Deployment

### Vercel

The app is deployed on Vercel's platform (Next.js creators).

**Benefits:**

* Zero-config deployment
* Automatic HTTPS
* Edge network CDN
* Environment variable management
* Preview deployments for PRs

**Live URL:** [https://daily-geogame.vercel.app](https://daily-geogame.vercel.app)

Reference: `README.md:5`

## Environment variables

Required configuration:

```bash theme={null}
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/geo_game
```

Reference: `README.md:39`

Stored in:

* `.env.local` for development
* Vercel dashboard for production

## Technology choices summary

| Technology        | Purpose      | Why chosen                                 |
| ----------------- | ------------ | ------------------------------------------ |
| **Next.js 15**    | Framework    | Full-stack React, API routes, SSR          |
| **React 19**      | UI library   | Modern hooks, Suspense, Server Components  |
| **TypeScript**    | Language     | Type safety, better DX                     |
| **Tailwind CSS**  | Styling      | Utility-first, fast iteration              |
| **MongoDB**       | Database     | Flexible schema, easy JSON storage         |
| **RestCountries** | Country data | Free, comprehensive, reliable              |
| **CIA Factbook**  | Hint data    | Rich geographic/economic info              |
| **D3-geo**        | Maps         | Industry standard for geo projections      |
| **Framer Motion** | Animations   | Declarative, performant animations         |
| **Vercel**        | Hosting      | Zero-config, global CDN, Next.js optimized |