RSMS Task 4 — context overlays (map + UI)
This document captures near-term scope, technical fit with rsms-suite, and a phased rollout for subcontract Task 4 (“incorporate other databases”). It complements:
- rsms-threat-layers-backlog — layer backlog table (priority candidates).
- rsms-task4-and-r5-layer-catalog — Task 4 subcontract themes (linked sources +
[ ]/[x]status) and full R5-derived layer enumeration. - rsms-threat-layers-r5-mapping — how EPA Region 5 “State Mapping Projects” patterns relate to RSMS.
Scope lock (what we care about now)
Context-only. Show hydrologic monitoring, facilities, and infrastructure near the river so planners and scenario authors see real-world conditions and upstream context that matters operationally. This does not change Fortran plume math or ingestion of hydraulic outputs beyond existing RSMS flows (gages are display/context only unless separately wired into forcing—out of scope here).
Technical stack. Fits the current ArcGIS Maps SDK for JavaScript usage in rsms-frontend-react: GeoJSONLayer, Map, layer toggles, pop-ups/templates, and standard widgets—similar to existing Ohio basin/static GeoJSON wiring (see rsms-frontend-react/src/pages/map/ohioRiverbasinGeoJsonLayer.js).
More ambitious integrations (live federated queries, authenticated EPA portals, spill projection geometry rebuilt inside RSMS, etc.) are explicitly out of scope for the first slices.
Relationship to other RSMS work
| Topic | Where it lives |
|---|---|
| Time-stamped HEC-RAS binary flow files and API/worker changes | Task 3 route—handled outside this doc. Binary ingest paths are associated with riverflows-api-drf (not in this repo); RSMS consumes upgraded flows via existing integration patterns once published. |
| Ohio RiverFlows API usage for runs | Already used by worker/API flows in-suite; unrelated to Task 4 overlays except sharing the same map UX surface. |
| Results prefetch / charts / tables | See rsms-results-prefetch-design and results storage docs—not duplicated here. |
Architecture preferences (FastAPI vs frontend vs stored extracts)
Three ideas often coexist:
Thin backend proxy (FastAPI) — Centralizes API keys, caching, CORS, and logging. Useful when upstream services require server-side credentials or heavy normalization.
Call external services directly from the frontend — Fewer moving parts; aligns when stakeholders prefer not adding another hop. Works best for public endpoints with acceptable CORS and rate limits.
Self-hosted curated extracts (blob/static hosting or bundled GeoJSON) — RSMS-side snapshots + codified geography (reach IDs, mainstem/tributary, optional river-mile buckets) so the client does not repeat “within x miles of mile y” spatial filtering against raw national datasets on every session.
Practical recommendation: Ship two pilot overlays in order (USGS streamgages, then USACE bridges), using static or lightly refreshed GeoJSON, NWIS/feature APIs, or HTTPS Feature/Layer URLs keyed to RSMS river semantics; add FastAPI mediation only when a specific source forces it (auth, unstable CORS, or transform cost).
Pilot overlays (locked order)
Each pilot is one vertical slice end-to-end (toggle, legend, pop-ups/templates, attribution, documented refresh or API usage)—then reuse the same integration pattern for backlog layers.
| Pilot | Layer | Rationale |
|---|---|---|
| Pilot A | USGS streamgages | Already implemented in legacy RSMS; port map/UI behavior into this repo’s ArcGIS Maps SDK stack (GeoJSONLayer / feature layers). Provides immediate hydraulic context alongside scenarios and results. |
| Pilot B | USACE bridges | Matches subcontract Task 4 emphasis on railroad bridges, Corps-standard bridge linkage, and navigation-adjacent inventory; second overlay after gages are stable. |
Further regulatory/threat themes (NPDES, crossings, TRI, etc.) follow rsms-threat-layers-backlog.md after pilots A and B.
Phased rollout
| Phase | Goal | Typical delivery |
|---|---|---|
| 0 — Foundations | Layer toggle pattern, attribution/source links in UI, performance guardrails (scale-dependent rendering / clustering strategy decided per layer). | Extend map module alongside existing GeoJSON layers; document SRID and fields in backlog rows. |
| 1 — Pilot A | USGS streamgages ported from legacy RSMS (subset near modeled corridors). | GeoJSON snapshot and/or NWIS waterservices / maps-facing endpoints (watch CORS—proxy if needed); pop-ups with site metadata + NWIS links as in legacy. |
| 2 — Pilot B | USACE bridges (inventory aligned with subcontract Corps-standard bridge path). | Static GeoJSON or USACE/ArcGIS-hosted layer URL; confirm attribution and currency expectations vs engineering manuals. |
| 3 — Expand backlog | Additional themes from rsms-threat-layers-backlog.md ranked by OH relevance and licensing. | Same integration paths; shared legend/pop-up components where possible. |
| 4 — Optional mediation | Introduce FastAPI or worker-hosted ETL only where needed (credentials, pagination glue, merging multi-source attributes into RSMS codification keys). | Keep frontend reading one stable contract (geojson_url + schema version). |
EPA Region 5 “State Mapping Projects” alignment
EPA Region 5’s interactive mapping program is a useful catalog of layer themes and workflows (FRS-derived facility layers, pipe/rail crossing spill projections, downstream tracing concepts, reporting widgets). RSMS will not replicate that entire authenticated portal in phase 1–2.
See rsms-threat-layers-r5-mapping for a concise pattern → RSMS hook mapping.
Document history
| Date | Change |
|---|---|
| 2026-05-21 | Initial overview + phased rollout + pointers to mirrored upgrade artifacts. |
| 2026-05-21 | Linked rsms-task4-and-r5-layer-catalog.md for Task 4/R5 enumeration + status tracking. |
| 2026-05-22 | Locked pilots: Pilot A — USGS streamgages (legacy port); Pilot B — USACE bridges; phased rollout renumbered. |