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 important mental model is:

The dashboard first converts each source into a normalized severity signal, then applies freshness and source-health weighting, then combines those weighted signals into a 0-100 operational score.

A high score means multiple relevant signals agree that local flood consequence risk is elevated. A low score means either the weather is weak, the hydrology is quiet, the terrain is not very sensitive, or the available evidence does not agree strongly enough.

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

District score formula

District scoring is the clearest base formula in the system:

district_raw_score =
  official_warning_component +
  flash_flood_bulletin_component +
  rainfall_component +
  antecedent_wetness_component +
  terrain_component +
  hydrology_component +
  radar_nowcast_component +
  reservoir_dam_component +
  agreement_bonus

Each component is normalized to a 0-100-like scale first, then multiplied by its configured weight. The final result is clamped into a 0-100 score band.

What a source percentage means

When the dashboard shows phrases like IMD district warning 22% or IMD station nowcast 18%, that number is the source signal’s effective severity after parsing and freshness weighting, not the final flood probability.

Examples:

• 22% means severity 0.22
• 35% means severity 0.35
• 70% means severity 0.70

The district, taluk, and hotspot scores then use those severities inside the weighted formulas below.

How warning and nowcast text becomes a severity value

The parser maps IMD text into coarse operational severity buckets before scoring. These values are intentionally simple and transparent rather than machine-learned.

Heat-only products such as Hot Day, Heat Wave, and similar heat advisories are intentionally treated as zero flood severity. They remain visible as source text for transparency, but they should not help create a flood watch by themselves.

How source freshness changes the score

Every signal is also multiplied by a source-health weight:

Example: an IMD warning with severity 0.22 contributes as 0.22 when the source is current, 0.132 when degraded, 0.055 when stale, and 0 when offline.

How rainfall is normalized

Rainfall is not scored as raw millimetres directly. It is normalized against configured caps so that very different durations can be blended together consistently.

Antecedent wetness is calculated separately from 3-day and 7-day totals:

• 3-day total uses a 500 mm cap and contributes 55% of the wetness family
• 7-day total uses a 900 mm cap and contributes 45% of the wetness family

Agreement bonus

The model adds a bonus when several independent families are active at once:

• 2 active families: +4
• 3 active families: +8
• 4 or more active families: +12

“Independent families” here means broad groups such as official warnings, bulletin support, runoff readiness, radar or nowcast, and hydrology or dam context. This is meant to reward agreement across different evidence types, not duplicate the same signal.

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.

Worked district example

Suppose a district has these current conditions:

• IMD district warning severity 0.22 from thunderstorm wording
• No CAP alert
• No flash-flood bulletin support
• 1h rain 12 mm, 3h rain 20 mm, 6h rain 35 mm, 24h rain 30 mm
• 3-day rain 60 mm, 7-day rain 100 mm
• terrain susceptibility 0.80
• hydrology severity 0.35
• district radar or nowcast severity 0.28
• reservoir or dam severity 0.40

The district score is approximately built like this:

official warning  = 22 * 0.24 = 5.3
bulletin          =  0 * 0.10 = 0.0
rainfall family   = 18.2 * 0.24 = 4.4
antecedent family = 13.2 * 0.09 = 1.2
terrain           = 80 * 0.12 = 9.6
hydrology         = 35 * 0.08 = 2.8
radar / nowcast   = 28 * 0.08 = 2.2
reservoir / dam   = 40 * 0.05 = 2.0
agreement bonus   = +8

raw score ≈ 35.5  → Watch

The exact dashboard number may differ slightly because the real model uses source-health multipliers, combines some signals before weighting, rounds to one decimal place, and uses the latest available source state at publish time. But this is the real structure of the calculation.

How hotspot scoring differs from district scoring

Hotspots start from the district model but then add consequence-focused local adjustments:

hotspot_raw_score =
  district_dynamic_raw_score
  + hotspot_susceptibility * category_weight
  + category_boost
  + manual_override_boost
  + local_short_lead_signal_term
  + hydrology_or_dam_term

Important consequences of that design:

• Hotspots inherit broad district context, but do not exactly equal district scores.
• Hotspot category matters: steep catchments, river floodplains, dam-downstream corridors, and urban flood pockets do not all escalate the same way.
• Nearby station nowcast and nearby radar matter more for hotspots than for districts.

Runoff potential

Runoff potential is a separate internal calculation, also shown in the UI because it helps explain why a place is sensitive even before flooding is visible.

It blends:

• catchment wetness
• short-lead trigger intensity (recent rain + radar)
• local susceptibility

Different hotspot categories use different blend weights. For example, a river_floodplain hotspot leans more on wetness and susceptibility, while an urban_flood_pocket hotspot leans more on short-lead trigger intensity.

Watch-gating safeguards

One more safeguard matters a lot:

A hotspot or locally promoted taluk is not allowed to remain at Watch just because its raw score crosses 35. It must also pass a category-specific “watch support” gate.

This gate exists to stop false positives such as:

• broad district thunderstorm or wind warnings with no meaningful local rain
• moderate radar or nearby station nowcast context that is not strong enough for flash-flood concern
• heat-only advisories like Hot Day
• vulnerable geography, weak dam context, or weak river context with no current flood-weather trigger

A local Watch now needs flash-flood-capable support: short-duration rain that crosses the hotspot category threshold, strong radar, strong nearby station nowcast, strong hydrology, strong dam or release context, explicit flash-flood bulletin/CAP support, or runoff readiness backed by wetness or another flood trigger.

For example, river-floodplain and dam-downstream hotspots now require strong hydrology or dam context on its own, or a weaker river or reservoir signal paired with meaningful local flood-weather support. Moderate storm context, district warning text, and consequence geography can still explain caution, but they should not create a flash-flood Watch by themselves.

If you think any of these calculations, thresholds, or gating rules are wrong for Kerala reality, please send a concrete example to nishanthdotkesavan@gmail.com. The goal is not to defend the model; the goal is to improve it when reality disagrees.

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.

Taluks also get extra score from:

• the strongest mapped hotspot score inside the taluk
• the number of mapped hotspots in that taluk
• local hotspot susceptibility averaged into the taluk susceptibility term

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, moderate storm context, or vulnerable geography alone. A generic district thunderstorm or wind warning should not create a hotspot Watch by itself.

Freshness, saved copies, and source status

The dashboard separates three different ideas:

• Source data time: when the source data itself appears to have been issued
• Last checked by our system: when our system last fetched or confirmed that source
• Latest refresh result: whether the latest source refresh succeeded or left that source unavailable for this snapshot

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

Each refresh workflow attempts a live fetch for the sources it owns. If a source fails in that refresh, it drops out of scoring for that snapshot instead of silently reviving an older successful payload. Current sources contribute fully. Degraded sources are down-weighted. Stale sources are heavily down-weighted. Offline sources do not contribute.

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.

The Worker is intentionally narrow in scope: it serves the Telegram webhook, exposes a simple health check, and is no longer used as a general source-fetch proxy.

/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 are answered directly from the webhook. The older poll-based Telegram workflow has been removed.

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,” not “this source definitely published new data in this run.”

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.

Feedback email: nishanthdotkesavan@gmail.com

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.”

The most helpful feedback includes the exact area name, date, what the dashboard showed, and what local reality looked like instead.