JalSeva (जलसेवा)
Real-Time Water-Tanker Marketplace for Bharat

Acknowledgement

I take this opportunity to express my profound sense of gratitude to my capstone mentor, Dr. Abhishek Tomar, Yogananda School of AI, Computers and Data Sciences, Shoolini University, for his expert guidance, candid feedback and constant encouragement throughout the conception, design and execution of this work. His insistence on engineering rigour and his patient review of intermediate prototypes shaped the project at every milestone.

I am thankful to the faculty of the Department of Computer Science & Engineering for providing me with the academic environment and the infrastructural support that made an end-to-end production-grade build possible within a single semester. I also acknowledge the staff of the Yogananda School for the administrative scaffolding around the capstone programme.

I extend my sincere thanks to the open-source maintainers of Next.js, Firebase, Google Cloud Run, Google Maps Platform and TypeScript — every layer of the system I built rests on tooling they ship and support, free of cost, to students like me.

I am deeply grateful to my family and friends for the moral support, the late-night patience, and the willingness to be field-test users when the application first stumbled out of localhost and onto a public URL.

Finally, I take responsibility for any errors that remain in this report or in the deployed system. They are mine alone.

Abstract

Approximately 163 million Indians lack reliable access to clean piped water and rely on privately-operated water-tanker deliveries, an informal supply chain plagued by opaque pricing, no order tracking, and weak accountability. JalSeva is a production-grade, multi-tenant water-tanker marketplace that brings the on-demand ride-hailing experience to this market: customers place an order in three taps, suppliers receive it in real time, live GPS tracking persists through delivery, and the lifecycle terminates in a rated, receipt-backed transaction.

This report documents the design, implementation, security posture and serverless deployment of JalSeva as the author's BTech capstone project. The application is built on Next.js 16 with React Server Components, Firebase Phone Authentication for identity, Cloud Firestore for the real-time data plane, and Google Maps Platform for geocoding and routing. The runtime is Google Cloud Run in the asia-east1 region, configured for scale-to-zero economics. A defining engineering choice — replacing the conventional embedded Firebase Admin private key with a runtime IAM service-account and Application Default Credentials (ADC) — eliminates the most common credential-leakage vector in serverless Node.js deployments.

The platform is live at jalseva.dmj.one and is reproducible from source with a single gcloud run deploy invocation. End-to-end demonstration is supported on two physical devices: one acting as customer, one as supplier, with sub-second propagation of GPS updates from supplier to customer's map view via Firestore onSnapshot. Key performance optimisations include in-process L1 caching, a 500-millisecond write-coalescer that collapses 5–20 GPS updates into one Firestore write, and a geohash-based spatial index for nearby-supplier search in O(k) instead of O(n).

Keywords: on-demand logistics, water supply, Firebase, Cloud Run, real-time tracking, GPS, IAM, ADC, serverless, Bharat, PWA, Next.js.

Table of Contents

• 1.Introduction & Problem Definition6
• 2.System Requirements8
• 3.System Architecture & Design10
• 4.Technology Stack13
• 5.Implementation15
• 6.Algorithms / Models18
• 7.Testing20
• 8.Results & Performance Analysis22
• 9.Deployment24
• 10.Challenges & Solutions26
• 11.Conclusion & Future Scope28
• 12.Viva-Voce Questions30
• 13.References32

List of Figures

• Fig 3.1High-Level System Architecture10
• Fig 3.2Order Lifecycle State Machine11
• Fig 3.3Real-Time GPS Tracking Data Flow12
• Fig 4.1Technology Stack Layers13
• Fig 5.1Sign-In Sequence Diagram (Phone OTP + ID-Token)15
• Fig 5.2Order Acceptance & Live Dispatch17
• Fig 9.1Cloud Run Deployment Topology24

List of Tables

• Table 2.1Functional Requirements8
• Table 2.2Non-Functional Requirements9
• Table 3.1Firestore Collection Schema11
• Table 4.1Technology Choices & Rationale14
• Table 7.1Test Matrix Summary20
• Table 8.1Performance Benchmarks22
• Table 9.1Cloud Run Service Configuration25

1. Introduction & Problem Definition

1.1 Background

