How this dashboard works

Purpose

Kerala Flash-Flood Watch is a public, static-first decision-support dashboard for Kerala monsoon and flood monitoring. It combines official warnings, official hydrology, radar, satellite rainfall, reservoir and dam status, and a small set of curated local-risk corridors into one place.

The main question it tries to answer is:

Where in Kerala should we pay closer attention right now for flash-flood, runoff, river-rise, reservoir-release, or dam-related flood consequences?

It is not an official government warning system. It is meant to help people read many signals together more clearly.

Who this is for

• Disaster-management volunteers
• Journalists and public-interest monitors
• Local observers and community groups
• Field teams who want one place to review multiple signals quickly
• People who want evidence-linked alerts instead of a black-box score

What the dashboard shows

• A single operational headline at the top
• Active alerts at Watch and above
• District risk cards for all 14 Kerala districts
• Taluk risk cards for 61 taluks
• Hotspot risk cards for curated local corridors and low-lying pockets
• Source-health cards showing whether each source is current, older than usual, or unavailable

The map is currently a district-only Kerala map with hotspot overlays. Taluks are still scored and shown in card form, but the taluk map toggle was removed because it was not reliable enough.

Area types

Districts

Districts are the main operational layer. They aggregate warnings, rainfall, radar, hydrology, reservoir context, and terrain sensitivity at district scale.

Taluks

Taluks are a finer summary layer. They use localized rainfall context and district or hotspot membership, but are currently shown as cards rather than map polygons.

Hotspots

Hotspots are curated named places where local geography or infrastructure makes flood consequences more likely. These include steep catchments, floodplains, dam-downstream pockets, confluences, low-lying basins, and urban drainage pockets.

Data sources used

IMD warning sources

• IMD CAP RSS: official severe weather CAP feed for Kerala. CAP items only contribute while unexpired.
• IMD District Warning (Kerala): district-level warning map used as official district warning support.
• IMD District Nowcast (Kerala): short-lead district nowcast support for current conditions.
• IMD Station Nowcast (Kerala): station nowcast mapped cautiously to nearby hotspots only.
• IMD Flash Flood Bulletin: bulletin-style expert guidance used as corroboration, not as a sole severe trigger.

Official hydrology and reservoir sources

• India-WRIS CWC Rainfall: official station-based rainfall, treated as higher-trust daily rainfall evidence.
• India-WRIS CWC River Water Level: official river-level context.
• CWC FFS Live River Levels: live flood-forecasting and river-stage support.
• KSDMA Daily Dam Levels (KSEB): reservoir status context.
• KSDMA Daily Dam Levels (Irrigation): dam and controlled outflow context.

Environmental context

• RainViewer Radar Nowcast: short-lead radar support.
• NASA IMERG Near-Real-Time: satellite rainfall backbone for continuous spatial coverage.

Manual input

• Operator Observation Override: manual fallback or override path, not the normal primary workflow.

Why multiple sources are needed

No single source is enough.

• IMD may issue a broad warning while rainfall stays low in a specific district.
• Radar may show active weather while formal warning products are still quiet.
• A river or dam situation can raise risk even without extreme short-duration rainfall.
• Terrain and wetness matter because the same rain does not create the same consequence everywhere.

The dashboard exists because operational risk in Kerala depends on both hazard and local consequence context.

How scoring works

The model produces a composite score from 0 to 100 for districts, taluks, and hotspots. It is a decision-support score, not a probability.

The model also adds a small agreement bonus when several independent signals point in the same direction.

Alert thresholds

A score of 58 does not mean “58% chance of flood.” It means the current combination of evidence crosses the dashboard’s Alert threshold.

How district, taluk, and hotspot logic differ

District logic

Districts combine official warning products, district nowcast, official and satellite rainfall, radar, river-stage and dam context, and terrain susceptibility. Districts are the most balanced layer.

Taluk logic

Taluks use localized rainfall estimates, district background conditions, hotspot membership or context, and local runoff susceptibility. They are meant to be more local than districts, but still more cautious than hotspots.

Hotspot logic

Hotspots are the most consequence-focused layer. They combine nearby rainfall, nearby radar, nearby station nowcast when available, catchment wetness, hotspot category, terrain and runoff susceptibility, and river or dam context where relevant.

