Technology stack

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

"next": "15.5.9"

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

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:

<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

"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:

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:

"mongodb": "^6.19.0"

Reference: package.json:17 Connection management: Singleton pattern with connection pooling:

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:

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

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

{
  "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:

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:

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:

"axios": "^1.11.0"

Reference: package.json:12 Axios is used for Factbook requests due to better error handling:

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.

"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.

"react-svg": "^16.3.0"

Reference: package.json:21

react-zoom-pan-pinch

Enables interactive map controls:

"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:

"cookies-next": "^6.1.1"

Reference: package.json:13 Usage:

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:

"uuid": "^13.0.0"

Reference: package.json:23

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:

// 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:

"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 Reference: README.md:5

Environment variables

Required configuration:

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

Setup

Architecture

API Reference

Contributing

Framework

Next.js 15

UI framework

React 19

Tailwind CSS

Framer Motion

Lucide React

Language

TypeScript

Database

MongoDB Atlas

External APIs

RestCountries API

CIA World Factbook

Map visualization

D3-geo

react-svg

react-zoom-pan-pinch

Session management

cookies-next

uuid

Utilities

Geographic calculations

Development tools

ESLint

pnpm

Deployment

Vercel

Environment variables

Technology choices summary

Build docs developers (and LLMs) love

Setup

Architecture

API Reference

Contributing

Documentation Index

​Framework

​Next.js 15

​UI framework

​React 19

​Tailwind CSS

​Framer Motion

​Lucide React

​Language

​TypeScript

​Database

​MongoDB Atlas

​External APIs

​RestCountries API

​CIA World Factbook

​Map visualization

​D3-geo

​react-svg

​react-zoom-pan-pinch

​Session management

​cookies-next

​uuid

​Utilities

​Geographic calculations

​Development tools

​ESLint

​pnpm

​Deployment

​Vercel

​Environment variables

​Technology choices summary

Build docs developers (and LLMs) love

Framework

Next.js 15

UI framework

React 19

Tailwind CSS

Framer Motion

Lucide React

Language

TypeScript

Database

MongoDB Atlas

External APIs

RestCountries API

CIA World Factbook

Map visualization

D3-geo

react-svg

react-zoom-pan-pinch

Session management

cookies-next

uuid

Utilities

Geographic calculations

Development tools

ESLint

pnpm

Deployment

Vercel

Environment variables

Technology choices summary