BWSSB Borewell Dashboard — IISc

An interactive dashboard for exploring BBMP's 198 wards and the borewell sensors reporting inside them. Built by the Indian Institute of Science team for BWSSB.

• Live URL (once deployed): https://<your-user>.github.io/bbmp-borewell-dashboard-iisc/
• Codebase: static HTML/JS/CSS (this repo). Two data modes: (a) read data/*.json shipped with the site, or (b) call a Cloudflare Worker + D1 API. Switch via js/config.js.
• Cost: free at current scale (GitHub Pages + Cloudflare Workers free tier + D1 free tier).

If you're brand new here, read START_HERE.md first — it walks through viewing locally, publishing to GitHub Pages, and refreshing data.

Repo layout

Dashboard_IISC_for_BWSSB/
  index.html                        Dashboard entry (map + overlays). Includes Leaflet + Chart.js via CDN.
  css/style.css                     All styles. Slate/teal palette, minimal chrome, no default sidebars.
  js/                               Front-end, split from the former single app.js into ordered
                                    classic scripts that share one global scope (zero build step).
    config.js                       Data source switch: "static" (JSON files) or "api" (Worker).
    session-quality.js              Pump-session quality policy (parity with backend).
    state/store.js                  Single source of truth for mutable state + Store.set/subscribe.
    config/constants.js             Lens guard, trend thresholds, palette, notifyError banner.
    core/api.js                     Data-access layer: urlOf/seriesUrlOf, resilient getJson, analytics loaders.
    core/classification-helpers.js  Ward style/status/colour helpers + shared utils.
    core/groundwater.js             Groundwater criticality (Theil-Sen + linear + Modified MK), lens logic.
    core/data.js                    boot(), loadData, sensor-inventory merge, point-in-polygon.
    ui/selection.js                 Pan / ward selection, choropleth palette, choroColor.
    ui/metrics-query.js             KPI cards, metrics, common query, presets.
    ui/map-layers.js                initMap, ward + sensor rendering, legend.
    ui/controls.js                  Toolbar, overlays, search, filters.
    ui/detail.js                    Ward + sensor detail panels.
    ui/charts.js                    Session reconstruction + water/discharge/modal charts.
    bootstrap.js                    fmtDate, rainfall CSV, global listeners, final boot() call (loads last).
    app.js                          DEPRECATED placeholder (old monolith); no longer loaded.
                                    See docs/ARCHITECTURE.md for the module map and load order.

  data/                             Data files served by the static site.
    manifest.json                   Snapshot summary (KH ZIP name, dates, counts).
    wards.geojson                   198 ward polygons + area, population, sensor counts.
    sensors.json                    Per-sensor metadata (uid, lat, lng, ward, HP, depth, coverage).
    sensor_series/<uid>.json        Per-sensor time series (water level, discharge, cumulative yield).

  backend/                          Python scripts that build data/ from raw sources.
    prepare_data.py                 Reads KH ZIP + ward shapefile + population xlsx -> writes data/*.
    sensors_db_extract.py           Pulls sensors table from your Neon Postgres DB (adds motor HP + full UID list) -> data/sensors_db.json.
    requirements.txt

  worker/                           Cloudflare Worker + D1 (optional, for scale).
    src/index.js                    The Worker itself: JSON API over the D1 database.
    wrangler.toml                   Worker + D1 binding config. Fill in your D1 database_id.
    schema.sql                      D1 tables: wards, sensors, sensor_series, snapshots.
    seed_d1.py                      Reads ../data/*.json and writes seed_generated/*.sql for wrangler to execute.
    seed_generated/                 (git-ignored) chunked SQL files produced by seed_d1.py.
    README.md                       End-to-end D1 deploy steps.

  .github/workflows/deploy.yml      GitHub Actions: on push to main -> deploy static site to GitHub Pages.
  .gitignore                        Excludes _to_delete/, .env, __pycache__, seed_generated/, etc.
  start_server.bat                  One-click local dev server (Windows).
  START_HERE.md                     Quickstart for viewing, publishing, refreshing data.
  README.md                         (this file)

Architecture at a glance

Two swappable data modes, one frontend:

                            Static mode (default)
                            ─────────────────────
     ┌────────────┐   fetch ┌───────────────┐
     │  Browser   │────────>│ GitHub Pages  │──> serves data/*.json directly
     └────────────┘         └───────────────┘

                            API mode (Cloudflare + D1)
                            ─────────────────────────
     ┌────────────┐   fetch ┌────────────────┐  SQL   ┌───────┐
     │  Browser   │────────>│ Cloudflare Wkr │───────>│  D1   │
     └────────────┘         └────────────────┘        └───────┘
              (js/config.js chooses which)

The static mode has zero moving parts and is fine while total data stays under a few hundred MB. The API mode scales to years of historical data on Cloudflare's free tier (5 GB D1, 100k Worker requests/day) and is the path for when you want the dashboard to answer live queries.

This is the beginning of the README. Read the rest at the original. Read the full README ↗