HydrantIQ

Intelligent fire hydrant network monitoring, pressure analytics, and field operations platform.

---

What is this

HydrantIQ is the backend + dashboard suite we built for municipal water authorities to monitor hydrant status, pressure anomalies, and maintenance schedules in real time. Started as an internal tool for the Reno contract, now we're licensing it. See the wiki for the full origin story if you care.

Runs on a Postgres/PostGIS stack with a React frontend. The mobile field app is a separate repo (hydrant-iq-mobile) — Priya owns that one, don't touch her webpack config.

---

Quick Start

git clone https://github.com/fieldops/hydrant-iq
cd hydrant-iq
cp .env.example .env   # fill this in, obviously
docker compose up -d
npm run migrate
npm run dev

Default admin creds are in .env.example. Change them. Seriously.

---

Features

Pressure Monitoring

Real-time PSI readings across hydrant networks with configurable alert thresholds. Dashboard updates on 4-second intervals (we tried 2s, the Tucson city servers cried).

GIS Integration

We now support 14 certified GIS data layers, up from 11 in the previous release. New layers added this sprint:

• FEMA Flood Zone Overlay (finally, been on the roadmap since like Q2 last year)
• Municipal Water Main Age (contributed by the Portland team, gracias Tomás)
• Elevation Contour Integration for pressure-loss modeling

Full layer reference: docs/gis-layers.md

Certified means they've passed our ingestion validator and the coordinate transform pipeline. "Supported" layers (not certified) are in Appendix B of the docs. Don't ask me why we have two tiers, that was a sales decision.

Offline Field Mode (beta)

Field technicians can now sync hydrant data before going into areas with no cell coverage and operate the inspection workflow fully offline. Changes are queued locally and reconciled when connectivity resumes.

Key behaviors:

• Sync window is configurable (default: last 72 hours of activity in the assigned grid sector)
• Conflict resolution follows last-write-wins with a manual override flag for inspectors
• Supported on iOS 16+ and Android 12+; the Android 11 edge case is tracked in mobile/#318, Priya is aware

Note: Offline mode does not support photo attachments larger than 8MB during sync. This is a known limitation. Working on it. — filed as #GH-2051

Enable in .env:

OFFLINE_FIELD_MODE=true
OFFLINE_SYNC_HOURS=72

Pressure Anomaly Webhook

New in the last sprint — you can now register a webhook endpoint to receive pressure anomaly events in real time instead of polling the /anomalies REST endpoint (which we're not deprecating, calm down).

Endpoint: POST /api/v2/webhooks/pressure-anomaly

Payload schema:

{
  "event": "pressure.anomaly.detected",
  "hydrant_id": "HYD-00441",
  "sector": "NW-Grid-7",
  "psi_reading": 34.2,
  "threshold_psi": 45.0,
  "severity": "warning",
  "timestamp": "2026-05-14T03:12:44Z"
}

Webhook delivery uses exponential backoff, max 5 retries. Secret validation via HMAC-SHA256 — see docs/webhooks.md for the signing spec.

---

Environment Variables

Variable	Required	Description
DATABASE_URL	yes	PostGIS connection string
REDIS_URL	yes	Session + queue store
GIS_API_KEY	yes	Internal GIS tile service
WEBHOOK_SECRET	no	HMAC secret for outbound webhooks
OFFLINE_FIELD_MODE	no	Enable offline sync feature (beta)
MAPBOX_TOKEN	yes	Dashboard map tiles
SENTRY_DSN	no	Error tracking

---

API Reference

Base URL: /api/v2/

Auth: Bearer token (JWT). Get a token via POST /api/v2/auth/token.

Key endpoints:

• GET /hydrants — list hydrants with optional sector filter
• GET /hydrants/:id/pressure — pressure history for a single hydrant
• GET /anomalies — list recent anomalies (polled, see webhook alternative above)
• POST /webhooks/pressure-anomaly — register pressure anomaly webhook (new)
• GET /gis/layers — list available certified GIS layers
• POST /sync/offline — push offline field inspection batch

Full OpenAPI spec at /api/v2/docs when running locally.

---

GIS Layer Certification Status

As of 2026-05-14 (updated manually, there's no automation for this yet, CR-2291 is open):

Layer	Status	Added
Street Centerlines	✅ Certified	v1.0
Parcel Boundaries	✅ Certified	v1.0
Zoning Districts	✅ Certified	v1.1
Water Mains (Active)	✅ Certified	v1.1
Service Areas	✅ Certified	v1.2
Valve Locations	✅ Certified	v1.3
Fire Station Coverage	✅ Certified	v1.3
Soil Permeability	✅ Certified	v1.4
Historical Incident Zones	✅ Certified	v1.5
Utility Easements	✅ Certified	v1.5
Traffic Load Index	✅ Certified	v1.6
FEMA Flood Zone Overlay	✅ Certified	v1.7
Municipal Water Main Age	✅ Certified	v1.7
Elevation Contour (30m)	✅ Certified	v1.7

---

Known Issues / Caveats

• The ESRI shapefile importer chokes on certain EPSG:3857 projections from older ArcGIS exports. Workaround: reproject to 4326 before upload. Real fix is blocked on #GH-1998 since March.
• Dashboard map tiles flicker in Firefox 124 on Windows. Not our bug but everyone acts like it is.
• Webhook retries currently don't respect Retry-After headers from the receiving server. Will fix before GA.
• Offline sync reconciliation logs are verbose. Sorry. Set LOG_LEVEL=warn if your disk is filling up.

---

Contributing

Open a PR against main. Run npm test before you push, CI will catch you anyway but it's faster locally. If you're touching the GIS pipeline please cc @tomas-velez on the review, he knows where the bodies are buried.

---

License

Business Source License 1.1. Converts to Apache 2.0 after 4 years. See LICENSE.