# 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

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