WaterQualityLens

A deterministic, address-level Public Water System (PWS) lookup and NSF/ANSI-verified filtration matching backend, built exactly to the Strategic Evaluation and Build Plan: WaterQualityLens.

The service accepts a US residential address and returns the supplying public water system, the contaminants detected there that exceed public-health goals, and the specific retail filter SKUs that are independently certified to neutralize those exact contaminants — never brand-level or fear-based claims.

This tool aggregates municipal engineering data and hardware certifications. It does not diagnose exposure risks, predict toxicological outcomes, or offer medical advice. (§13 non-dismissible disclaimer.)

---

Architecture (§15, §22 — Cloudflare-native edge)

Concern	Technology	Notes
API + orchestration	Cloudflare Workers	src/index.ts — fetch / scheduled / queue handlers
Primary datastore	Cloudflare D1 (edge SQLite)	PWS boundaries, SDWIS data, curated SKU/cert moat
Cache	Cloudflare KV	geocode + full-lookup + SDWIS payload caching
Background jobs	Cloudflare Queues	asynchronous alert delivery
Scheduling	Cron Triggers	weekly SDWIS ingestion + daily alert scan

The whole system is read-heavy and deterministic — no per-query LLM inference — so it runs within Cloudflare's free tier at launch scale (§15).

address ──▶ geocode C(lat,lon) ──▶ TEMM 3-tier resolve PWSID ──▶ SDWIS profile
                                                                       │
        unified JSON  ◀── set-cover filter match (D ⊆ ⋃ N_c)  ◀───────┘

---

The two core algorithms (§12)

1. TEMM deterministic spatial join (src/services/spatial.ts)

Strict, highest-fidelity-first hierarchy. The first tier that resolves wins, and the numeric confidence is emitted verbatim to the UI to manage legal expectations.

Tier	Test	Confidence	UI treatment
1 — Explicit	point ∈ verified utility service polygon	1.0	Explicit Boundary
2 — Matched	point ∈ TIGER place polygon matched to a utility proxy	0.85	Matched Proxy
3 — Modeled	Haversine d to nearest modeled centroid, d < R_model	0.50	Modeled Radius → yellow warning banner + lab-test advice

2. Constrained set-cover recommendation (src/services/setcover.ts)

Let D = detected contaminants exceeding health guidelines and N(f) = the union of contaminants a SKU is verified to reduce under a health standard. A SKU qualifies iff:

D ⊆ ⋃_{c ∈ C_f} N_c

• Only NSF/ANSI 53 / 58 / 401 may satisfy a hazard.
• NSF/ANSI 42 (aesthetic) and 372 (lead-free materials) are isolated and can never satisfy a health contaminant. Retired P473 is ignored.
• Artificial precision is prohibited: a SKU not verified for a specific compound is programmatically eliminated (partial matches never surface).
• Form-factor heuristics rank results (pitchers for multi-family rentals, under-sink RO for single-family homes) but never affect eligibility.

---

API

Method & path	Purpose
POST /api/lookup { address, zip?, dwelling_type?, nocache? }	Primary MVP lookup → §22 output contract
GET /api/lookup?address=…&nocache=1	Same, via query string (nocache=1 bypasses KV)
GET /api/lookup?zip=48503	Coarse ZIP fallback via SDWA_GEOGRAPHIC_AREAS registry
GET /api/pws/:pwsid	Programmatic PWS entity page data (+ SEO indexable gate, §9)
GET /api/contaminants / GET /api/contaminants/:code	Contaminant glossary entities
GET /api/filters / ?deceptive=1	Filter Certification Registry; flags 42/372-only deceptive SKUs (§9)
POST /api/auth/register · POST /api/auth/login	V1 accounts
GET/POST/DELETE /api/addresses · PUT /api/addresses/:id/alerts	Saved addresses + alert opt-in (V1)
GET /api/vault/report · POST /api/vault/lab-results[/import] · POST /api/vault/cartridges	Premium Household Water Vault
GET /api/health · POST /api/admin/ingest · POST /api/admin/alerts	Ops

POST /api/lookup response shape (§22 output contract)

{
  "query": { "address": "...", "normalized_address": "...", "dwelling_type": "SINGLE_FAMILY" },
  "coordinate": { "lat": 43.0125, "lon": -83.6875 },
  "match": { "pwsid": "MI0002360", "tier": "TIER_1_EXPLICIT", "confidence": 1.0,
             "tierLabel": "Explicit Boundary", "requiresLabTestWarning": false },
  "utility": { "pwsid": "MI0002360", "name": "City of Flint", "state": "MI", ... },
  "detected_contaminants": [ { "code": "PB90", "name": "Lead", "value": 27, "unit": "ug/L",
                              "mcl": 15, "exceeds_health_goal": true, "sample_date": "2026-05-15", ... } ],
  "active_violations": [ ... ],
  "recommended_filters": [ { "brand": "Frizzlife", "model": "M800 Under-Sink RO",
                             "certified_standards": ["58"], "neutralizes": ["PB90"],
                             "full_coverage": true, "score": 1.55, "affiliate_url": "..." } ],
  "nitrate_warning": null,          // set to RO-only guidance when nitrate/nitrite detected
  "multi_system_warning": false,    // true when a ZIP/address maps to >1 water system
  "multi_system_count": 1,
  "data_freshness": { "sdwis_fetched_at": "2026-07-01T00:00:00Z", "generated_at": "..." },
  "disclaimers": [ "...medical...", "...plumbing...", "...affiliate..." ],
  "meta": { "cache_hit": false, "engine_version": "1.0.0", "resolution": "TEMM" }
}

---

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