India's Census 2011 reports that only about 43% of households have piped water at the dwelling premises. The National Sample Survey Office (NSO, 2018) further documented continued reliance on shared and externally-sourced supply, particularly in peri-urban settlements and tier-2/3 towns. Where municipal supply is intermittent or absent altogether, privately-operated water-tankers serve as the de-facto infrastructure for daily living. Estimates from the Ministry of Jal Shakti place this dependent population at approximately 163 million people, with the sharpest concentrations in summer months across Rajasthan, Gujarat, Maharashtra, Karnataka and the National Capital Region.

Yet, unlike auto-rickshaws (which Ola and Uber digitised) or restaurant food (which Swiggy and Zomato digitised), the water-tanker logistics layer has remained almost entirely analog. The customer phones a number; the supplier or driver answers if they choose to; pricing is negotiated verbally; and the tanker may or may not arrive in the promised window. There is no consumer-facing platform that delivers the three primitives the rest of the on-demand economy now takes for granted: real-time matching, transparent pricing, and live tracking.

1.2 Problem Statement

The incumbent ordering pattern in tier-2/3 India produces four concrete failure modes:

1. No tracking. The customer cannot tell whether the tanker is on its way, delayed, or simply not coming.
2. No price transparency. Per-call pricing varies; surge pricing is opaque and arbitrary; receipts are rare.
3. No accountability loop. A no-show carries zero consequence for the supplier; a punctual driver earns no reputation upside.
4. No language accessibility. Existing fragmentary digital alternatives are English-first, while the customer base is heavily Indic-language and includes low-literacy users.

The objective of this capstone is therefore to design, build and deploy a single mobile-installable application that addresses all four failure modes simultaneously, while remaining operable on entry-level Android phones over slow networks.

1.3 Target Users

• Households in tier-2/3 India that depend on private tankers, especially during summer scarcity.
• Resident Welfare Associations (RWAs) coordinating bulk supply for an apartment complex or colony.
• Independent tanker operators currently dependent on a fragmented voice-call order book.
• Government and CSR programmes (Jal Jeevan Mission, district administrations) seeking visibility into the informal supply layer.

1.4 Scope of the Project

The project is bounded to delivering a working, multi-device, production-deployed system that demonstrates: phone-OTP authentication with role selection, customer order placement, supplier acceptance, live GPS tracking, status transitions, and order completion. KYC, real payment settlement, ONDC integration and WhatsApp-bot ordering are scaffolded but not commissioned within the capstone window; they are explicitly listed as future work.

2. System Requirements

2.1 Functional Requirements

Table 2.1 enumerates the user-facing functional requirements that the deployed system must satisfy.

Table 2.1 — Functional Requirements

2.2 Non-Functional Requirements

Table 2.2 — Non-Functional Requirements

2.3 Hardware / Software Requirements (Build & Run)

• Development: Windows 11 / macOS 13+, Node.js 22 LTS, pnpm 10.30, VS Code, Git.
• Deployment target: Google Cloud Run, Artifact Registry, Firestore (asia-south2), Firebase Auth (Identity Toolkit).
• Client: Any modern mobile browser supporting Service Workers and the Geolocation API.

3. System Architecture & Design

3.1 High-Level Architecture

The system follows a serverless, BaaS-leaning architecture in which the Next.js application acts as a thin coordination layer above managed services. All state — authentication, user profiles, orders, supplier presence, tracking — lives in Cloud Firestore. The application runs in stateless Cloud Run containers that scale from zero to N instances based on traffic, addressed behind Cloudflare-fronted HTTPS at jalseva.dmj.one.

Fig 3.1 — High-Level System Architecture

3.2 Order Lifecycle State Machine

Fig 3.2 — Order Lifecycle State Machine

3.3 Firestore Collection Schema

Table 3.1 — Firestore Collection Schema

3.4 Real-Time GPS Tracking Data Flow

Fig 3.3 — Real-Time GPS Tracking Data Flow

4. Technology Stack

4.1 Layer-by-Layer

Fig 4.1 — Technology Stack Layers

4.2 Choices & Rationale

Table 4.1 — Technology Choices & Rationale

5. Implementation

5.1 Authentication Flow

The /login page uses the Firebase JavaScript SDK's signInWithPhoneNumber with an invisible RecaptchaVerifier. After OTP confirmation, the client requests a Firebase ID token and passes it to a Next.js server action.

