GAUGE - Queensland Flood Tracking Dashboard

Real-time water level monitoring and flood warning dashboard covering all of Queensland, from the Gold Coast to Cape York, including Brisbane, Townsville, Cairns, Mackay, Rockhampton, and remote Western Queensland.

Approach & Architecture

GAUGE is designed with rural Queensland communities in mind, where reliable internet connectivity cannot be guaranteed and users need quick, actionable flood information.

Design Principles

Clarity over complexity - Status levels use plain language (SAFE, WATCH, WARNING, DANGER) with color-coded visual indicators. No technical jargon.
Map-first interface - The interactive map is the primary view, with satellite/hybrid imagery showing familiar landmarks. River overlays display real-time status at a glance.
Progressive data loading - Core gauge status loads first via SWR with auto-refresh. Historical charts and detailed data load on-demand when a gauge is selected.
Offline resilience - Data is cached client-side. When connectivity drops, users still see the last known readings with staleness indicators.
Mobile-responsive - Full functionality on phones, designed for users checking conditions from the field.

Data Flow

                                    Cloud Scheduler (every 1-2 min)
                                             │
                                             ▼
Queensland WMIP API ──┐                                    ┌──────────────┐
BOM Water Data API ───┤                                    │              │
Open-Meteo API ───────┼──> Cron API (/api/cron/fetch) ───>│  Firestore   │
QLDTraffic API ───────┘                                    │              │
                                                           └──────────────┘
                                                                  │
                       Cached Data (10 min TTL)                   │
                       ├── Water levels & discharge               │
                       ├── Dam storage levels                     │
                       ├── Statewide rainfall                     │
                       └── Road closures                          ▼
                              Next.js API Routes ──> SWR Cache ──> React UI
                                      │
                                      ├── Rate limiting
                                      ├── Input sanitization
                                      └── Direct fetch fallback (if cache miss)

Cloud Architecture

GAUGE uses Firestore + Cloud Scheduler for reliable data caching across Cloud Run instances:

Cloud Scheduler triggers the /api/cron/fetch-water-data endpoint every 1-2 minutes
Firestore stores all data with 10-minute TTL, shared across all Cloud Run instances:
- Water levels and discharge readings
- Dam storage levels
- Statewide rainfall aggregates (from Open-Meteo)
- Road closures (from QLDTraffic)
API routes read from Firestore cache with fallback to direct API fetch on cache miss
Partial failure tracking ensures water level data is stored even if auxiliary sources fail
Application Default Credentials (ADC) handle authentication automatically on Cloud Run
Lazy Firestore initialization allows local development without GCP credentials

Key Components

FloodMap - Leaflet map with gauge markers, river polylines, and address search
GaugeListSidebar - Priority-sorted gauge list grouped by river system
WaterLevelChart - 24-hour history with flood threshold lines
StatusBadge - Consistent status display across the app

Features

Real-time Water Levels: Live data from 100+ gauge stations across Queensland
Discharge/Flow Rates: Water flow data (ML/day or cumec) at gauge locations
Dam Storage Levels: 30+ major dams including Wivenhoe, Burdekin Falls, Fairbairn
Rainfall Data: Statewide aggregated rainfall with location-specific data when gauges selected
Road Closures: Real-time flood-related road closures from QLD Traffic
Interactive Map: Satellite/street/hybrid map views with status-coded markers
Address Search: Search by address, town, river, or gauge name
Historical Charts: 24-hour water level history with flood threshold indicators
Flood Warnings: Real-time BOM flood warning integration
Rain Radar: Live weather radar overlay from RainViewer
7-Day Gauge Reliability: Uptime tracking showing gauge reporting consistency over the past week
Deep Linking: Shareable URLs for specific gauges with proper OpenGraph metadata for social previews
Anchor Links: Direct links to page sections (map, details, history, reliability)
Share & Bookmark: Built-in share button with Web Share API and clipboard fallback
Mobile Responsive: Fully functional on all device sizes
Offline-friendly: Cached data for poor connectivity areas

URL Structure & Deep Linking

GAUGE supports deep linking to specific gauges and page sections for easy sharing:

Gauge URLs

Each gauge has a dedicated URL that preserves OpenGraph metadata for social media sharing:

https://gauge.clermont.digital/gauge/{gauge_id}

Examples:

https://gauge.clermont.digital/gauge/130401A - Sandy Creek at Clermont
https://gauge.clermont.digital/gauge/143010A - Burdekin River at Sellheim

