Río Negro Basin Explorer

English · Español

Live: https://basinexplorer.vercel.app/ (hub with two explorers: /rionegro and /cordoba)

---

English

An interactive satellite explorer of the Río Negro basin in northern Patagonia (Limay, Neuquén and Río Negro). The map shows only the river system and a strip of land around it. Click a river, a reach or a sub-basin to open a panel with its metrics. The UI is in English and Spanish. Inspired by Amazon Basin Explorer.

The same app serves more regions, one per path, sharing every component. The Río Negro basin (nqn, at /rionegro) and Córdoba (cba, at /cordoba, covering the Primero to Quinto rivers and Mar Chiquita) are both live (see regions/cba/README.md).

Features

• Rivers from HydroRIVERS: smaller streams appear as you zoom in. Perennial and non-perennial streams (GIRES) can be shown or hidden separately.
• Visible Land slider: six levels of land around the rivers, from 4.6% to 100% of the basin.
• Panels for named rivers, unnamed reaches and sub-basins: length, elevation, gradient, Strahler order, discharge, flooded area, lakes, population and dam regulation.
• Sub-basin hierarchy (levels 1–4) with a tree selector and breadcrumbs.
• IGN names and detail lines, lakes and reservoirs, dams, and OSM localities.
• Search by name (typos and missing accents tolerated), or by a HydroRIVERS HYRIV_ID. Every view can be shared by its URL.
• Ask in the search bar: type a question ("Which is longer, Caleufú or Agrio?", "longest tributary of the Limay") and a card under the bar answers it with values read from the data, their source and the modeled-data caveat. An LLM only picks the rivers and the measure; it never writes numbers.
• km/mi toggle, dark/light theme, minimap, PNG snapshot export, mobile bottom sheet.

Modeled data. HydroATLAS values are modeled estimates, each for its own period. Discharge is a natural long-term average for 1971–2000 and does not reflect today's dam regulation. Population is a 2010 estimate (GPWv4). Flooded area comes from 1993–2004 satellite data (GIEMS-D15). Dam regulation is based on GRanD v1.1. The app states this wherever these values appear.

Architecture

Sources (HydroSHEDS, HydroLAKES, GIRES, IGN, OSM)
   │  pipeline/  — TS steps running DuckDB + tippecanoe, each writes a report.json
   ▼
public/tiles/<region>/*.pmtiles (geometry)      data/out/<region>/*.ndjson → npm run seed → MongoDB Atlas (metadata)
   │ HTTP Range                                                           │
   ▼                                                                      ▼
MapLibre GL in the browser ── click → feature id → /api/* route handlers (CDN-cached)

• Geometry and metadata live apart. Geometry ships as static PMTiles vector tiles. Every tile feature carries an id that matches a MongoDB document, so a click on the map fetches that feature's panel data.
• No separate backend. MongoDB is read only from Next.js Server Components and Route Handlers. The app's database user is read-only.
• State: Zustand, kept in sync with the URL (?r=<river>, ?reach=<HYRIV_ID>, ?s=<subbasin>).
• i18n: next-intl. The locale is stored in a cookie, so URLs carry no locale prefix.

Stack

Next.js 16 (App Router) · React 19 · TypeScript (strict) · Tailwind CSS 4 · MapLibre GL + PMTiles · Zustand · next-intl · MongoDB Atlas · zod · DuckDB · tippecanoe · Vitest · Playwright · Vercel

Getting started

Requires Node 24.

npm ci
cp .env.example .env.local   # fill in MONGODB_URI, MONGODB_DB and the imagery variables
npm run seed -- --region nqn # loads data/out/<region>/*.ndjson into MongoDB (idempotent)
npm run dev

Command	What it does
npm run dev	Development server
npm run check	Typecheck, lint, format check and unit tests
npm run test:e2e	Playwright screenshot tests
npm run pipeline:<step> -- --region <id>	One data pipeline step for one region (see pipeline/README.md)
npm run seed -- --region <id>	Upserts a region's NDJSON outputs into MongoDB
npm run atlas:check -- --region <id>	Verifies that the app's Mongo user can only read

Rebuilding the data needs tippecanoe on your PATH. DuckDB is installed by npm ci. The full pipeline order and its prerequisites are in pipeline/README.md.

Repository layout

app/[region]/ pages, /attributions, /api/{rivers,reaches,subbasins,search,health,ask} (one region per host, proxy.ts)
components/   map, panels, controls, search, mobile sheet
lib/          mongo.ts, data/ (schemas, queries), map/ (style, mask, minimap), store.ts, url-state.ts
messages/     shared en.json, es.json
regions/      region registry (index.ts, hosts.ts) and one folder per region: configs, messages/, content.ts
pipeline/     data pipeline steps, SOURCES.md
scripts/      seed, Atlas check, OG shapes
public/tiles/<region>/ PMTiles archives (committed)

Project docs: PLAN.md (phases and status) and DECISSIONS.md (dated decisions).

Data and licenses

Data comes from HydroSHEDS (HydroRIVERS, RiverATLAS, HydroBASINS), HydroLAKES, GIRES, IGN (Argentina) and OpenStreetMap. Satellite imagery is EOxCloudless 2024 (CC BY-NC-SA 4.0), so the site is non-commercial. Full licenses and citations are in pipeline/SOURCES.md and on the app's /attributions page.

This is the beginning of the README. Read the rest at the original. Read the full README ↗