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

"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:[e-mail]/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