Fig 5.1 — Sign-In Sequence (Phone OTP + ID-Token)

5.2 Customer Order Placement

The landing page uses the browser Geolocation API to auto-detect the customer's coordinates, reverse-geocoded via the Maps Geocoding API. The customer picks water type and quantity; a pricing function computes the total inclusive of surge. On confirm, a createOrder server action writes orders/{id} via the Firebase Admin SDK in a batch, populating the order with status searching.

5.3 Supplier Reception & Acceptance

Once authenticated and online, the supplier client holds an onSnapshot listener on orders filtered by status == 'searching'. New orders enter the dashboard's pending queue with a 30-second countdown. On accept, the supplier's hook performs an atomic updateDoc assigning supplierId and transitioning status → accepted.

Fig 5.2 — Order Acceptance & Live Dispatch

5.4 Live GPS Broadcast

Inside /supplier/delivery/[orderId], a useEffect registers navigator.geolocation.watchPosition with high-accuracy mode. Each callback throttles to one POST per 5 seconds against /api/tracking. The route handler verifies the supplier owns the order, computes a Haversine ETA, updates the L1 cache, kicks an async Maps Routes call for polyline refinement, and pushes the write into a 500-millisecond coalescer that ultimately writes orders/{id}.tracking once per window.

5.5 Project Layout (key files)

6. Algorithms / Models

6.1 Haversine ETA

The hot path computes ETA synchronously without blocking on the Maps Routes API by using the Haversine great-circle distance and an assumed city-driving speed of ~30 km/h. Given supplier coordinates (φ₁, λ₁) and drop coordinates (φ₂, λ₂) with Earth radius R = 6371 km:

Sub-microsecond evaluation, with the Maps Routes API result populating an L1 cache asynchronously for a more accurate polyline on subsequent reads.

6.2 Geohash Spatial Index for Nearby Suppliers

Suppliers are indexed by a 6-character geohash (~1.2 km cell). To find suppliers near a query point, the system computes the geohash of the query and its 8 neighbours, then scans only that 9-cell neighbourhood — converting an O(n) full-collection scan into an O(k) bucket lookup.

6.3 Write Coalescer

GPS updates from a moving tanker arrive at ~1 Hz. Writing each to Firestore would burn quota and serialise on the document. A coalescer batches all writes to the same (collection, docId) within a 500 ms window and emits a single merged write to Firestore. Pseudocode:

6.4 Token-Bucket Rate Limiter

Per-IP API throttling is enforced in Next.js middleware using an in-memory token bucket: burst capacity 100, sustained refill 50 tokens/second. A separate global bucket caps the entire instance at 60K bursts / 50K sustained. Eviction of stale buckets is amortised on each consume() call.

7. Testing

7.1 Strategy

A test pyramid was applied: unit tests on pure functions, integration tests on critical API handlers, and a manual scripted end-to-end run across two physical devices for the live demo. Type-checking via TypeScript's strict mode acts as a compile-time test of structural correctness.

7.2 Test Matrix

Table 7.1 — Test Matrix Summary

7.3 End-to-End Scenarios

1. Happy path. Customer logs in → places order → supplier accepts → GPS moves → delivered.
2. Customer cancels during search. Order transitions to cancelled; supplier sees it disappear from queue.
3. Supplier denies location permission. GPS indicator shows "denied"; customer side falls back to static "Accepted, awaiting GPS" state.
4. Cold start. First request after idle: Cloud Run boots in < 8 s; subsequent requests serve in < 200 ms.
5. Bad OTP. Three retries supported with countdown; reCAPTCHA re-rendered on fourth.

8. Results & Performance Analysis

8.1 Functional Outcome

All ten "Must" functional requirements (FR-1 through FR-10) listed in Table 2.1 were achieved and verified end-to-end on the production URL. Two "Should" requirements were also commissioned (customer cancellation, admin analytics).

8.2 Performance Benchmarks

Table 8.1 — Performance Benchmarks

8.3 Cost Analysis

Idle cost is dominated by Artifact Registry storage (~₹3/month per image revision) and Firestore at-rest storage (negligible at MLP volumes). All other services are charged per-request; under the GCP free tier and Firebase free quotas, the platform serves up to ~50 K verifications/month, ~50 K Firestore reads/day and ~20 K writes/day at zero cost.

9. Deployment

9.1 Topology

