PaaniPath: Building a Waterlogging-Aware Route Planner with Geospatial Algorithms and AWS
PaaniPath is a waterlogging-aware trip planner for Delhi NCR, featuring real-time API routing, multi-stop journeys, community flood reports, and vehicle-specific route comparisons. Built as a TypeScript monorepo with AWS serverless integration and a responsive map interface.
PaaniPath: Building a Waterlogging-Aware Route Planner with Geospatial Algorithms and AWS
Introduction
Urban waterlogging during monsoon rainfall can turn an otherwise normal commute into a risky and unpredictable journey. Conventional navigation focuses primarily on route distance and estimated travel time, leaving travellers to make decisions with incomplete information about reported waterlogging.
PaaniPath is a waterlogging-aware route-planning web application built for Delhi NCR. It compares real, provider-generated road routes against reported waterlogging observations, helping users understand the trade-off between travel time and potential flood exposure.
The project combines geospatial algorithms, community reporting, external routing APIs, and a serverless AWS architecture to provide transparent, data-aware route comparisons.
1. The Problem and the Solution
The central challenge is not simply finding a path between two locations. It is comparing available routes while considering uncertain observations, vehicle-specific assumptions, and an acceptable detour.
PaaniPath supports Delhi, Gurugram, Noida, Greater Noida, Ghaziabad, Faridabad, and surrounding NCR locations.
Its key capabilities include:
- Real road directions and interactive maps using OpenRouteService (ORS) and OpenStreetMap.
- Address search through the Photon geocoding service.
- Multi-stop trips with two to four locations and optional intermediate-stop order comparison.
- Vehicle-specific water-depth classifications for scooters, motorbikes, cars, autos, and buses.
- Community-submitted depth observations, optional photos, independent confirmations, dismissals, and report-freshness tracking.
- Route alternatives ranked by reported exposure and estimated travel time.
- Route-focused hotspot visualization and a responsive Progressive Web App shell.
The objective is to make routing decisions more transparent rather than promise that a particular road is safe.
2. Technology Stack
The application follows a modular TypeScript architecture built with Node.js and npm workspaces.
Component | Technology |
|---|---|
Frontend | apps/web, interactive map, trip editor, report overlays and PWA shell |
Backend | Node.js, TypeScript, HTTP API and Lambda adapters |
Domain layer | Shared types, validation, vehicle policies and error contracts |
Geospatial processing | Haversine distance, point-to-segment geometry and spatial grid indexing |
Mapping | OpenStreetMap raster tiles with Web Mercator projection |
Geocoding | Photon |
Road routing | OpenRouteService directions and polygon avoidance |
Local persistence | SQLite |
Cloud persistence | Amazon DynamoDB and private Amazon S3 |
Infrastructure | AWS SAM, AWS CLI v2 and AWS CloudFormation |
Testing | Type checking, unit tests, HTTP integration tests and optional live-provider smoke tests |
A key architectural decision is that PaaniPath does not maintain its own road network. ORS provides the road geometry and directions, while the application's own algorithms perform exposure evaluation, candidate filtering, ranking, and reporting logic.
3. System Architecture
The system separates presentation, API processing, domain logic, routing, and persistence.
The browser renders the map, accepts trip inputs, displays route comparisons, and supports community reports. The API validates requests and coordinates routing and report operations. Shared domain contracts ensure that client and server agree on input formats, validation rules, and response structures.
The main request flow is:
Browser → API → Domain validation → Routing planner → OpenRouteService → Geospatial exposure scoring → Ranked route response → Map visualization.
Search follows a separate path through the API to Photon. OpenStreetMap tiles are loaded directly by the browser.
The data layer uses a common storage interface, allowing SQLite for local development and DynamoDB with private S3 photo storage in AWS. This separation makes the application easier to test and deploy without coupling business logic to a specific storage implementation.
4. The Core Algorithm: Bounded Route Candidate Comparison
PaaniPath uses bounded candidate comparison rather than implementing a local Dijkstra or A* road-network search algorithm.
The user supplies two to four distinct locations, a vehicle profile, and a detour factor. The planner then executes the following steps:
- Validate the stops, coordinates, selected vehicle, and report snapshot.
- Classify active reports according to their depth, vehicle thresholds, and freshness.
- Request the fastest available provider baseline for the selected trip order.
- Generate alternative directions using approximate polygon-avoidance zones around relevant risky or stale observations.
- Measure the proximity of reported observations to each returned route.
- Reject candidates exceeding the detour budget and rank the remaining candidates.
- Deduplicate identical route geometries and return up to three distinct routes, retaining the fastest baseline for comparison when necessary.
For a trip containing an origin, two intermediate stops, and a destination, PaaniPath can compare both intermediate-stop orders while keeping the endpoints fixed. It does not attempt to enumerate every possible road path.
Detour constraint
Let:
- T(r) = estimated duration of a candidate route.
- T₀ = minimum duration among the returned baseline routes.
- f = user-selected detour factor, between 1 and 3.
A route is eligible when:
T(r) ≤ f × T₀ + 0.001 The small tolerance handles floating-point comparisons; it is not an additional travel allowance.
Geospatial proximity
PaaniPath uses the Haversine formula for point-to-point distances:
d = 2R × asin(√a) where:
a = sin²(Δφ/2) + cos(φ₁)cos(φ₂)sin²(Δλ/2) Here, R is the Earth's mean radius used by the implementation (6,371,008.8 metres), and the latitude and longitude values are expressed in radians.
For route exposure, the implementation uses a local tangent-plane approximation to calculate point-to-segment distance. A report is counted as exposed when it is within 85 metres of any route segment. A set of report IDs ensures that one observation is counted only once per route, even if several segments pass near it.
Avoidance geometry
Relevant risky, marginal, and stale reports are converted into approximate square GeoJSON polygons with a half-width of about 60 metres. These polygons are sent to ORS as avoidance areas.
To reduce unnecessary provider requests, avoidance candidates are generated from relevant observations within a 2 km corridor of the baseline geometry. However, every returned candidate is scored against all active reports, including observations outside this corridor.
This distinction matters: candidate generation is deliberately bounded, while route evaluation still considers the wider report catalogue.
Ranking function
Each candidate receives a lexicographic score:
Score(r) = (D(r), C(r), W(r), T(r)) where:
- D(r) = number of unique damaging exposures.
- C(r) = number of unique caution-level or stale exposures.
- W(r) = maximum qualitative reported depth encountered.
- T(r) = estimated travel time in seconds.
The planner minimizes these components in order. Fewer damaging exposures take priority over caution exposures, and travel time is used only after the exposure-related criteria.
This avoids using arbitrary weighted sums that might trade an additional damaging exposure for a slightly shorter journey.
5. Algorithmic Time Complexity
Let n be the number of active reports, k the number of stops, c the number of candidates evaluated, and s the number of route segments per candidate.
The implementation bounds k at four, c at four, and the stored report count at 10,000.
Operation | Time complexity |
|---|---|
Validate distinct stops | O(k²) |
Classify reports and prepare selected buffers | O(n + a) |
Build spatial grid | Expected O(n) |
Parse provider geometries | O(cs) |
Exposure scoring with grid indexing | Expected O(n + c(G + H + n)) |
Exposure scoring, worst case | O(cns) |
Sort candidates | O(c log c) |
Exact geometry deduplication | O(c²L) |
Here, a denotes the number of selected avoidance reports, G the number of grid cells visited, H the number of candidate point visits across route segments, and L the serialized geometry size.
The grid uses geographic cells approximately 0.005 degrees wide to narrow candidate searches. Exact distance checks then filter the returned points.
The worst-case scoring complexity remains O(cns) because dense cells or long-segment fallbacks can require extensive report scanning. Since c is small and n is bounded, the approach is practical for the current pilot, but it is not constant-time or a guarantee of nationwide scalability.
Network latency is separate from these local complexity bounds and may dominate a routing request.
6. Community Reports and Data Integrity
Users can submit observations with coordinates, a qualitative depth level from 1 to 4, an optional name, and an optional JPEG or PNG photo.
Reports close to an existing community observation may be merged within a 65-metre radius. Merging preserves the maximum reported depth and can add an independent confirmation. Users cannot confirm their own report or vote twice on the same report, and nearby-coordinate checks constrain voting.
A report is considered stale after at least one hour without confirmation. At least two dismissals, with dismissals outnumbering confirmations, are required to clear it.
The displayed agreement indicator uses add-one smoothing:
Confidence = round(100 × (confirms + 1) / (confirms + dismisses + 2)) This is an agreement indicator, not a calibrated flood probability or proof that a road is clear.
Concurrent writes use revision-based optimistic concurrency. The storage layer checks whether the revision has changed before accepting an update and retries conflicting mutations up to five times.
For demonstrations, the seed catalogue contains 500 hotspots and 6,505 simulated cases. Their coordinates were obtained through ORS road snapping, but their counts, depths, and freshness are simulated. They must not be presented as verified live flood incidents.
7. AWS Architecture and Deployment
AWS provides the application's hosting, compute, persistence, security boundaries, and operational monitoring.
The deployment targets
us-east-1 (Northern Virginia) and uses AWS SAM with CloudFormation to define and provision the serverless infrastructure.Request flow in AWS
- Amazon CloudFront serves the frontend over HTTPS from a private Amazon S3 website bucket using Origin Access Control (OAC).
- Requests to
/api/*are forwarded through CloudFront to Amazon API Gateway's HTTP API.
- AWS Lambda executes the Node.js 24 ARM64 backend.
- Amazon DynamoDB stores revisioned report snapshots, confirmations, dismissals, and associated application state.
- A separate private S3 bucket stores report photos, served through the API rather than exposed as public objects.
- Lambda communicates with OpenRouteService for directions and Photon for geocoding. The browser loads OpenStreetMap tiles directly from the tile provider.
AWS services and responsibilities
- AWS Lambda: Serverless request processing, routing orchestration, report management, and provider integration.
- Amazon API Gateway: HTTP API endpoints, same-origin integration, and request throttling.
- Amazon S3: Private static website assets and private report-photo storage.
- Amazon CloudFront: Global HTTPS delivery and frontend caching; API caching is disabled.
- Amazon DynamoDB: On-demand persistence, conditional writes, consistent reads, and point-in-time recovery.
- AWS Secrets Manager: Versioned management of the server-side ORS API key, referenced by the deployment configuration.
- AWS IAM: Scoped permissions for Lambda access to storage, logging, and other required AWS resources.
- Amazon CloudWatch: Application logs and alarms for Lambda errors, throttling, and duration.
- Amazon SNS: Email delivery for operational alerts.
- AWS Budgets: Account-wide monthly spending alerts.
- AWS SAM and AWS CLI v2: Infrastructure validation, deployment automation, account checks, and resource management.
The documented deployment workflow runs quality checks, validates the SAM template, provisions infrastructure, publishes frontend assets, invalidates CloudFront caches, and performs HTTPS smoke checks.
The API uses a 25-second Lambda timeout, with memory configurable from a 2,048 MB default. The gateway is configured for a rate of 10 requests per second and a burst of 20. Photos have a 30-day S3 lifecycle, and application logs are retained for 14 days.
Provider credentials remain server-side, and AWS runtime access uses the Lambda execution role. API responses are not cached so that report and session data are not served from a stale shared cache.
8. Testing and Reliability
The project includes multiple verification layers:
-
npm run checkfor the project's configured quality checks.
-
npm run test:httpfor isolated HTTP integration tests using temporary SQLite storage and mocked ORS responses.
-
npm run test:e2efor live routing and asset smoke tests against a configured server, consuming provider quota.
- Deployment smoke checks for health, bootstrap data, essential assets, and optionally real route generation.
Tests cover input validation, geospatial calculations, route ranking, detour constraints, provider failures, concurrent persistence, reporting rules, and deployment behavior.
Missing credentials, quota exhaustion, network failures, malformed provider responses, and baseline no-route outcomes are not treated as evidence of a clear road. Only documented avoidance no-route outcomes can retain baseline routes, and those results must carry a visible warning.
9. Limitations and Future Improvements
PaaniPath compares returned candidates; it does not prove global route optimality, use a live-traffic model, or verify physical flood conditions. Vehicle profiles rely on qualitative thresholds, and the approximate avoidance zones do not represent surveyed flood boundaries.
The current storage design rewrites a shared snapshot, creating a potential contention point as usage grows. Visible browser tabs poll the complete report catalogue every five seconds, even when the revision is unchanged. Production expansion would benefit from regional partitioning, incremental updates, stronger moderation and identity controls, shared provider-quota coordination, and more scalable spatial indexing.
The PWA caches application assets and queues a limited number of unsent reports, but maps and routing are not available offline.
Conclusion
PaaniPath combines hosted road directions with explicit geospatial scoring, vehicle-dependent report classification, bounded route comparison, and community-driven observations. Its technical contribution lies in the orchestration and ranking of provider-generated candidates, not in claiming to replace established navigation engines.
By combining transparent algorithms with a modular backend and an AWS serverless deployment architecture, PaaniPath provides a practical foundation for waterlogging-aware travel decisions in Delhi NCR while keeping uncertainty and operational constraints visible.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article