Anchor Links

Link directly to specific sections on any gauge page:

Anchor	Section
`#map`	Interactive map
`#details`	Gauge details card
`#history`	24-Hour Water Level History chart
`#reliability`	7-Day Reliability chart

Example: https://gauge.clermont.digital/gauge/130401A#history

OpenGraph Support

All gauge URLs generate proper OpenGraph metadata for rich social media previews, including:

Gauge-specific title and description
1200x630 preview image
Twitter card support

Tech Stack

Framework: Next.js 14 (App Router)
UI: React 18, Tailwind CSS
Maps: Leaflet / React-Leaflet
Charts: Recharts
Data Fetching: SWR with auto-refresh
Database: Google Cloud Firestore
Hosting: Google Cloud Run
Scheduling: Google Cloud Scheduler

Quick Start

Clone and install

git clone https://github.com/ClermontDigital/flood_dashboard.git
cd flood_dashboard
npm install

Configure environment
```
cp .env.example .env.local
```
Run development server
```
npm run dev
```
Open in browser
```
http://localhost:3000
```

Environment Variables

See .env.example for all available configuration options:

Variable	Description	Default
`NEXT_PUBLIC_WMIP_BASE_URL`	Queensland WMIP API endpoint	Set
`NEXT_PUBLIC_BOM_WATERDATA_URL`	BOM Water Data API	Set
`NEXT_PUBLIC_ENABLE_MOCK_DATA`	Enable mock data fallback	`true` (dev only)
`RATE_LIMIT_MAX_REQUESTS`	API rate limit per minute	`60`
`GOOGLE_CLOUD_PROJECT`	GCP project ID for Firestore	Auto-detected on Cloud Run
`CRON_SECRET`	Secret for Cloud Scheduler auth	Optional
`QLDTRAFFIC_API_KEY`	QLDTraffic API key for road closures	Required for road data

Data Sources

All data is sourced from official Australian Government APIs:

Bureau of Meteorology (BOM) - Water Data Online

URL: www.bom.gov.au/waterdata/

The BOM SOS2 (Sensor Observation Service) API provides:

Data Type	Parameter	Unit	Description
Water Level	`Water Course Level`	metres	Current water height at gauge
Discharge	`Water Course Discharge`	ML/d or cumec	Water flow rate
Dam Storage Volume	`Storage Volume`	ML	Total water stored
Dam Storage Level	`Storage Level`	metres	Dam water elevation
Rainfall	`Rainfall`	mm	Daily rainfall totals

Queensland WMIP (Water Monitoring Information Portal)

URL: water-monitoring.information.qld.gov.au

Queensland Government's water monitoring system, used as a fallback data source for water levels.

BOM Flood Warnings

URL: www.bom.gov.au/qld/flood/

Official flood warnings and alerts for Queensland catchments.

QLDTraffic API

URL: qldtraffic.qld.gov.au

Queensland Government's traffic and road conditions API provides:

Real-time road closures due to flooding
Traffic hazards and incidents
Road condition alerts

Requires an API key (set via QLDTRAFFIC_API_KEY environment variable).

Open-Meteo API

URL: open-meteo.com

Free weather API used for statewide rainfall aggregation:

Rainfall data from 14 sample locations across Queensland
Batched requests (5 at a time with 100ms delay) to avoid rate limiting
Aggregated into min/max/average for statewide overview

Monitored Infrastructure

River Systems (45+ Catchments)

Southeast Queensland

Brisbane River, Bremer River, Lockyer Creek, North Pine River
Logan River, Albert River, Nerang River, Coomera River
Mooloolah River, Mary River

Wide Bay-Burnett

Burnett River, Kolan River

Central Queensland (Fitzroy Basin)

Sandy Creek (Clermont), Theresa Creek, Wolfang Creek, Douglas Creek
Isaac River, Nogoa River, Mackenzie River, Comet River, Fitzroy River

Mackay-Whitsunday

Pioneer River, Proserpine River, Broken River, Don River

North Queensland

Burdekin River, Ross River, Herbert River

Far North Queensland

Barron River, Mulgrave River, Johnstone River, Tully River, Daintree River

Cape York

Mitchell River, Normanby River

Gulf Country

Norman River, Flinders River, Leichhardt River, Cloncurry River

Channel Country / Outback

Cooper Creek, Diamantina River, Warrego River, Paroo River

Darling Downs

Condamine River

Major Dams (30+)