Fig 9.1 — Cloud Run Deployment Topology

9.2 Service Configuration

Table 9.1 — Cloud Run Service Configuration

9.3 Continuous Delivery

A single command performs source-to-running deployment, eliminating manual image-build steps:

10. Challenges & Solutions

10.1 Credential Leakage Risk

Challenge. The conventional Firebase Admin SDK initialisation requires embedding a service-account private key, which is highly vulnerable to leakage via build logs, environment-variable dumps or compromised images.

Solution. The Admin SDK initialisation in src/lib/firebase-admin.ts detects the Cloud Run environment (via K_SERVICE) and falls back to applicationDefault(), which obtains short-lived tokens from the GCE metadata server bound to the Cloud Run service's IAM service account. Zero private keys ever exist inside the container or its environment.

10.2 Demo Cost on Phone OTP

Challenge. Live demonstrations require multiple OTP verifications, each costing real SMS spend.

Solution. Five Firebase Auth test phone numbers were registered with fixed OTPs (+91 99999 00001 → 123456, etc.). Firebase short-circuits these locally without dispatching SMS, enabling unlimited demo runs at zero cost.

10.3 Cluster vs Cloud Run

Challenge. The upstream codebase ships a server.cluster.js forking one worker per CPU core. Cloud Run allocates one vCPU per instance by default, making clustering inside a container counterproductive.

Solution. The Dockerfile forces CLUSTER_WORKERS=1 in production and starts the Next.js standalone server directly. Cloud Run handles horizontal scaling by adding instances rather than forking workers.

10.4 Public Client Keys (Firebase / Maps)

Challenge. The Firebase Web API key and Google Maps client key must be present in the client JavaScript bundle and are therefore inherently extractable by anyone using DevTools on the deployed site.

Solution. Restrict by reach instead of by secrecy. The Maps key is HTTP-referrer-restricted to https://jalseva.dmj.one/* and localhost; Firebase Authentication's authorised-domains list rejects sign-in attempts from any unlisted origin. The keys remain visible but unusable elsewhere.

10.5 Bandwidth Constraints in Bharat

Challenge. The target users are often on 3G / slow 4G with intermittent connectivity.

Solution. Next.js standalone output strips dev dependencies; output: "standalone" reduces the deployable to < 50 MB container. The PWA registers a Serwist-managed service worker to enable offline shell load. Tracking falls back to L1/L2-cached values when the network blips.

11. Conclusion & Future Scope

11.1 Conclusion

JalSeva demonstrates that the on-demand logistics pattern — real-time matching, live GPS tracking, transparent pricing — can be transplanted to India's informal water-tanker supply chain on serverless infrastructure that costs effectively zero rupees per idle hour. The implementation favours managed services over hand-rolled backends and treats the deployed image as a hostile surface by binding all server-side credentials to a single IAM service account rather than embedded private keys. The result is a complete, multi-device-capable application built to capstone scope, deployed live at jalseva.dmj.one, and engineered to scale without rewrites should it leave the academic context.

11.2 Future Scope

• ONDC/Beckn handshake so JalSeva's supplier inventory is discoverable by any participating Buyer App in the Open Network for Digital Commerce.
• WhatsApp ordering channel for low-literacy and elderly users via the WhatsApp Business API, with Gemini-mediated language translation.
• Demand prediction using Gemini + Firestore order history to pre-stage tankers in high-demand zones during peak summer months.
• Supplier-side route optimisation when multiple deliveries are accepted in sequence — Hamiltonian shortest path on the day's drop graph.
• End-to-end automated testing via Playwright executing the customer + supplier flow nightly against a staging Cloud Run instance.
• Hardware integration with low-cost flow-sensors on the tanker outlet to publish litres-delivered telemetry, eliminating disputes about quantity.

12. Viva-Voce Questions

Q1. What real-world problem does the project solve, and who are the target users?

It digitises the informal water-tanker order book in tier-2/3 India: customers gain price transparency and live GPS tracking, suppliers gain steady demand without middlemen. Target users are households without piped supply, RWAs aggregating bulk demand, and independent tanker operators.

Q2. Why this technology stack over alternatives?

