FloodShield: Building a Mumbai Monsoon Risk Explorer That Admits What It Doesn't Know
A weather app can tell you it is raining 40 mm an hour. It cannot tell you whether the underpass on your route is the kind of place where that rain becomes a problem.
That gap is why I built FloodShield, a prototype for the AWS Environmental Hacks hackathon in the Heat & Water track. Mumbai's monsoon waterlogging is not only a question of how hard it rains. It depends on where you are: how low the ground sits, how much of the surface is paved, how close the nearest waterway is, and what the tide is doing. A rainfall number alone cannot answer all those questions.
FloodShield is a scenario explorer, not a flood predictor. This post covers what I built, how it fits together with AWS, the engineering decisions behind it, and what I would not claim about its capabilities.
WHAT YOU CAN DO WITH FLOODSHIELD
FloodShield opens an interactive Leaflet map containing eight Mumbai locations associated with waterlogging concerns, including Milan Subway, Hindmata, and Kurla. Each location has predefined attributes, such as elevation, a depression index, distance to the nearest waterway, and an impervious-surface ratio.
Selecting a location displays a heuristic susceptibility score between 0 and 100, a breakdown of contributing factors, and practical precautions.
The Storm Simulator lets users explore different scenarios. You can adjust rainfall intensity, duration, tide level, and drainage condition to observe how the calculated score and its contributing factors change.
A “Use current rainfall” action loads the latest available Open-Meteo rainfall observation as a scenario input. This lets users explore questions such as how a higher rainfall scenario might affect a location under different assumptions.
These results are exploratory. The locations and their predefined attributes have not been validated against a comprehensive historical flood dataset, so the scores should not be interpreted as verified predictions or guarantees of safety.
ARCHITECTURE
FloodShield separates weather retrieval from risk assessment. The browser retrieves weather observations directly from Open-Meteo, while the configured backend provides an assessment endpoint through Amazon API Gateway and AWS Lambda.
Architecture diagram:
Figure 1: FloodShield architecture. Solid arrows represent application data flows, while dashed arrows represent infrastructure configuration. This describes the intended design and does not imply that a live AWS deployment has been verified.
The frontend uses React 19, TypeScript, and Vite, with Leaflet for the interactive map and Storm Simulator.
Risk assessment follows the AWS path when a backend endpoint is configured. The frontend sends a POST /assess request through the API client to Amazon API Gateway, which invokes a Node.js 22 Lambda handler. The assessment response returns through the API client, which validates it before the interface uses it.
The SAM template in infra/template.yaml defines the Lambda function and two routes: POST /assess and GET /health.
Weather follows a separate browser-side path. The frontend calls Open-Meteo directly rather than routing weather requests through Lambda. If the request fails or the payload is malformed, the weather service provides sample data marked SAMPLE_FALLBACK.
There is also a local assessment fallback. If VITE_AWS_API_URL is not configured, or the AWS request fails or returns an invalid response, the frontend can calculate an assessment locally using src/services/riskEngine.ts. That result is labelled LOCAL_FALLBACK so the user can distinguish it from a response accepted from the AWS backend.
ENGINEERING DECISIONS
A transparent heuristic, not a predictive model
FloodShield does not use machine learning. Its risk score combines four capped components: precipitation load, worth up to 40 points; topography, up to 25; tide and drainage, up to 20; and surface runoff, up to 15.
I chose a rules-based approach because I did not have the observed flood data required to train or calibrate a predictive model. A heuristic is easier to inspect, explain, and test. Its weights are design choices, however, and are not fitted to historical flood events.
That distinction matters. A numerical score can look authoritative even when the underlying assumptions have not been validated. FloodShield therefore presents its score as an exploratory assessment rather than a scientific prediction.
Validate at the boundary
The Lambda handler validates incoming requests before processing them. This includes checking required fields, numeric values, supported ranges, and allowed parameter values. The handler also handles unsupported HTTP methods and content types.
These checks help prevent malformed requests from entering the assessment logic. Unexpected errors are handled separately so that internal implementation details are not unnecessarily exposed to clients.
Don't trust a successful HTTP status alone
A request returning HTTP 200 does not guarantee that the response contains valid assessment data. A server might return malformed JSON, an HTML error page, or a score outside the expected range.
FloodShield's frontend API client validates the response structure, score ranges, and provenance. A response is accepted as an AWS-backed assessment only when it meets the expected schema and carries the expected AWS_LAMBDA provenance marker.
If validation fails, the client falls back to the local engine instead of displaying the response as a valid AWS result.
The trade-off is strictness: even a harmless change in the backend response schema can trigger a local fallback. That makes clear provenance indicators and useful error handling important parts of the user experience.
Label weather like data, not decoration
The weather service checks whether the response contains the expected current observation, including a timestamp and a finite temperature value. When weather retrieval fails because of a network error, an HTTP error, or a malformed payload, the service can return sample data labelled SAMPLE_FALLBACK.
This keeps the demonstration usable without presenting sample values as live observations. It is a small design decision, but one that matters whenever an application displays information that users might otherwise assume is current.
WHAT FOUGHT BACK
Failure that looks like success
One of the most important cases to handle was a response that appeared successful but contained unusable data. An endpoint could return HTML with a 200 status or provide a score greater than the permitted range.
The API client tests cover these scenarios. They demonstrate why checking response.ok is insufficient and why validating the actual payload matters.
The trade-off is that strict validation can reject responses when the backend changes unexpectedly. FloodShield responds by using the local engine and marking the result accordingly.
Two copies of one engine
The assessment logic exists in two places: backend/lambda/riskEngine.js for the Lambda backend and src/services/riskEngine.ts for the frontend fallback.
This duplication allows local assessment when the backend is unavailable, but it creates a maintenance risk. If one implementation changes without the other, the two paths could produce different results for identical inputs.
A useful next step would be a shared set of test scenarios that runs against both implementations and checks that their outputs agree. That would help reduce the risk of the two engines drifting apart.
Unreliable upstream data
Weather services can time out or return incomplete responses. Simply displaying the last received value as though it were current would be misleading.
FloodShield handles this by marking sample data explicitly. The remaining challenge is ensuring that the interface makes the distinction visible enough that users do not mistake demonstration data for a live measurement.
WHAT THE 43 TESTS COVER
The local Vitest suite contains 43 passing tests across four test files.
The Lambda handler suite has 16 tests covering the health endpoint, CORS preflight, validation failures, boundary values, and unsupported methods and content types.
The API client suite has 15 tests covering response validation, provenance, and fallback behaviour for server errors, malformed responses, network failures, and out-of-range scores.
The weather service suite has five tests covering parsing, sample-data labelling, and fallback behaviour for network errors, HTTP errors, and missing weather structures.
The risk engine suite has seven tests covering score bounds, differences between locations, tide effects, and extreme inputs.
The production build also succeeds locally. Linting reports zero errors and two React warnings.
These results provide evidence that the tested software behaves as intended for the covered cases. They do not prove that the risk scores match actual flooding, and FloodShield has not been validated against historical flood observations. It remains a prototype rather than a production-ready environmental safety system.
WHAT I USED ON AWS, PRECISELY
FloodShield includes a Lambda function configured for Node.js 22, an API Gateway HTTP API, an AWS SAM template, and a deployment script at infra/deploy.sh.
The backend handler can be tested locally, including through the project's local API emulator. The SAM template describes the infrastructure and routes needed for AWS deployment.
I have not independently verified a public AWS deployment, so I am not claiming that the live endpoints are operational.
Serverless architecture is a useful fit for this prototype because the assessment logic is a relatively small, stateless operation. Lambda provides managed compute, and API Gateway exposes the HTTP endpoints. Actual scaling, availability, security, and costs still depend on configuration and usage.
A real municipal or emergency-management deployment would require considerably more work. That includes authentication and authorization, appropriately restricted CORS, rate limiting, monitoring, reliable data pipelines, model validation, and clear accountability for the information presented to users.
LESSONS AND NEXT STEPS
Building FloodShield reinforced four lessons.
First, external APIs fail in more ways than simply becoming unavailable. A robust client must account for timeouts, incomplete payloads, malformed responses, and values outside expected ranges.
Second, data provenance is a feature. Users should be able to understand whether a result came from a live service, a backend assessment, or a local fallback.
Third, serverless architecture does not remove the need for engineering discipline. Validation, testing, observability, and error handling remain essential.
Finally, environmental claims require evidence. A confident-looking score is easy to produce; demonstrating that it corresponds to real-world flood risk is much harder.
The next steps for FloodShield are to compare assessments against authoritative historical flood observations, calibrate the heuristic weights, improve the quality of elevation and drainage information, incorporate suitable rainfall and tidal data, and test consistency between the two risk-engine implementations.
Before the application could responsibly support operational decisions, its uncertainty and limitations would need to be evaluated with domain experts and relevant authorities.
CLOSING
FloodShield cannot predict floods or guarantee a safe route. What it can do today is make the assumptions behind an exploratory risk assessment visible and let users ask “what if?” under different rainfall and environmental scenarios.
The project has also taught me that responsible environmental software is not just about producing a number or building an attractive map. It is about explaining where information comes from, handling failures honestly, and recognising what the available evidence cannot establish.
That is the direction in which I want to take FloodShield next.
Amazon API Gateway HTTP APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article