Hotspots are not allowed to escalate too easily from broad warning text alone. A generic district thunderstorm or wind warning should not create a hotspot Watch by itself.

Freshness and source status

The dashboard separates three different ideas:

• Data published: when the source data itself appears to have been issued
• Last checked by our system: when our system last attempted to fetch that source
• This run: whether the latest refresh produced usable data, or whether the source is currently unavailable

Source status meanings:

• Current / ok: within expected freshness window
• Degraded: available, but weaker than normal for scoring
• Older than usual / stale: older than expected
• Unavailable / offline: should not contribute to scoring

Older data is not treated the same as fresh data. Current sources contribute fully. Degraded sources are down-weighted. Stale sources are heavily down-weighted. Offline sources do not contribute.

Each refresh workflow now fetches live for the sources it owns. If a source fails in that refresh, the latest snapshot records it as unavailable instead of silently reusing an older successful payload.

Important safeguards already implemented

• CAP expiry is respected: CAP alerts only contribute while their official expires window is still valid.
• Same-day district warning logic: the district warning page is treated like a same-day bulletin rather than a minute-precise feed.
• Stale-source down-weighting: old data does not keep behaving like fresh evidence.
• Manual review for highest severity: severe candidates require explicit approval before becoming public reviewed severe alerts.

How the dashboard decides what to show first

• Operational headline: summary of the current picture, not the full alert list
• Active alerts: the full list of current alerts
• District, taluk, and hotspot cards: cards try to show the most local and most useful explanation first rather than raw internal driver strings

Refresh and publication workflow

The dashboard uses a multi-step workflow.

1. Data refresh: different workflows update different source groups
2. Publish dashboard snapshot: a publish workflow rebuilds the public snapshot from the latest source cache
3. GitHub Pages deployment: GitHub Pages serves the latest published snapshot

This separation exists so refresh workflows do not fight each other and one workflow produces the final public snapshot.

Telegram controls and alert review

Telegram is split into two different roles.

• Private command chat: used for /status, /pause_refresh, /resume_refresh, /pending_alerts, /approve, and /reject
• Public alert group: used only for reviewed severe alerts

The preferred control path uses a Cloudflare Worker webhook. Telegram sends the command to the Worker, the Worker validates the private command chat, and GitHub applies state-changing commands like pause, resume, approve, and reject.

/pause_refresh now hard-disables the three refresh workflows, so scheduled refresh runs stop being created until /resume_refresh turns them back on.

Read-only commands such as /status and /pending_alerts can be answered directly from the webhook. The older poll-based Telegram workflow is kept only as a fallback path.

How often sources are checked

• India fast sources: about every 20 minutes
• India hydrology sources: about every 60 minutes
• External sources: about every 30 minutes

Important: a source card should be read as “what data is being used now.” Publish rebuilds the page from the latest refresh snapshot for each source group, but each refresh always attempts a live fetch for the sources it owns.

Known limitations

• It is not an official warning authority.
• Government websites, PDFs, and embedded page data can change structure unexpectedly.
• Some sources provide exact times; others only provide a date or a daily bulletin.
• Hotspots cover selected known sensitive corridors, not every vulnerable place in Kerala.
• Scores are heuristic and evidence-based, but still human-designed, not a trained probabilistic flood model.

When this page should be updated

This page should be updated whenever any of the following changes:

• source list
• source role in scoring
• weights
• thresholds
• manual review rules
• stale-data treatment
• CAP expiry handling
• district, taluk, or hotspot logic
• map behavior
• publish workflow or operational architecture
• interpretation guidance for users

If the meaning of the dashboard changes, this page should change too.

Feedback we want

We especially welcome feedback from IMD users, hydrologists, district disaster-management staff, dam and river monitoring teams, and field volunteers who can compare dashboard outputs with local reality.

Useful feedback looks like:

• “This alert is too aggressive for this kind of signal.”
• “This source should be weighted less.”
• “This district should rely more on river context than radar.”
• “This hotspot is missing.”
• “This official product should be treated as primary, not secondary.”
• “This explanation is too technical or not understandable.”