Next.js + Cloud Run gives one codebase for client and server with scale-to-zero economics; Firestore provides sub-second real-time propagation without a hand-rolled WebSocket layer; Firebase Phone Auth offers a free tier of 50K verifications/month plus a test-numbers facility for zero-cost demos. Alternatives (Postgres + Supabase, Twilio SMS, GKE) were ruled out on cost, integration friction or operational overhead.

Q3. Explain the system architecture.

Three client surfaces (Customer PWA, Supplier PWA, Admin) talk to one stateless Next.js service running in Cloud Run. The service authenticates via Firebase, persists state in Firestore, and uses Maps Platform for geocoding/routing. All credentials live as IAM bindings on the Cloud Run service account; nothing sensitive is embedded in the container image.

Q4. How will the system handle scaling from 100 to 10,000 users?

Cloud Run autoscales by instance count up to a configurable cap; Firestore scales linearly to millions of QPS. The first bottleneck at this volume would be Firestore quota per document on hot orders — already mitigated by the 500-ms write coalescer. The next step would be raising Cloud Run max-instances and adding regional Firestore replicas.

Q5. What security measures have been implemented?

Phone OTP authentication with ID-token verification on the server; httpOnly session cookie scoped to the domain; IAM-bound runtime service account replacing embedded service-account keys; Maps key restricted by HTTP referrer; Firebase authorised-domains list; OWASP-recommended security headers in middleware (X-Frame-Options, Referrer-Policy, Permissions-Policy); token-bucket rate-limiting at the edge.

Q6. The biggest development challenges, and how were they solved?

Three stand out: (i) the cluster server inherited from the upstream design conflicted with Cloud Run's single-vCPU instances — resolved by forcing CLUSTER_WORKERS=1; (ii) credential leakage risk was eliminated by switching to ADC; (iii) demo OTP cost was eliminated by registering test phone numbers in Firebase.

Q7. How was the system tested for reliability?

A test pyramid: Vitest unit tests on pure functions (Haversine, geohash, rate-limiter), integration tests on API handlers, TypeScript strict mode as a compile-time test, and end-to-end manual runs across two physical devices on the live URL. Lighthouse scores ≥ 90 on the PWA audit.

Q8. If the system fails in production, how is recovery handled?

Cloud Run revisions are immutable — rollback to the previous revision is a single command. Application-layer circuit breakers shed load on dependent-service degradation. Logs and metrics flow to Cloud Logging and Cloud Monitoring; alerts fire on p95 latency > 500 ms or error rate > 1%. Firestore offers point-in-time recovery as a paid feature.

Q9. What are the project's limitations and how can it improve?

Real payments are simulated; supplier KYC is auto-verified for demo; offline ordering is not implemented; the service is single-region. Each is listed as future work in §11.2.

Q10. If this were deployed as a startup, what are the next steps?

Pilot in one tier-2 town (e.g. Kalka, Solan, or Parwanoo): onboard 20 verified suppliers off Justdial, run free first deliveries for 1,000 households via RWA partnerships, then iterate on retention and unit economics. Parallelly, commission ONDC integration so JalSeva's inventory is discoverable by any Buyer App and we participate in the wider open-network economy.

13. References

1. Government of India, Census of India 2011 — Source of Drinking Water Tables. Office of the Registrar General & Census Commissioner, India.
2. National Sample Survey Office (NSO), Drinking Water, Sanitation, Hygiene and Housing Condition in India, NSS 76th Round, 2018.
3. Ministry of Jal Shakti, Government of India, Jal Jeevan Mission — Operational Guidelines, 2019.
4. Beckn Foundation, Beckn Protocol Specification v1.0, 2024.
5. Google Cloud, Cloud Run runtime contracts and service accounts, official documentation, 2024–2026.
6. Google, Firebase Authentication: Phone Auth + ID-token verification (Admin SDK), official documentation.
7. Google Maps Platform, Routes API, Geocoding API, JavaScript SDK, official documentation.
8. Niemeyer, Gustavo, The Geohash Geocoding System, 2008.
9. Vercel, Next.js App Router and Server Actions, official documentation, 2025–2026.
10. OWASP Foundation, OWASP Top Ten — 2021 Edition.
11. Mozilla Developer Network, Geolocation API: watchPosition(), web standards reference.
12. W3C, Web Content Accessibility Guidelines (WCAG) 2.2, 2023.
13. Akamai Technologies, State of the Internet — India Connection Speeds Report, 2023.