# CountryAtlas

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

The definitive, sourced, historical data profile for every country: economy, government, population, labour, income,
housing, health, education, trade, energy, climate, environment, infrastructure, digital, innovation, agriculture,
tourism, security and quality of life — with rankings, comparisons, similarity, change detection and full provenance.

## 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)
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.