Bara La Afrika

Bara La Afrika (Swahili for "the continent of Africa") is a long-running project for uncovering, learning about and understanding Africa from historical and contemporary perspectives. It is a responsive web app with four sections:

Section	Route	What it shows
Home	/	Interactive Equal Earth map of Africa, countries coloured by their UN M49 region
Countries	/countries	All 54 states: the meaning of their names, flags, national symbols and national animals (from the project's research document)
Harim	/harim	Africa's mountains and their heights, country by country, with ranges, peak pages and exports
Dhahabu	/dhahabu	Gold in Africa: where it is found, how much is mined and traded, and how much central banks hold
Vinara	/vinara	The cardinals of Africa: the leading state and the runner-up on 13 measures, in Africa and in each region, whether the lead is narrowing, and the next elections

History appears in the navigation as "Coming soon".

Live site: https://baralaafrika.netlify.app. Data is refreshed weekly by a GitHub Actions workflow; every figure on the site carries its own date, and the strip at the top of each page shows the sources behind it.

---

Contents

• Architecture
• Repository layout
• Prerequisites
• Getting started (local development)
• Data: database and pipelines
• API
• The map
• The countries table
• Harim: the mountains page
• Dhahabu: the gold page
• Vinara: the cardinals of Africa
• The data ribbon and time range
• Performance
• Quality checks
• Environment variables
• Deployment (Netlify)
• Design system
• Decisions and trade-offs
• Scope and future work
• Credits and licences

---

Architecture

Browser (React + Vite SPA)
   │  /api/*  (JSON, zod-validated, CDN-cached)
   ▼
Netlify Functions (Node, TypeScript) ── read-only role ──▶ Neon Postgres
                                                             ▲
Python pipelines (uv, GitHub Actions cron) ── write role ────┘

• Frontend: React 19, Vite 8, React Router 8 (data router, code-split routes), TypeScript (strict). Plain CSS with design tokens and CSS Modules; no Tailwind or CSS-in-JS. The five main pages are prerendered at build time and hydrated in the browser (see Performance).
• API: Netlify Functions in TypeScript. Input is validated with zod; every error uses the shape { error: { code, message } }. Responses send Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400 plus an ETag.
• Database: Postgres on Neon. Plain numbered SQL migrations. Statistics are defined in SQL views, not in the browser.
• Pipelines: Python 3.15, managed with uv. Every pipeline is idempotent, logs its runs and records dataset coverage.
• Shared code: packages/shared holds the API types, schemas and constants used by both the web app and the functions. Unit constants (e.g. troy ounces per tonne) are defined once in config/constants.json and read from TypeScript, Python and SQL.

Repository layout

apps/web/                 React + Vite app
  index.html              Real HTML entry, incl. the no-flash theme bootstrap
  build/                  build steps: the CSP (_headers), page shells with route preloads,
                          sitemap.xml and robots.txt, and the prerender of the main pages
  public/                 favicon (Africa silhouette), boot.js, social images, map topojson, flags
  src/
    app/                  router, layout shell, theme provider, error boundaries
    features/             map, countries, harim, dhahabu, vinara, coverage (data ribbon)
    components/           Icon, IconButton, GlassCard, PageHeader, Tooltip, Drawer, RegionFilter…
    styles/               tokens.css, glass.css, base.css, media.css, fonts.css
    lib/                  strings (i18n dictionary), api client, units (m/ft), storage, theme
packages/shared/          types, zod schemas and constants shared by web + functions
netlify/functions/        API functions (_shared/ holds HTTP and DB helpers)
netlify/tests/            function tests (kept outside functions/ so they never deploy)
db/migrations/            numbered .sql migrations
db/roles.sql              one-time read/write role setup (run in the Neon SQL editor)
db/tests/                 schema and seed tests against PGlite
db/seeds/                 generated, reviewable JSON seeds (committed)
pipelines/                Python package: `python -m pipelines <command>`
scripts/                  build helpers (Material Symbols subsetting, favicon, social images)
config/constants.json     single source of truth for unit constants
e2e/                      Playwright suites (desktop 1440×900, mobile 390×844)
data/source/              the research PDF (raw downloads go to data/raw/, gitignored)
docs/                     statistic definitions (harim-stats.md, dhahabu-stats.md), the Vinara method,
                          and gold and Vinara sources and licences
data/*.md                 review reports: research document, region colours, boundaries, mountains, gold

Prerequisites

Tool	Version	Install (macOS)
Node.js	24 (see .nvmrc; ≥ 24.0)	brew install node@24 or nvm
Python	3.15 (see .python-version)	brew install [email protected]
uv	current	brew install uv
cairo	current (native lib for flag rasterisation)	brew install cairo

On Linux, install libcairo2 instead of cairo.

Getting started (local development)

npm install                     # all JS workspaces
uv sync                         # Python venv for pipelines
npx playwright install chromium # browser for end-to-end tests (one-time)

npm run dev:local               # site + API with the committed seed data: http://localhost:5173

Three ways to run the site locally:

Command	Open	Data
npm run dev:local	http://localhost:5173	The real API handlers on an in-memory Postgres loaded with the committed seeds (e2e/api-server.ts, port 4175), behind Vite's proxy. No database or .env needed. Ctrl+C stops both.
npm run dev:netlify	http://localhost:8888	The Netlify Functions emulator on your Neon database (DATABASE_URL_READ from .env). The CLI injects every .env variable locally, but the functions only ever read DATABASE_URL_READ.
npm run dev	http://localhost:5173	None: the site alone, for layout work. Where data would load, development builds explain which command to run instead.

netlify dev and the production CSP: the build writes the Content-Security-Policy to apps/web/dist/_headers, and Netlify merges <publish>/_headers into its config. Under netlify dev that CSP would block Vite's inline development scripts and leave a blank page, so netlify.toml points publish at apps/web/public in the dev context. Deploys still use apps/web/dist and its CSP (a test guards this).

Local netlify dev quirk: after a 404 from a function, the emulator retries the same path with .html/index.html suffixes (to mimic static-file lookup), so a not-found message may name a suffixed path. Production returns the function's response as is.

The pipelines run from the repo root (uv run python -m pipelines --help); see the next section.

Data: database and pipelines

One-time Neon setup

1. Create a Neon project (one branch for production; optionally a branch per deploy preview).
2. In the Neon SQL editor, as the database owner, run db/roles.sql after replacing its two placeholder passwords. It creates bla_writer (pipelines) and bla_reader (read-only, for the Netlify Functions).
3. Put the connection strings where they belong (see Environment variables): bla_writer → DATABASE_URL_WRITE in your local .env and the GitHub Actions secrets; bla_reader → DATABASE_URL_READ in the Netlify site settings.

First run

Step	Command	What it does
1	uv run python -m pipelines migrate	Applies db/migrations/*.sql in order (checksummed; an applied file that was edited is an error) and grants SELECT to bla_reader
2	uv run python -m pipelines extract-pdf	Research PDF → db/seeds/{countries,sources,datasets}.json and data/review_report.md, with loud validation (54 countries; UN M49 region counts 6/16/9/18/5; the PDF's own headings checked against the document's grouping; unique ISO codes; every summary field present; no stray citation digits)
3	uv run python -m pipelines flags	Downloads the 54 flag SVGs from flagcdn.com (cached in data/raw/flags/, copied to apps/web/public/flags/ as the offline fallback), computes each flag's palette and each region's colour, and writes db/seeds/flags.json and data/region_colors_report.md
4	uv run python -m pipelines boundaries	Natural Earth 4.1.0 (1:50m, via world-atlas 2.0.2) → apps/web/public/geo/africa.topo.json (the 54 countries, Somaliland tagged as Somalia, Western Sahara as disputed) and africa-context.topo.json (neighbouring land, loaded after the countries); computes each country's area on the equal-area Equal Earth projection, a map anchor and whether it needs a circle marker; writes db/seeds/boundaries.json and data/boundaries_report.md
5	uv run python -m pipelines mountains	Builds the Harim catalogue (see Mountain data) → db/seeds/{mountains,mountain_ranges,country_low_points}.json and data/mountains_review_report.md
6	uv run python -m pipelines gold	Builds the Dhahabu data (see Gold data) → db/seeds/gold_*.json, data/gold_coverage_matrix.md and data/gold_review_report.md (needs COMTRADE_API_KEY)

uv run python -m pipelines status prints every dataset's "as of" date, last refresh, cadence and last run (flagging overdue datasets).

migrate --dry-run lists pending migrations. extract-pdf --check validates without writing and fails if the committed seeds are stale; the pytest suite runs it.

Mountain data (Harim)

python -m pipelines mountains (pipelines/africa_pipelines/harim*.py) builds a catalogue covering all 54 countries. Every download is cached under data/raw/ (gitignored), so re-runs are reproducible and offline; --refresh fetches again.

• Sources:
  • the Harim prototype at a pinned commit (harim.html and README.md), which decides which peaks exist;
  • Wikidata: peaks per country, each country's P610 highest point and P1589 lowest point, prominence, isolation and GeoNames IDs (the class IDs used are checked against Wikidata on every run);
  • the CIA World Factbook's final edition (public domain; discontinued in February 2026), via the factbook.json mirror at a pinned commit, as an independent check of every country's highest and lowest point;
  • GeoNames dumps (CC BY 4.0), for elevation cross-checks (surveyed elevations only);
  • Wikipedia, only for curated facts, each quoted;
  • the Smithsonian Global Volcanism Program's volcano numbers, read from Wikidata (P1886) and linked from each volcano (none of the GVP's data is copied).
• Volcanoes: a mountain is a volcano when Wikidata gives it a volcanic class (stratovolcano, shield volcano and others) or the Global Volcanism Program lists it. Many volcanoes (Mount Meru, Ol Doinyo Lengai, Nabro) are typed only as "mountain" in Wikidata, so the class alone would miss them. Older volcanoes the GVP does not list (it covers recent volcanism) are added in the curation file's volcanoes section, each with a quoted source (Mount Kenya: an extinct stratovolcano). Status (active, dormant, extinct) is recorded only where a source states it (a Wikidata class or the curated source); nothing is inferred, so most statuses are unknown.
• Elevation: the value most of the most reliable sources agree on (within 10 m); every other value is kept in elevation_alternatives. Confidence is high when they agree within 10 m, medium within 50 m (or with one reliable source), low otherwise; any disagreement above 10 m, including the prototype's, sets needs_review. Values that bulk-imported Wikidata items copied from GeoNames count as GeoNames.
• Selection: every country high point, every peak of 3,000 m or more, every prototype peak, and up to 8 notable peaks per country. Little-known points within 1.5 km of a mountain, or within a massif's radius, are parts of it, not separate mountains. Territory peaks (Réunion, the Canary Islands, Madeira…) are kept separate.
• Hierarchy: massif → summit, two levels, only where a cited source names the summits (Kilimanjaro → Kibo, Mawenzi, Shira; Mount Kenya → Batian, Nelion, Point Lenana; and others). A massif counts as one mountain and stands exactly as high as its highest summit.
• Range descriptions: 27 of the 30 ranges have a short description (and a formation note, type and length where the source states them), each sourced to its Wikipedia article with exact quotes re-checked every run; the review report lists them. Sinai, the Tunisian Dorsal and Moka have none yet, and their pages say so.

Gold data (Dhahabu)

python -m pipelines gold runs seven steps (pipelines/africa_pipelines/gold_*.py), each also a command of its own. Every download is cached under data/raw/gold/; --refresh fetches again. Sources, licences and the decisions behind them are in docs/dhahabu-sources.md: only sources usable without asking permission are used (the British Geological Survey and the World Gold Council are not).

Step	Source	Output
gold-price	World Bank Pink Sheet, monthly average (IMF PCPS as cross-check and fallback)	gold_price.json: 801 months from 1960
gold-production	USGS Mineral Commodity Summaries 2022–2026 and the Minerals Yearbook country chapters (about 200 workbooks)	gold_production.json: every edition's figures, "included in other" rows, in-ground reserves, and the evidence each chapter gives (notes, artisanal splits, operations)
gold-official-reserves	IMF International Liquidity, one call for the 54 countries	gold_reserves.json: monthly holdings since 2000, valued at each month's price, and who reports late
gold-trade	UN Comtrade (HS 7108 without 7108.20), reported and mirror, 111 calls	gold_trade.json: flows, top 10 partners, total exports
gold-mines	Wikidata	gold_mines.json: candidate mines and the quality-bar verdict (the layer is off: it fails all three checks)
gold-presence	the above, plus db/seeds/gold_presence_overrides.json	gold_presence.json: each country's tier, evidence, confidence and source
gold-profiles	the above, plus db/seeds/gold_profile_notes.json	gold_profiles.json, then validation and the two reports

• Null, zero, "included in other": never coerced into each other. "NA" in a source is no row; "--" is a reported zero; a country inside a source's "Other countries" is included_in_other with no tonnes (and only where the yearbook shows it producing).
• One figure per country-year: v_gold_production prefers a figure over "included in other", a reported figure over an estimate, then the newer edition (gold_production_source_priority), and values it at that year's mean monthly price (empty until all twelve months exist).
• Presence tiers: major producer (≥ 20 t in the latest year with a figure), producer (> 0 t), occurrences known (a cited source documents gold without a current figure), none identified (the USGS chapters consulted show none), unknown (no USGS production table). Trade is never evidence of deposits. Curated overrides and profile notes need a source and the exact quote, which every run re-checks against the source's text (a missing quote stops the run). Seven overrides (Togo, Somalia, Guinea-Bissau, Cabo Verde, The Gambia, São Tomé and Príncipe, Comoros) leave no country "unknown"; 53 curated notes cover 31 countries.
• Validation (the run fails otherwise): every country has a tier; no negative quantities; producers have production evidence; every US dollar value uses the price of its own year or month (never filled); every cited source exists; "none identified" uses the agreed wording.
• Reports: data/gold_coverage_matrix.md (country × metric, with the years available) and data/gold_review_report.md (tiers with their evidence, source conflicts, lumped countries, late reporters, trade gaps, the mines verdict, figures left out, what needs review).
• Database: migration 0007_dhahabu.sql (tables, v_gold_price_annual, v_gold_production, and troy_oz_per_tonne(), which a test checks against config/constants.json). Migration 0008_dhahabu_api.sql adds world production (the MCS world totals) and each central bank's reporting status (gold_reserves_reporting), gold_country_metrics(year) with v_gold_country_latest (each metric's latest value in or before a year, with its own year or date), and v_gold_stats(region, year), the statistics band (definitions in docs/dhahabu-stats.md, which a test keeps word for word in step with the SQL). Migration 0009_dhahabu_charts.sql adds gold_price_effect() and , the split of a change in holdings value into a price effect and a volume effect (they sum exactly to the change, by construction), and the 11th card, "Price effect" (the 0008 function is renamed and adds the card to its ten).

Country indicators (Vinara)

python -m pipelines indicators (pipelines/africa_pipelines/indicators*.py) reads annual figures for the 54 states from 2000. Every download is cached under data/raw/indicators/; --refresh fetches again. What each series is, and its code at the source, is in pipelines/africa_pipelines/reference/indicators_config.json; sources and licences are in docs/vinara-sources.md and the rules in docs/vinara-method.md.

Indicators	Source
Population and its growth, land and surface area, GDP (US$ and PPP), GDP per capita (PPP), real growth, inflation, GNI	World Bank WDI (CC BY 4.0)
Government gross debt (% of GDP)	IMF World Economic Outlook
Military spending (US$ and % of GDP)	SIPRI, read through WDI; only the latest ten years are kept (fair use)
Human Development Index	UNDP Human Development Report (CC BY 3.0 IGO); when UNDP's site does not answer, Our World in Data's copy of the same series
External debt, public external debt, and what is owed to multilateral lenders, governments, bondholders, commercial banks and other private lenders; each creditor's share	World Bank International Debt Statistics (CC BY 4.0)

• One value per country, indicator and year. The World Bank's figure is used where it has one. Where it has none for the year before the IMF's latest WEO edition, the IMF's figure for that year fills it (GDP, GDP at PPP, GDP per capita, growth, inflation), stored as an estimate. Government debt comes from the IMF, whose figure for that year is likewise an estimate. Projections (the edition's year and later) and years not yet ended are refused.
• No data is a missing row, never zero. Countries outside the World Bank's debt reporting (Libya, Namibia, Seychelles, South Sudan) have no debt rows.
• Creditors: the last ten years of public and publicly guaranteed external debt by creditor. A creditor's kind is the series it appears in (multilateral, bilateral, commercial banks, other private); bondholders are one creditor. Creditor amounts are checked against their totals.
• Validation (the run fails otherwise): no duplicate or future observation; estimates only for the year before the edition; every value within a plausible range for its unit; at most ten years of SIPRI data; every indicator has data.
• Reports: data/indicators_coverage_matrix.md (each country's latest year per indicator) and data/indicators_review_report.md (coverage and each indicator's default ten-year window, gaps, the IMF estimates used, where the World Bank and the IMF disagree, SIPRI's years, external debt coverage and the largest creditors, and extreme values to check).
• Database: migration 0011_indicators.sql: indicators (definition, unit, display precision, source code and dataset), indicator_observations (value, reported or estimate, source and edition) and external_debt_creditors.

Leaders and elections (Vinara)

python -m pipelines politics (pipelines/africa_pipelines/politics*.py) reads two Wikipedia lists through the MediaWiki API: List of current heads of state and government and List of next general elections. Sources and licences are in docs/vinara-sources.md; the rules are in docs/vinara-method.md.

• Leaders: the office the list marks as holding executive power comes first, then the other of head of state and head of government where it is a different person. Each is labelled transitional or de facto where the list says so, and carries the Wikidata item read from the person's article. Wikidata's own head-of-state and head-of-government statements are compared, and differences are reported.
• Elections: the next election that decides the executive. That is the presidential election where the executive president is directly elected, otherwise the legislative election. A month or year alone is the list's latest possible date and is stored as its last day, with its precision. election_status() (migration 0012_politics.sql) gives "Election within 12 months", "No election within 12 months" or "No date set" from today's date whenever it is read.
• Curation: pipelines/africa_pipelines/reference/politics_curation.json holds country names as the lists spell them, the executive override for Sudan's collective council, Eritrea's lack of elections, and short notes (Somalia's disputed presidency, Libya's and Sudan's rival authorities, Cabo Verde's acting president, the monarchies). Every note and override rests on quotes from the lists, which each run re-checks.
• Approval: the site shows the snapshot in reference/politics_approved.json. Every run lists the differences from it in data/politics_review_report.md, and load keeps the approved records until politics --approve records new ones. The weekly refresh never approves.
• Database: country_leaders and country_elections, with election_status(next_date, today).

Exchange rates (Vinara)

python -m pipelines fx (pipelines/africa_pipelines/fx*.py) reads rates in local currency per US dollar from 1 January 2020 (the floor for exchange rates) to the day before the run. Sources and licences are in docs/vinara-sources.md (§4, 5 and 12); the reference of currencies, pegs, currency changes and daily sources is pipelines/africa_pipelines/reference/currencies.json.

• Daily, official: one source per currency, stored per currency (states sharing one share its rates).
  • ECB: the rand, and at their official parities the two CFA francs, the Comorian franc, the Cabo Verdean escudo, the dobra, the loti, the lilangeni, the Namibian dollar and the Djiboutian franc (22 states).
  • BIS: Algeria and Mauritius.
  • The state's own central bank, read through Frankfurter (the bank's rates as published, never Frankfurter's blend; one year per request, past years cached): Kenya, Tanzania, Zambia, Angola, The Gambia, Liberia, Malawi, Tunisia and Morocco. A bank is used only when its terms allow reuse or it publishes none; banks whose terms could not be read (Nigeria, DR Congo, Rwanda, Madagascar) or require permission (Botswana, Mozambique, Seychelles) are recorded with that status.
• Monthly: the IMF's Exchange Rates (period average and end of month) for all 54 states. It is the series shown for states without a usable daily source, and the check on every daily one.
  • One unit throughout: each currency change is recorded with its official conversion; the pipeline detects whether the IMF already gives earlier months in the new unit and converts them where it does not (Zimbabwe's ZiG, April 2024), so a change is never read as a gain or a loss.
  • Status: each monthly series is current, late or stale (more than 12 months behind the newest month); months that have not ended are refused.
• Checks (the run fails otherwise):
  • each peg holds against the IMF's own rates in 95% of months (within 1%);
  • each daily series' monthly mean matches the IMF's monthly average in 90% of months (within 1% for fixed currencies and the rand, 2% otherwise);
  • each state's currency, and each changed currency's withdrawal date, is checked against the ISO 4217 lists (SIX for ISO);
  • an unexplained jump across a currency change stops the run.
• Report: data/fx_review_report.md lists, per state, its daily source and span, its monthly span and status, and why a state is monthly only; how each currency change was applied; the peg and daily checks; and every month a currency moved more than 50% against the dollar.
• Database: migration 0014_fx.sql: country_currencies, currency_changes, fx_monthly, fx_daily (with each rate's source) and fx_reporting.

The rankings (Vinara)

Every Vinara rule is computed in the database (migration 0015_vinara.sql), from the indicators and exchange rates above; there is no pipeline step. The rules are in docs/vinara-method.md, and each metric's definition there is word for word the one the database returns (a test keeps them identical).

• vinara_metrics: the 13 ranked metrics, each with how it is measured over the window, which way leads, its precision (values equal at it tie), how a region's figure is made, and its definition.
• v_fx_month: each state's monthly rate on one basis for ranking (the mean of its daily rates where it has them, otherwise the IMF's monthly average).
• vinara_window(metric, from, to): the default window (the last ten complete years) or a range asked for, kept within the data.
• vinara_rankings(metric, region, from, to): the states ranked, with ties sharing a rank; vinara_signal(...): whether the cardinal's lead is narrowing; vinara_region_values(...): each region's figure, its median over states and the share it covers.
• vinara_summary(region, from, to, metric): everything the page needs for each metric in one call. It holds intermediate rankings as JSON rather than temporary tables, so it runs for the read-only API role (a test runs it in a read-only transaction).
• Migration 0016_vinara_speed.sql redefines the per-state and regional functions with the same results, so that each metric runs only the steps it needs: the exchange-rate steps for the two currency metrics, and each regional step for the metrics that use it.
• Migration 0017_vinara_currency_window.sql ends the currency metrics' default window at the latest full year of rates any state has, so they show the latest rates; states without rates for its last month are listed as not ranked.

Region colours

Each region's identity colour is the mode colour across its flags: flags are rasterised, clustered into at most 8 colours in CIELAB, merged across flags (CIEDE2000 < 10) and summed per region; white, black and grey are excluded by default, and near-identical picks are resolved by giving the colour to the region where it has the larger share. Anti-aliasing blends at stripe edges are folded back into the real flag colours first. Every parameter is a command-line option (python -m pipelines flags --help), and --include-neutrals switches which result is selected (both are always reported).

data/region_colors_report.md shows the picks with swatches, the top five candidates per region, every uniqueness decision, both results, per-flag palettes and automated checks (distinctness, colour-vision-deficiency simulation, contrast against the light and dark page). Colours are never adjusted by hand in the computation; an adjustment the owner approves is recorded with its reason in the approval file.

Approval. The approved colours (2026-10-22: Northern #c1272d, Western #55d27a, Central #fcd116, Eastern #006600, Southern #6da9d2) are recorded in pipelines/africa_pipelines/reference/region_colors_approval.json, and load writes only those to regions.color_hex. The file keeps the approved computation separately from the colours in use: Western Africa's computed #009e49 is lightened to #55d27a (same hue) so it stands apart from Eastern Africa's green, and the report names that adjustment with its reason. If a later flags run computes different colours, the approved ones stay in use and the report says the computation differs, until a new approval is recorded there.

Correcting the data

The research document is not fully verified (see data/review_report.md). To correct it:

1. Edit db/seeds/countries.json (or sources.json). For example, fix a summary, set etymology_category, change animal_status, or set needs_review to false once a record is checked.
2. Run uv run python -m pipelines load.

extract-pdf refuses to overwrite seeds you have edited (it compares a content hash recorded at generation time) unless you pass --force.

How the extraction works and where its judgement calls live:

• pipelines/africa_pipelines/reference/african_states.json: canonical names (with diacritics), ISO codes, UN M49 regions (with the research document's own grouping for the five states it files differently), and every label the PDF uses for each country.
• pipelines/africa_pipelines/reference/symbology_curation.json: the reviewed mapping of each country's prose sentences to profile fields, the animal-status decisions with their reasons, the reviewed etymology categories, the known inconsistencies (each marked corrected, status changed or open) and the verified corrections. Each correction replaces or appends exact text, gives its reason and cites the reference source it was checked against; that source is added to sources and cited on the corrected field. If a correction's original text stops matching, extraction fails rather than silently skipping it. The review report lists every correction with its before and after text.
• pipelines/africa_pipelines/reference/source_tiers.json: the reliability tier for each cited website.

Scheduled refresh

.github/workflows/data-refresh.yml runs every Monday at 03:17 UTC (and on demand): migrate → flags --refresh → mountains --refresh, the gold steps and indicators --refresh (first Monday of the month, or on a manual run; gold production only on a manual run), fx --refresh (weekly), politics --refresh (weekly; changes wait for approval) → load → status, then calls the Netlify build hook if load changed any rows. If upstream data changed the generated seeds, the run warns and uploads them (with the colour, mountain, gold, indicator, exchange-rate and politics reports) as the refreshed-data artifact for you to review and commit; the approved region colours are never replaced automatically. Repository secrets: DATABASE_URL_WRITE (required), COMTRADE_API_KEY (for gold trade; without it the step is skipped with a warning) and NETLIFY_BUILD_HOOK (optional).

Local database for tests

Tests never need a database server. Vitest runs the migrations and loads the seeds into PGlite (Postgres compiled to WebAssembly, in-process). pytest starts PGlite's socket server so the Python migration runner is tested over the real Postgres wire protocol.

API

Netlify Functions in netlify/functions/, one file per route, each declaring its route with config.path (functions are matched before redirects; the /api/* → /.netlify/functions/:splat rewrite in netlify.toml remains the catch-all). All responses are JSON; request parameters are validated with zod against the shared contract in packages/shared/src/schemas.ts.

Route	Returns
GET /api/regions	The five UN M49 regions in display order: name, description, approved colorHex, country count
GET /api/countries?region=<slug>&q=<text>	Country summaries (all 54 without parameters): region, flag URLs (Flagpedia SVG, PNG template, self-hosted fallback), short profile fields, animal status, needsReview, and facts from v_country_facts (migration 0013): latest population and land area with their years, leaders (executive first), and the next election with its status as of the request. q matches names, official names and ISO codes, accent-insensitively ("cote" finds Côte d'Ivoire)
GET /api/countries/:iso3	The full profile: long texts, scientific name, review notes and every cited source with its reliability tier and the fields it supports. Unknown or malformed codes are 404
GET /api/coverage?datasets=a,b	Each dataset's provider, licence, attribution, coverage, "as of" date and last refresh; requested keys with no data yet are listed in missing
GET /api/mountains/summary?region=&q=	One row per country (54), highest peak first: the highest peak (with a massif's top summit and the countries it is shared with), number of mountains, mean height, ranges, lowest point and relief
GET /api/mountains?region=&country=&range=&q=&minHeight=&volcanic=&sort=	The catalogue (counted mountains: standalone and massifs, each once; summits are nested in their massif). country lists a shared peak under each of its countries; volcanic=1 any volcano, or active/dormant/extinct/unknown; sort=height (default), -height, prominence (unknown last) or name. territories=1 lists the territory peaks instead; summits=1 adds summits as rows. Returns count, total and capped (the list is capped at 600)
GET /api/mountains/:slug	One mountain: height with its source and every other sourced height, prominence, isolation, coordinates, range, type, volcanic status, massif and summits, local names and name origin (each with its source), notes, review notes and sources by field. Unknown or malformed slugs are 404

• Errors always have the shape { "error": { "code", "message" } }: bad_request (400, invalid query parameters), not_found (404), method_not_allowed (405; only GET and HEAD), service_unavailable (503, database not configured) and internal_error (500; details are logged, never returned).
• Caching: Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400 with a weak ETag (304 on If-None-Match). Errors are no-store.
• Database: the Neon HTTP driver with the read-only bla_reader role (DATABASE_URL_READ); every query is parameterised (netlify/functions/_shared/queries.ts and harimQueries.ts). Search uses the search_fold() SQL function and the v_country_summary view (migration 0002). The Harim routes read v_mountains, v_country_mountain_summary and v_harim_stats() (migration 0004; 0005 adds each height's confidence and other sourced heights to the statistics, and names the region in the lowest point's label). Every statistic's definition and tie rule is in docs/harim-stats.md, word for word as the SQL returns it (a test keeps them identical).
• Vinara reads vinara_summary(), vinara_rankings() and vinara_country_years() (migration 0015) through netlify/functions/_shared/vinaraQueries.ts, which only shapes their rows.
• Routing: /api/mountains/:slug excludes the fixed paths (summary, stats, export, ranges), and a test checks every API path reaches exactly one function.
• Files: a handler may return a ready Response (the export), with the same caching and ETag as JSON.
• Bundling: functions import the shared contract by relative path (_shared/contract.ts), so Netlify's bundler inlines it. npm run check:functions builds the functions exactly as a deploy does and checks every bundle loads and answers.
• Web client: apps/web/src/lib/api.ts (typed by the same contract).

The map

The home page (apps/web/src/features/map/) draws Africa on the Equal Earth projection (d3-geo), fitted to a box from Cabo Verde to Mauritius (far islands such as South Africa's Prince Edward Islands stay reachable by panning).

• Fills use the approved region colours as CSS variables (--region-<slug>), set from /api/regions, with the same colours in tokens.css as no-flash fallbacks (a test keeps them in sync with the approval).
• Borders are one dark line, except between two countries whose region colour is dark (Northern and Eastern Africa today): there the light theme draws a light line, which shows where the dark one would vanish. A fill counts as dark when a light line contrasts with it more than the dark line does (prefersLightLine, lib/colour.ts); the dark theme lifts those fills, so its borders stay dark.
• Dark theme: darkThemePalette() (lib/colour.ts) keeps every hue. It lifts a colour's OKLCH lightness only to reach 3:1 against the dark map ocean (WCAG 1.4.11), then lifts the lighter of any pair closer than ΔE 30 until they separate. With the approved colours this changes only East (#72b6fe) and Southern (#2b5acd).
• Boundaries are drawn once as meshes (borders and coastlines), with thin strokes that stay thin at any zoom. Somaliland is merged into Somalia (no internal line); Somalia's tooltip and profile explain this (declared independence in 1991, self-governing, not recognised by the African Union or UN), and screen readers hear the same note. Western Sahara is hatched, with the tooltip "Disputed territory". A note under the map states that boundaries do not imply endorsement of any claim.
• Small states (under 20,000 km² on the map: Cabo Verde, São Tomé and Príncipe, Comoros, Mauritius, Seychelles, The Gambia, Eswatini) get clickable circle markers. Lesotho (about 30,000 km²) is large enough to click.
• Interaction:
  • Hover or keyboard focus shows a tooltip with the flag, name and region, the population and land area, the leader and the next election with its status; the click popover (a bottom sheet on phones) shows the same facts.
  • Click or tap opens a short profile with "See in table": a popover on larger screens, a bottom sheet on phones. Escape closes it and returns focus.
  • The legend isolates a region (others dim) and links to /countries?region=….
  • Zoom with the + / − / reset buttons, pinch, or Ctrl/⌘ + scroll; drag to pan. One-finger swipes still scroll the page on phones.
• Keyboard: one Tab stop into the map, arrow keys move between countries (alphabetical), Home/End jump, Enter opens. The countries table is the accessible equivalent and is linked under the map.
• Countries fade in by region (instant with reduced motion).

The countries table

/countries (apps/web/src/features/countries/) lists all 54 countries with their flag and region, in two views:

• Symbols (the default): name meaning, national symbol and national animal.

• Facts (?view=facts): population and land area, each with its year; the leader holding executive power (title above the name), then the other of head of state and head of government; and the next election that decides the executive, with its status ("Election within 12 months", "No election within 12 months" or "No date set", computed from today's date). Transitional and de facto leaders are labelled, and an "i" button explains a country's political context (Somalia's disputed presidency, Libya's and Sudan's rival authorities). A month or year alone reads as a deadline ("by Jul 2031").

• Filters live in the URL, so every view can be shared: ?view=facts, ?region=<slug>, ?q=<search>, ?sort=<column> (a leading - sorts descending, e.g. sort=-animal) and ?country=<ISO3> (opens that country's drawer). Invalid values are ignored. Filter changes replace the current history entry rather than adding one.

• Region chips in the region colours, plus "All", each with its country count.

• Search ignores case and accents ("cote" finds Côte d'Ivoire). It matches names, official names, ISO codes, leaders and the symbol columns, so "eagle" finds the countries whose animal is an eagle and "ruto" finds Kenya. The list loads once (shared with the map) and filters instantly; the API's q parameter matches names and codes only.

• Sorting: every column but the flag. Population and land area sort largest first on the first click, and elections soonest first; countries without a figure or a date always sort last. Ties sort by country name; regions sort in their display order (Northern → Southern). Phones get a "Sort by" menu for the view's columns, and cards that expand to the view's fields.

• Flags come from Flagpedia (flagcdn.com, 1x/2x, explicit size, lazy-loaded, self-hosted fallback). Hovering or focusing a flag shows the document's flag text (summary, then the full description); a tap toggles it on touch screens. Escape dismisses it, and it stays inside the viewport.

• Animal status: anything short of official (de facto, inferred, sports nickname, contested) is badged in the table, so inference never reads as fact.

• Drawer: a click on a row (or Enter on the country name) opens the full profile in a modal dialog: a side panel on wide screens, a bottom sheet on phones. It shows the long texts, the etymology category (when assigned), the animal status with its meaning, every source with its reliability tier and the fields it supports, and a "Needs verification" marker that expands to the review notes. Somalia's drawer explains Somaliland. Escape, the close button or a click on the backdrop close it, and focus returns to where it was.

Harim: the mountains page

/harim (apps/web/src/features/harim/) answers "what are Africa's mountains, how high are they, and where are they, country by country?"

• By country (the default): one row per country, highest peak first, with the flag, the region chip, the highest peak (a massif's top summit beneath it, and "Shared with …" for border peaks), its height with a proportional bar, the number of mountains, the ranges, the lowest point and the relief. Click a row (or its name) to expand it to the country's mountains: height in metres and feet, range, type and volcanic status, a confidence badge, "National high point" and "Shared with …" badges, and a massif's summits nested beneath it (it counts as one mountain). "Country profile" opens the country's drawer on /countries.
• All peaks: the whole catalogue as one list, sortable by name, height or prominence (unknown prominence shows "—" and sorts last), with a "Most prominent peaks" preset and an "Ultra-prominent" badge from 1,500 m. Filters: region, country, range, volcanic status and a minimum-height slider.
• Territory peaks (Réunion, the Canary Islands, Madeira…) are listed apart, in a collapsed group loaded on first open, and never counted with the countries.
• Statistics band (features/harim/stats/): nine glass cards under the header, all figures from /api/mountains/stats (computed in the database; definitions in docs/harim-stats.md).
  • Hero cards: mountains catalogued (with countries and territory peaks), volcanic mountains (a bar and legend by status), the tallest mountain (a massif with its top summit, and the flag), and the lowest national high point ("Africa's lowest 'highest point'", never "the shortest mountain").
  • Compact cards: peaks above 4,000 m (a bar and legend of the four height bands), the most mountainous country, the busiest range with its tallest peak, the lowest point and the greatest relief. Ties are listed, each with its own button.
  • Scope: "All Africa", or the selected region as a chip in its colour, always shown above the cards; the figures recompute for the region (the previous figures stay, dimmed, while the new ones load). Screen readers hear the scope with each card's name, and the lowest-point card names the region ("Lowest point in Eastern Africa").
  • Each card does something: open the peak's drawer (tallest, lowest high point), filter All peaks (volcanoes; peaks above 4,000 m from 4,001 m, since the bands are strict; the most mountainous country's peaks of 3,000 m or more; the busiest range's peaks of 3,000 m or more), or open the country's row (lowest point, greatest relief). The page then scrolls to the list. The whole card is the target, through its own button (keyboard and screen readers).

Dhahabu: the gold page

/dhahabu (apps/web/src/features/dhahabu/) covers, for each of the 54 countries, whether gold is found, how much is mined and traded, and how much central banks hold. It is the site's time-series page: the ribbon's year range drives its cards, table, map and charts.

• Reference year: the end of the ribbon's year range. Every card and table figure is the latest in or before it, and shows its own year or month (countries report on different schedules). With the full range the page shows the latest available figures, and the API gets no year. A note above the table says which applies.
• Statistics band (GoldStatsBand.tsx, from /api/gold/stats; definitions and tie rules in docs/dhahabu-stats.md): eleven glass cards, each with a year or month chip, the definition behind "How is this calculated?", count-up (none with reduced motion) and an action.
  • Hero cards: gold-producing countries (of 54, with a segmented bar and legend by presence tier), Africa's mine production (tonnes, share of world output, change from the previous year), its value (computed at that year's average price, labelled so) and the largest producer (with its share).
  • Compact cards: central bank gold held (tonnes and value, with how many countries report), the largest holder (value and share of its reserves), the gold price ("monthly average, not live", with the change on a year earlier), the most gold-dependent exporter, the biggest reporting gap (neutral wording: "not evidence of wrongdoing"), the largest net buyer over 12 months ("No net buyer" when no holding grew) and the price effect (how much of the 12-month change in the value of central bank gold came from the price, and how much from tonnes bought or sold; "See the holdings chart").
  • Production uses the latest complete year: a year counts for Africa only when the producers missing from it (nearest figure within three years) make up at most 5% of the total, so Africa's total is never a partial sum. With the current data that is 2021: the USGS chapters stop around 2021–2023, and later years cover only the producers the MCS names.
  • Actions: "Sort by production" or "Sort by holdings" sorts the table and scrolls to it; "Show the country" clears any search or presence filter hiding the country, then highlights its row and moves focus to it.
  • Layout: from 1280px the four hero cards, then the compact cards four to a row (the price effect takes two places, so the rows end evenly); 720–1279px three columns (the first card spans two, so four rows fill evenly); phones a scroll-snap carousel with dots. Long figures ("US$36.8 bn", "4.79 million oz") scale down to fit their card.
• Country table (from 1024px; GoldTable.tsx): flag, country with region chip, presence badge, mine production, gold exports, central bank gold and share of exports. A click on a row (or its name, the keyboard way) opens the country's drawer. The headers sort (production, exports, holdings and share largest first, name A–Z; again to reverse; no data always last).

Vinara: the cardinals of Africa

/vinara (apps/web/src/features/vinara/; Vinara is Swahili for "leaders") names, for each of 13 measures, the cardinal (the leading state) and the silent contender (the runner-up), in Africa or in one UN M49 region, and says whether the cardinal's lead is narrowing. Every ranking, window and signal comes from /api/vinara (computed in the database; rules in docs/vinara-method.md); the page only counts and lays out what it returns.

• Scope: "All" (Africa) or one of the five regions, as chips in the region colours (?region=).
• Years: by default each measure covers its own last ten complete years, and the ribbon reads "Last 10 complete years". A range chosen in the ribbon (?from=&to=) applies to every measure, each keeping to the years it has data for; a range left open at the end runs to each measure's latest complete year. A line above the cards says which applies.
• Summary cards (VinaraStatsBand.tsx): most cardinal titles, the leading region (Africa only), gaps closing, contenders ahead in the last year, and elections within 12 months, each with its definition behind "How is this calculated?" (the text of the method's "summary cards" section, kept identical by a test). Phones show them as a carousel.
• Cardinals and silent contenders (VinaraTable.tsx): one row per measure with its years, how many states are ranked, the cardinal and the contender (flag, name, value at the measure's precision, and the year for levels), and the signal: Gap closing (highlighted), Lead holding, Not enough data, or no signal for a tie. Every state in a tie is named. IMF estimates are labelled, and a contender ahead in the window's last year is said in words. Each measure's definition and each signal's meaning show on hover, focus or tap. Below 1024px, one card per measure.
• Region against region (Africa only, RegionComparison.tsx): the leading region and the runner-up for each measure with their figures, and the regions shown as partial (with the share covered), which are not ranked.
• Export CSV (VinaraExport.tsx): every measure's ranking for the scope and years from /api/vinara/export, with a message confirming the download or reporting a failure.
• One measure in detail (MeasureDetail.tsx, ?metric=; from /api/vinara/metrics/:key): the measure's definition and years, then two charts.
  • The leaders year by year (charts/LeadersChart.tsx): the cardinal's and the contender's yearly figures as two lines (the first two categorical colours, a legend and direct labels), with hollow points for IMF estimates, a crosshair tooltip by year and the figures as a table. A tie at the top or for second place has no two lines to follow, and says so.
  • Every state ranked (charts/RankingBars.tsx): horizontal bars from zero, so a currency's loss runs left; the cardinal and the contender in colour and the rest neutral. The top ten show first, then all on request. Hover, focus or tap shows the rank and figure with "Open the state", and the figures are also a table.

The data ribbon and time range

The strip at the top of every page (apps/web/src/features/coverage/) shows the data behind the current view.

• Route config: each route declares its datasets and whether its data is a time series in its handle (ROUTE_DATA in app/router.tsx). The ribbon fetches /api/coverage for exactly those datasets (one cached request, shared with the time range).
• Summary line: the kind (reference data or time series), "as of" (the newest date among the datasets), each dataset's short label (with its covered range on time-series pages, e.g. Gold price: Jan 1990–Sep 2026) and "Refreshed 2 days ago" (the latest pipeline run). Datasets with no row yet show "(not loaded yet)". Phones show one line; the arrow opens the details.
• Details: for each dataset its full name, "as of", covered range, update cadence, last refresh (date and how long ago), provider and licence.
• Dates are calendar dates formatted in UTC (14 Oct 2026), so no time zone shifts them. Ranges use the dataset's granularity from its cadence: months (Sep 2026), quarters (Q2 2026) or years (2024).
• Date-range control: read-only on reference pages ("Not time-dependent", with the explanation on hover, focus or in the details). On time-series pages (/dhahabu, /vinara) it is a year picker with presets (last 5 years, last 10 years, since 2000, all years) and From/To lists. It is bounded by the data's coverage and never goes beyond it. With no data loaded it shows "No data yet" instead of inventing a range.
• URL: the range lives in ?from=&to= (years). The full coverage is the default and leaves no params (a route with its own default years, ownDefault in its handle, uses the last ten years of its coverage instead and the control names that default); values outside the data are clamped and a reversed range is put in order, so shared links always resolve to a valid range. Reference pages ignore the params.

For time-series views (Dhahabu, Vinara, and any later one):

const { interactive, bounds, range, referenceYear, isDefault, setRange } = useTimeRange();
// range: { start, end } years for charts; referenceYear (= range.end) for tables, maps and cards.

To add a dataset, add its key to DATASET_KEYS (packages/shared/src/datasets.ts), give it a short label in strings.datasets, and list it in the route's handle. Its coverage then appears in the ribbon and, for series, extends the range's bounds.

Performance

The target is Lighthouse ≥ 90 on mobile for Performance, Accessibility, Best Practices and SEO on /, /countries, /harim, /dhahabu and /vinara (npm run lighthouse).

• Prerendered first views: the build renders each main page's first view (the layout, header, controls and loading skeletons, before any data) into its HTML file: npm run build runs the client build, a server build of src/entry-server.tsx and build/prerender.ts. The page paints as soon as its CSS arrives instead of after the app's script has run.

• Hydration, not a second render: on a bare URL the app hydrates that markup (hydrateRoot, after loading the matched route's code-split module, app/hydration.ts), so the painted page is kept. The first browser render must therefore equal the prerendered one: anything the server cannot know (the screen, the theme, <body> portals) uses useSyncExternalStore with a server snapshot or useIsClient, and settles straight after hydration. A URL with a query (filters, an open drawer) renders afresh instead, since its first view differs. An e2e test fails on any hydration error.

• The app starts after the first paint: a prerendered page loads /boot.js, which imports the app's entry once the page has painted, so the styles and fonts get the connection first; each page links its route's stylesheets directly. Pages without prerendered markup (peak and range pages, any other path via app.html) load the app's module and preload their route's chunk in the usual way.

• No layout shift: the skeletons reserve the loaded cards' heights and choose carousel or grid in CSS; region chips show their names (REGION_NAMES, checked against the seed) with counts pending until the data arrives.

• Payload: routes are code-split; the map's context land loads after the countries; Material Symbols is subset to the icons used (≈24 KiB); fonts are self-hosted Latin subsets; API time series are capped and pre-aggregated in SQL; images have explicit dimensions; flagcdn.com is preconnected.

• Measured on the live site (LIGHTHOUSE_URL=https://baralaafrika.netlify.app npm run lighthouse, mobile, 2026-10-21):

  Page	Performance	Accessibility	Best Practices	SEO	LCP
  /	92	100	100	100	1.1 s
  /countries	98	100

Quality checks

Command	What it runs
npm run check	ESLint + Stylelint, Prettier (check), tsc -b, Vitest, production build: the same steps as CI's web job
npm run lint / npm run typecheck / npm test / npm run build	individually
npm run format / npm run format:check	Prettier
npm run check:functions	Builds the Netlify Functions as a deploy does and checks each bundle loads and answers
npm run e2e	Playwright: desktop (1440×900) and mobile (390×844) projects; includes axe accessibility checks in light and dark mode and no-horizontal-scroll checks at 320px. It runs the real API handlers (e2e/api-server.ts) on an in-memory Postgres loaded with the committed seeds, proxied behind vite preview, so no Neon connection is needed
npm run screenshots	Captures every page at desktop and mobile, light and dark, into screenshots/ (gitignored) for visual review
npm run lighthouse	Lighthouse (mobile) on /, /countries, /harim, /dhahabu and /vinara against the production build (run npm run build first) and the local API; fails below 90 in any category; HTML and JSON reports in lighthouse/ (gitignored). LIGHTHOUSE_URL=https://… npm run lighthouse audits a deployed site instead
uv run ruff check . && uv run ruff format --check .	Python lint and format
uv run mypy	Python type-check (strict)
uv run pytest	Python tests (needs npm install for the PGlite-backed database tests)

Vitest also checks the repository itself: scripts/gitignore.test.ts fails if .gitignore hides any source file, and scripts/netlifyConfig.test.ts keeps the production CSP out of netlify dev.

CI (.github/workflows/ci.yml, Ubuntu 24.04) runs the web checks (npm run check and check:functions), the Playwright suites and the Python checks on every pull request and every push to main. Runs on a pull request cancel that PR's older run; runs on main always complete. npm run screenshots and npm run lighthouse are run by hand.

Environment variables

Copy .env.example to .env for local work. Each variable belongs in exactly one place:

Variable	Where it lives	Used by
DATABASE_URL_READ	Netlify site environment variables (and local .env for npm run dev:netlify)	Netlify Functions (read-only DB role)
DATABASE_URL_WRITE	local .env, GitHub Actions secret	Python pipelines only
COMTRADE_API_KEY	local .env, GitHub Actions secret	gold-trade pipeline only
ENABLE_WGC_IMPORT	local .env (default false)	reserved for an optional manual WGC import, not built while the WGC is not used
NETLIFY_BUILD_HOOK	GitHub Actions secret (optional)	data-refresh workflow

Functions never hold write credentials, and no secret is ever exposed to the client bundle.

Deployment (Netlify)

netlify.toml configures:

• the build: npm run build, publishing apps/web/dist
• functions from netlify/functions
• the /api/* → /.netlify/functions/:splat redirect and the SPA fallback (/* → /app.html, the plain app; index.html is the prerendered home page, and each page with a shell is served from its own flat file first, e.g. /harim from harim.html, which Netlify serves without a trailing-slash redirect)
• security headers: HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, COOP
• cache headers: one-year immutable for hashed assets, revalidate for HTML

The Content-Security-Policy is generated at build time into dist/_headers by apps/web/build/securityHeaders.ts. It allows exactly the inline theme-bootstrap script, by SHA-256 hash, and blocks every other inline script. A unit test keeps the hash in sync with index.html.

The build also writes sitemap.xml (every page with a shell) and a robots.txt that points to it, using the deploy's address (URL, or DEPLOY_PRIME_URL for previews); local builds have no address and skip the sitemap.

The live site is https://baralaafrika.netlify.app, built from main on every push.

From clone to deployed site

1. Database (once): create the Neon project, run db/roles.sql and set the connection strings as in One-time Neon setup.
2. Data (once, then on schedule): from your machine, with DATABASE_URL_WRITE and COMTRADE_API_KEY in .env, run uv run python -m pipelines migrate, then uv run python -m pipelines load (it loads the committed seeds; regenerate them first with the pipeline commands in First run if you want fresh data). uv run python -m pipelines status shows each dataset's freshness.
3. Netlify site (once): npx netlify login, then npx netlify init in the repository (or create the site in the Netlify UI from the GitHub repository). The build settings come from netlify.toml, so leave the UI fields empty.
4. Environment variables: in Site configuration → Environment variables, add DATABASE_URL_READ (the bla_reader connection string), scoped to Functions. Nothing else belongs on Netlify: DATABASE_URL_WRITE and COMTRADE_API_KEY are pipeline secrets (local .env, GitHub Actions).
5. Deploy: push to the production branch (Netlify builds every push), or from your machine run npx netlify deploy --build for a draft URL and npx netlify deploy --build --prod for production.
6. Check: open the site and /api/regions (it should list five regions), then run LIGHTHOUSE_URL=https://<site> npm run lighthouse.
7. Scheduled refresh: in GitHub → Settings → Secrets and variables → Actions, add DATABASE_URL_WRITE, COMTRADE_API_KEY and (optional) NETLIFY_BUILD_HOOK. .github/workflows/data-refresh.yml then refreshes the data weekly and monthly, and triggers a rebuild when something changed.

Netlify badge: on its free plan Netlify injects a "Powered by Netlify" badge script. The site's Content-Security-Policy blocks its inline script (a console error that costs Best Practices points), so the badge is turned off in the Netlify project settings.

Deploy previews work out of the box: every pull request gets its own URL, and its functions read DATABASE_URL_READ. To keep previews off production data, create a Neon branch for previews and set a different DATABASE_URL_READ for the Deploy previews context in the Netlify UI.

Refreshing data by hand: run the pipeline for a dataset (e.g. uv run python -m pipelines gold-price), review the seed diff, commit it, then uv run python -m pipelines load. The site reads the database at request time (cached for an hour at the CDN), so no rebuild is needed for data. Rebuild only when page shells or the prerender should change (new peaks or ranges).

Adding a dataset or tab: add the dataset's key to DATASET_KEYS and a label in strings.datasets, a migration for its tables, a pipeline command that writes a committed seed, and a TableSpec in the loader. For a new tab, add its route (lazy module) and handle in app/router.tsx, its navigation entry, a function per API route (registered in netlify/tests/functionRoutes.ts), and, to prerender it, an entry in PRERENDERED (build/prerender.ts) and ROUTE_MODULES (build/pageShells.ts).

Design system

• Tokens: apps/web/src/styles/tokens.css defines typography, spacing, radii, motion, layers and colours (OKLCH). The light set is on :root and the dark set on [data-theme='dark'].
• Liquid glass: the .glass / .glass--strong classes in glass.css combine a translucent tint, backdrop blur and saturation, a 1px specular gradient edge, an inner highlight and a depth shadow, layered over an ambient colour mesh. Fallbacks:
  • a near-opaque surface when backdrop-filter is unsupported or prefers-reduced-transparency is set
  • a solid surface with a solid border for prefers-contrast: more
• Typography: self-hosted Fraunces (display, with an optical-size axis) and Instrument Sans (text), Latin subsets. Numbers use tabular figures.
• Breakpoints: 480 / 720 / 1024 / 1280 / 1440 px, defined once as @custom-media in media.css (compiled by PostCSS) and mirrored in lib/breakpoints.ts. A test keeps them in sync.
• Icons: Google Material Symbols (Outlined) via <Icon name="…" />, which is aria-hidden by default. Icon-only buttons use <IconButton label="…" />. The font is subset to the icons in components/Icon/iconNames.ts (≈20 KiB instead of 4 MB) by uv run python -m scripts.build_icon_font. The script fails if a name is not in the current canonical Material Symbols set. Re-run it after editing the list; a test fails if the subset is stale.
• Theme: follows prefers-color-scheme until the user toggles it. The choice persists in localStorage (failures are tolerated) and is applied before first paint by the inline script in index.html, so there is no flash.
• Strings: all UI copy lives in src/lib/strings.ts, ready for translation.
• Signature: every page ends with "© {year} Michael Maina Mwangi. All rights reserved." and "Proudly built in Kenya." with the self-hosted Kenyan flag (SiteFooter.tsx). The year comes from the visitor's clock, so it never goes stale.
• Favicon: a dark-filled silhouette of Africa (mainland and Madagascar), built from the site's own Natural Earth boundaries (public domain) by node scripts/build-favicon.mjs. The SVG switches to a light fill when the browser uses a dark colour scheme, so it stays visible on dark tab strips; (16/32/48 px) is the fallback. The script also stamps the icon links in with , so browsers that cached an older icon for the same address (another project on , or a previous deploy) fetch the new one; a test checks the stamp is current. Material Symbols has no Africa icon. The home page's tab reads just "Bara La Afrika".

Decisions and trade-offs

Decisions taken where the project brief (africa-explorer-claude-code-prompt.md) left room, or where the current ecosystem required it:

• TypeScript 6.0, not 7.x: typescript-eslint (needed for type-aware linting) supports TypeScript < 6.1 only.
• ESLint 10 with eslint-plugin-jsx-a11y: the plugin's declared peer range stops at ESLint 9, which is no longer supported upstream. It was verified to work under ESLint 10, and a scoped overrides entry in package.json records this.
• jsdom 29: jsdom 30 requires Node ≥ 24.15.
• npm workspaces, since pnpm is not assumed.
• packages/shared is a small addition to the specified layout, so the web app and functions share one set of types and schemas.
• Charts: hand-written React SVG with small, tested scale and path helpers (no charting library, not even d3-scale). This keeps the bundle smaller, themes charts directly from CSS tokens, and gives full control of focus, ARIA and data-table fallbacks. The map uses d3-geo and d3-zoom.
• Prerendered pages hydrate only on a bare URL: a URL with a query (filters, an open drawer, a map metric) renders afresh over the prerendered markup, since its first view differs; the page still paints early. Peak and range pages are not prerendered (about 380 pages of mostly data): they keep their link-preview shells and render in the browser.
• The app starts after the first paint on prerendered pages (public/boot.js). On a slow connection the page is readable a little before it is interactive, in exchange for an early, stable first paint (and LCP).
• Lighthouse locally: npm run lighthouse serves the production build with vite preview and the seed-backed local API, so its figures are a floor for the deployed site; LIGHTHOUSE_URL measures a deploy.
• Flat page files: each page with its own HTML is a flat file (harim.html, harim/peaks/<slug>.html), because Netlify answers a folder's index.html with a redirect to a trailing-slash URL.
• CI on a pinned runner: the workflows use ubuntu-24.04 rather than ubuntu-latest, so a new image cannot change system packages unannounced; astral-sh/setup-uv is pinned by commit (it publishes no floating major tag).
• Icon substitutions: terrain is now only a legacy alias of landscape, and filter_hdr is not in the current canonical set. They are replaced by landscape_2 and mountain_flag where the specification suggested them.

Scope and future work

The site covers the four sections above. Each was built against review gates on the data and the design (region colours approved 2026-10-15; the Dhahabu sources decided and its data reviewed 2026-10-18), and the review reports in data/ record what was checked.

Planned, not built:

• Harim, "Ice and fire": glacier extent over time (Kilimanjaro, Mount Kenya, the Rwenzori) and eruption histories, driven by the ribbon's year range. It starts with a data assessment of the candidate sources (the Smithsonian Global Volcanism Program, GLIMS and the Randolph Glacier Inventory, published ice-extent studies), and sparse records will be shown as dated points, never interpolated.
• Harim: protected areas and UNESCO World Heritage mountain sites; an elevation-zones infographic; a west-to-east skyline chart; hillshade or 3D terrain; a "which is taller?" quiz; peak photos, climbing routes and first-ascent history.
• Dhahabu: gold demand, jewellery and investment flows (including ETFs); company-level production and ownership data; artisanal-mining formalisation and responsible-sourcing indicators; a standalone page per country; inflation-adjusted values. Forecasts and investment advice will never be added.
• Vinara: a composite ranking of states and regions, once enough measures are in place that no single one dominates it.
• General: the History section; historical timelines; user accounts; a CMS; multi-language content; long-form search; offline/PWA support.

Credits and licences

Credits are shown in the site footer and in data exports, including the attribution wording required by GeoNames (CC BY 4.0) and the IMF. Sources: the project's state-symbology research document, Natural Earth, Flagpedia, Material Symbols (Apache 2.0), Fraunces and Instrument Sans (SIL OFL 1.1), Wikidata (CC0), GeoNames (CC BY 4.0), the CIA World Factbook's final edition (public domain), Wikipedia (CC BY-SA 4.0, cited per item), the Harim prototype, the IMF, USGS, the World Bank and UN Comtrade, and for Vinara SIPRI (military spending, under its terms for non-commercial use of a small part of the database), UNDP (CC BY 3.0 IGO), the ECB, the BIS and the central banks of Kenya, Tanzania, Zambia, Angola, The Gambia, Liberia, Malawi, Tunisia and Morocco (read through Frankfurter). Each is credited with its required wording in the footer and in the Vinara export. The Smithsonian Global Volcanism Program is linked for reference only; none of its data is republished. The British Geological Survey and the World Gold Council are neither used nor linked (decided 2026-10-18).

Boundaries are shown as published by Natural Earth and do not imply endorsement of any border or territorial claim.