# CountryAtlas

www.countryatlas.co — Understand the world, one country at a time.

Explore the world through data. The interactive data atlas of the world: 218 countries and territories, 260+ indicators, 2 million observations, 9 sources — every number traceable to source → dataset → series → retrieval date → original URL.

Signature features (2.0, September 2026): World Explorer (/explore, full-screen map + time machine 1960→today), Country DNA (percentile fingerprint with a reference profile), Country similarity (explainable peers), World Pulse (what is changing globally), Change detection (records, reversals, structural breaks, volatility), Trajectories (/trajectories, animated Gapminder-style bubbles), Scatter with descriptive statistics, Country Finder (/finder, filter the world like a database), Extremes, Above/below expected (/peers), Data stories, a dataset builder, an interactive API explorer and a provenance panel on every value.

# Layout

text

registry/            canonical registries (YAML, versioned): countries, groups, indicators, topics, similarity, insights
src/countryatlas/    Python platform
  registry/          loaders + country-code lookups
  connectors/        one module per provider (worldbank, owid, imf, oecd, eurostat, who, fred, bis, ilo)
  pipeline/          fetch → normalize → validate → build (DuckDB snapshot) → derived tables; scheduler; exports
  storage/schema.sql DuckDB schema (single source of truth for pipeline and API)
  api/               FastAPI public API  (/api/v1, OpenAPI at /api/v1/docs)
  cli.py             `ca` command line
apps/web/            Next.js 16 app (App Router, Tailwind v4, own SVG chart kit, d3-geo maps) — see apps/web/README.md
src/countryatlas/stats.py   deterministic statistics engine (ranks, percentiles, robust z, breaks, correlations, Theil–Sen…)
deploy/              mld manifest for the MacLustr cluster
docs/                ARCHITECTURE.md (contract), PIPELINE.md, API.md, sources-research.md
tests/               pytest

# Run locally

bash

uv venv --python 3.12 .venv && uv pip install -e ".[dev]"
.venv/bin/ca registry validate
CA_DATA_DIR=~/countryatlas-data .venv/bin/ca refresh          # fetch all connectors, build ~/countryatlas-data/atlas.duckdb
CA_DATA_DIR=~/countryatlas-data .venv/bin/ca status
CA_DATA_DIR=~/countryatlas-data .venv/bin/python -m uvicorn countryatlas.api.main:app --port 8291
pnpm install && cd apps/web && API_URL=http://127.0.0.1:8291 pnpm dev      # http://localhost:8290

# Deploy (MacLustr)

Manifest deploy/countryatlas.mld.json → M1M32:~/dispatch/apps/countryatlas.json, then from the laptop:

bash

~/Desktop/cluster-skill/mld stage ~/Desktop/Projets/apps-web/countryatlas countryatlas
~/Desktop/cluster-skill/mld deploy countryatlas --node M2M32

Public route https://www.countryatlas.co → M2M32:8290 is created on the BHS64 gateway by mld deploy (DNS A www → 51.161.112.61). Processes (PM2): countryatlas-web (:8290), countryatlas-api (127.0.0.1:8291), countryatlas-scheduler (daily refresh 03:15 America/Toronto).

# Data sources & licences

World Bank WDI (CC BY 4.0), IMF WEO (IMF terms), OECD (CC BY 4.0), Eurostat (CC BY 4.0), WHO GHO (CC BY-NC-SA 3.0 IGO), FRED (St. Louis Fed terms; series-level licences), Our World in Data (CC BY 4.0), BIS (BIS terms). Every value on the site and in the API carries its source, dataset, series code, retrieval and source-update dates.