About This Project

FloodRisk (Floods Argentina) is a civic-focused hydrological risk platform for Tucumán, Argentina. It brings together observed rainfall, river and station data, official alerts, and forecast signals into one responsive map and information hub—built for clarity under stress, SEO, and day-to-day operability.

Featured in the press

This project was highlighted by a leading local newspaper in Tucumán for its contribution to flood awareness and public safety. Read the article.

The project started from a concrete need: make flood-relevant information easier to discover and interpret for residents and partners, without hiding methodology or sources. The public app emphasizes locality-centric views, transparent data provenance, and separation between measured hydrometric data and model-based outlooks (for example river flood outlooks when the Google Flood Forecasting API is enabled), so users are less likely to confuse a forecast with an on-the-ground reading.

Key features

• Next.js App Router & technical SEO — Server-rendered pages, shared metadata helpers, sitemap and robots, and canonical URLs driven by environment configuration so discovery and sharing stay consistent across deployments.


• Interactive provincial map — Leaflet-based map with locality focus, layers, and mobile-first layouts (bottom sheets, fullscreen, shareable views) tuned so the interface stays usable on phones during weather events.


• Locality and territory pages — Per-locality detail with recent rain, forecast context, and risk-oriented copy aimed at non-specialists; structured for sharing and open-graph previews.


• Rivers, stations, and hydrological context — Integration with INA-style river and precipitation feeds where configured, plus optional Google Flood outlook cards that present basin-scale forecast signals distinctly from gauge readings.


• Forecasts hub — Open-Meteo and related forecast plumbing with references to official SMN sources where appropriate, oriented to “what might happen next” without replacing institutional warnings.


• Official alerts surfacing — SMN alert banners and copy that reinforce source attribution so users see who issued the warning.


• Sources & methodology page — Explicit documentation of providers, limitations, and how map layers are assembled—critical for trust in a disaster-adjacent product.


• Partner-facing flows — Role-based access (e.g. partner admin / operator) and authenticated surfaces for operational use alongside the public site.


• Crowd and structured reporting (API-backed) — FastAPI service for sessions, reports, and ingestion pipelines; background worker for scheduled ingestion, risk computation, and alert dispatch.


• PWA & notifications — Web app manifest and service worker hooks oriented toward timely alerts when the stack is configured (e.g. VAPID), within the constraints of browser notification permissions.


• Analytics instrumentation — Google Tag Manager wired at the application shell for measurement without scattering ad-hoc scripts across routes.


• Containerized operations — Docker Compose–based stack (web, API, worker, Postgres) suitable for reproducible deploys and VPS-style hosting.

Architecture & responsibilities

• Frontend (apps/web) — Next.js, React, and global CSS for map/dashboard chrome; emphasis on responsive map UX and accessible patterns where implemented.


• Backend (services/api) — FastAPI: authentication, reporting, source status, Google Flood proxying when enabled, and APIs consumed by the web app.


• Worker (services/worker) — Ingestion cycles, risk calculations, and alert triggers decoupled from request/response latency.


• Data store — PostgreSQL (as per deployment configuration) for durable operational data.

Tech stack

• Frontend: Next.js (App Router), React, TypeScript, Leaflet (map), PWA (manifest / service worker).


• Backend: Python, FastAPI, SQLAlchemy-style persistence (via project conventions), pytest for API tests.


• Data & integrations: PostgreSQL; institutional and open meteorological/hydrological sources (e.g. SMN, INA where configured); Open-Meteo; optional Google Flood Forecasting API.


• Ops: Docker, Docker Compose, nginx-friendly deployment (production domain: floodrisk.com.ar).

Challenges & design choices

Blending many providers without a single “ground truth” required careful UI language: forecasts vs observations, failed or skipped sources surfaced in the UI, and methodology spelled out on a dedicated page. Map-heavy mobile layouts demanded iterative tuning—fullscreen modes, bottom sheets, and reduced “map jitter” from competing autopan behaviors on small screens. Environment-driven feature flags (e.g. Google Flood) keep staging and production honest: the same codebase can ship with a subset of integrations enabled.

Goal
Offer a fast, trustworthy, and maintainable hydrological risk companion for Tucumán—transparent about sources, respectful of official institutions, and engineered so new data feeds and alert paths can be added without rewriting the whole stack.