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.
The ask box uses Groq (openai/gpt-oss-20b) when LLM_PROVIDER is set, with Upstash Redis for the
rate limit and cache. Free-tier prompts may be logged or used by the provider; Gemini's free tier
uses prompts to improve Google's products and may not serve EEA/UK/CH users. Details in
pipeline/SOURCES.md.
Español
Un explorador satelital interactivo de la cuenca del Río Negro, en el norte de la Patagonia
(Limay, Neuquén y Río Negro). El mapa muestra solo la red de ríos y una franja de tierra a su
alrededor. Al hacer clic en un río, un tramo o una subcuenca se abre un panel con sus métricas. La
interfaz está en español e inglés. Inspirado en Amazon Basin Explorer.
La misma app sirve más regiones, una por ruta, compartiendo todos los componentes. La cuenca del
Río Negro (nqn, en /rionegro) y Córdoba (cba, en /cordoba, que abarca los ríos Primero a
Quinto y Mar Chiquita) están publicadas (ver regions/cba/README.md).
Funcionalidades
- Ríos de HydroRIVERS: los cursos más chicos aparecen a medida que se hace zoom. Los cursos
permanentes y no permanentes (GIRES) se pueden mostrar u ocultar por separado.
- Slider Visible Land: seis niveles de tierra alrededor de los ríos, del 4,6% al 100% de la
cuenca.
- Paneles de ríos con nombre, tramos sin nombre y subcuencas: longitud, altitud, pendiente, orden
de Strahler, caudal, área inundable, lagos, población y regulación por represas.
- Jerarquía de subcuencas (niveles 1 a 4), con selector en árbol y breadcrumb.
- Nombres y líneas de detalle del IGN, lagos y embalses, represas y localidades de OSM.
- Búsqueda por nombre (tolera errores de tipeo y tildes faltantes) o por
HYRIV_ID de
HydroRIVERS. Cada vista se puede compartir con su URL.
- Preguntas en la barra de búsqueda: escribí una pregunta ("¿Qué río es más largo, Caleufú o
Agrio?", "el afluente más largo del Limay") y una tarjeta bajo la barra la responde con valores
leídos de los datos, su fuente y la advertencia de datos modelados. Un LLM solo elige los ríos y la
medida; nunca escribe números.
- Unidades km/mi, tema oscuro/claro, minimapa, exportación a PNG y panel inferior en móvil.
Datos modelados. Los valores de HydroATLAS son estimaciones modeladas, cada una de su propio
período. El caudal es un promedio natural de largo plazo de 1971–2000 y no refleja la regulación
actual de las represas. La población es una estimación de 2010 (GPWv4). El área inundable viene
de datos satelitales de 1993–2004 (GIEMS-D15). La regulación por represas se basa en GRanD v1.1.
La app lo indica en cada lugar donde aparecen estos valores.
Arquitectura
Fuentes (HydroSHEDS, HydroLAKES, GIRES, IGN, OSM)
│ pipeline/ — pasos en TS con DuckDB + tippecanoe; cada uno escribe un report.json
▼
public/tiles/<region>/*.pmtiles (geometría) data/out/<region>/*.ndjson → npm run seed → MongoDB Atlas (metadatos)
│ HTTP Range │
▼ ▼
MapLibre GL en el navegador ── clic → id del feature → route handlers /api/* (con caché de CDN)
- La geometría y los metadatos están separados. La geometría se sirve como tiles vectoriales
PMTiles estáticos. Cada feature lleva un id que coincide con un documento de MongoDB, así que un
clic en el mapa pide los datos del panel de ese feature.
- Sin backend aparte. MongoDB se lee solo desde Server Components y Route Handlers de Next.js.
El usuario de base de datos de la app es de solo lectura.
- Estado: Zustand, sincronizado con la URL (
?r=<río>, ?reach=<HYRIV_ID>, ?s=<subcuenca>).
- i18n: next-intl. El idioma se guarda en una cookie, así que las URLs no llevan prefijo de
idioma.
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
Cómo empezar
Requiere Node 24.
npm ci
cp .env.example .env.local # completar MONGODB_URI, MONGODB_DB y las variables de imágenes
npm run seed -- --region nqn # carga data/out/<region>/*.ndjson en MongoDB (idempotente)
npm run dev
| Comando | Qué hace |
|---|
npm run dev | Servidor de desarrollo |
npm run check | Typecheck, lint, chequeo de formato y tests unitarios |
npm run test:e2e | Tests de capturas con Playwright |
npm run pipeline:<step> -- --region <id> | Un paso del pipeline de datos para una región (ver pipeline/README.md) |
npm run seed -- --region <id> | Hace upsert de los NDJSON de una región en MongoDB |
npm run atlas:check -- --region <id> | Verifica que el usuario de Mongo de la app solo lea |
Para regenerar los datos hace falta tener tippecanoe en el PATH. DuckDB se instala con npm ci.
El orden completo del pipeline y sus requisitos están en pipeline/README.md.
Estructura del repositorio
app/[region]/ páginas, /attributions, /api/{rivers,reaches,subbasins,search,health,ask} (una región por host, proxy.ts)
components/ mapa, paneles, controles, búsqueda, panel móvil
lib/ mongo.ts, data/ (esquemas, consultas), map/ (estilo, máscara, minimapa), store.ts, url-state.ts
messages/ en.json, es.json compartidos
regions/ registro de regiones (index.ts, hosts.ts) y una carpeta por región: configuración, messages/, content.ts
pipeline/ pasos del pipeline de datos, SOURCES.md
scripts/ seed, chequeo de Atlas, formas para la imagen OG
public/tiles/<region>/ archivos PMTiles (commiteados)
Documentación del proyecto: PLAN.md (fases y estado) y DECISSIONS.md
(decisiones fechadas).
Datos y licencias
Los datos vienen de HydroSHEDS (HydroRIVERS, RiverATLAS, HydroBASINS), HydroLAKES, GIRES, IGN
(Argentina) y OpenStreetMap. Las imágenes satelitales son EOxCloudless 2024 (CC BY-NC-SA 4.0), por
lo que el sitio es no comercial. Las licencias y citas completas están en
pipeline/SOURCES.md y en la página /attributions de la app.
La caja de preguntas usa Groq (openai/gpt-oss-20b) cuando LLM_PROVIDER está definido, y Upstash
Redis para el límite de pedidos y la caché. En los planes gratuitos, el proveedor puede registrar o
usar las preguntas; el plan gratuito de Gemini las usa para mejorar los productos de Google y no
puede atender a usuarios del EEE, Reino Unido o Suiza. Detalles en
pipeline/SOURCES.md.