Region	Dams
Southeast QLD	Wivenhoe, Somerset, Hinze, North Pine, Leslie Harrison, Lake Manchester, Moogerah, Lake Maroon, Lake Clarendon, Atkinson
Sunshine Coast	Ewen Maddock, Baroon Pocket
Burnett	Paradise, Boondooma, Fred Haigh, Wuruma
Central QLD	Fairbairn, Theresa Creek
Mackay-Whitsunday	Peter Faust, Kinchant, Eungella, Teemburra
North QLD	Burdekin Falls, Ross River, Tinaroo Falls, Copperlode
Western QLD	Julius, Lake Moondarra, Lake Fred Tritton
Darling Downs	Leslie, Storm King, Coolmunda, Glenlyon

Production Deployment

Cloud Run (Recommended)

GAUGE is deployed on Google Cloud Run with Firestore for data caching.

Live Sites:

Production: https://gauge.clermont.digital

Deploy to Cloud Run:

# Build and push image
docker build -t gcr.io/YOUR_PROJECT/gauge-dashboard .
docker push gcr.io/YOUR_PROJECT/gauge-dashboard

# Deploy to Cloud Run with environment variables
gcloud run deploy gauge-dashboard \
  --image gcr.io/YOUR_PROJECT/gauge-dashboard \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --set-env-vars QLDTRAFFIC_API_KEY=your_api_key

# Create Cloud Scheduler job for data fetching (runs every 2 minutes)
gcloud scheduler jobs create http gauge-fetch-water-data \
  --location=asia-southeast1 \
  --schedule="*/2 * * * *" \
  --uri="https://YOUR_SERVICE_URL/api/cron/fetch-water-data" \
  --http-method=POST \
  --oidc-service-account-email=YOUR_SERVICE_ACCOUNT

Update environment variables on existing deployment:

gcloud run services update gauge-dashboard \
  --update-env-vars QLDTRAFFIC_API_KEY=your_api_key \
  --region asia-southeast1

Docker (Local)

docker build -t gauge-dashboard .
docker run -p 3000:3000 gauge-dashboard

Docker Compose

docker-compose up -d

API Endpoints

Endpoint	Method	Description
`/api/water-levels`	GET	Current readings for all gauges
`/api/water-levels/[id]`	GET	Single gauge with 24hr history
`/api/warnings`	GET	Active BOM flood warnings
`/api/predictions`	GET	Calculated flood forecasts
`/api/weather`	GET	Current weather conditions
`/api/rainfall`	GET	Statewide rainfall (cached) or location-specific
`/api/road-closures`	GET	Flood-related road closures from QLDTraffic
`/api/uptime`	GET	7-day gauge reliability/uptime statistics
`/api/cron/fetch-water-data`	POST/GET	Cloud Scheduler endpoint (populates cache)
`/api/cron/backfill-uptime`	POST/GET	One-time backfill of historical uptime data

All API endpoints first check Firestore cache (10 min TTL) and fall back to direct API fetch on cache miss.

Development

Agent Context (CLAUDE.md)

The repository includes a CLAUDE.md file containing project-specific context for AI coding assistants. This documents:

Deployment configuration (region, service name)
Common gotchas and patterns
Architecture decisions and rationale

This file is automatically read by compatible AI assistants to provide better context-aware assistance.

Important Disclaimer

This dashboard displays water level data from government sources for informational purposes only. It is NOT an official warning system.

Always follow official warnings from:

Bureau of Meteorology (BOM)
Queensland Fire and Emergency Services (QFES)

In an emergency, call 000.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
docs		docs
public		public
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
cloudbuild.yaml		cloudbuild.yaml
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
logo.png		logo.png
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

GAUGE - Queensland Flood Tracking Dashboard

Approach & Architecture

Design Principles

Data Flow

Cloud Architecture

Key Components

Features

URL Structure & Deep Linking

Gauge URLs

Anchor Links

OpenGraph Support

Tech Stack

Quick Start

Environment Variables

Data Sources

Bureau of Meteorology (BOM) - Water Data Online

Queensland WMIP (Water Monitoring Information Portal)

BOM Flood Warnings

QLDTraffic API

Open-Meteo API

Monitored Infrastructure

River Systems (45+ Catchments)

Major Dams (30+)

Production Deployment

Cloud Run (Recommended)

Docker (Local)

Docker Compose

API Endpoints

Development

Agent Context (CLAUDE.md)

Important Disclaimer

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages