Concept · synthetic data

A next-generation statewide water measurement dashboard, built as a discovery artifact

A working, high-fidelity concept of a next-generation Water Measurement Data Dashboard: a user-centric web application for accessing, visualizing, analyzing, quality-controlling and managing water measurement data from about 1,200 active monitoring sites, set in Michigan and dressed in a simulation of the State of Michigan's visual language.

It is not an official product and not a proposed production system. It exists to make the architecture and UX questions tangible before anyone commits to a stack, a backlog or a budget.

Sites modeled: 1,112; 4 site types, 8 watersheds
Audiences: 2; public and internal QC staff
Data: Synthetic; seeded, seasonal, deterministic
Integration model: API-first; OGC SensorThings 1.1

01The brief

A next-generation Water Measurement Data Dashboard for a state water program: a user-centric web application for accessing, visualizing, analyzing, quality-controlling and managing water measurement data from about 1,200 active monitoring sites, with HydroServer already adopted as the authoritative repository. The planning work covers discovery, requirements, solution architecture, UX refinement, implementation planning and cost estimation.

Functional requirements

Support desktop, laptop, tablet and mobile access.
Provide intuitive data visualization and analytics.
Enable internal users to enter observations and run quality-control workflows.
Deliver public-facing access to published water measurement data.
Integrate with HydroServer and the division's existing technology platforms.
Modernize existing water distribution and reporting capabilities.

Required deliverables

Architecture documentation: solution architecture document, system context diagram, component diagram, deployment diagram, data flow diagrams, API integration specifications, security architecture documentation, implementation roadmap.
UX deliverables: refined and finalized Figma designs, high-fidelity dashboard mockups, user workflow documentation, UX recommendations and improvements.
Planning deliverables: comprehensive implementation backlog, phased development roadmap, project schedule and milestones, cost estimation model, recommended development and deployment approach, training and transition strategy.

Section 12 maps each of the eighteen to what this concept already contributes and what discovery must add.

Out of scope

Production software development, application implementation, data migration, API development or redesign, modifications to HydroServer, cloud infrastructure procurement, ETL redesign and sensor deployment. The concept touches none of them; it is a planning artifact for the work that comes before.

02Stakeholders & personas

Stakeholders and personas, what each needs, and which part of the concept serves them
Audience	Who	What they need	Served in the concept by
Public	Resident, irrigator, recreational user	Wants today's conditions at a place they know, in context: is the river high or low for this time of year?	The map, the site list, the current-value hero, and "% of normal."
Public	Researcher, consultant, other agency	Wants period-of-record context and a programmatic path to the data.	The time-series chart, the daily-conditions heatmap, site metadata, and the visible SensorThings request per site.
Internal	Hydrographer / QC reviewer	Works a queue. Needs to see why an observation was flagged, the raw recent values, and act: approve, correct, or go look at the site.	Internal mode, the QC review tab, the unpublished observations table, and the QC halo on the map.
Internal	Program manager / data steward	Needs the network-health view: how many sites are streaming, delayed, offline, or manual, and how much is waiting for review.	The statewide indicator strip and the pending-QC count.
Technology division	Integration, identity, hosting	Cares that the client is stateless, that authorization derives from state identity claims, that nothing bypasses the authoritative APIs, and that the whole thing fits the state's cloud landing zone.	The API-first model and the deployment view below.
Oversight	Leadership and auditors	Wants evidence that the modernization delivers public transparency, data quality controls, and less reliance on legacy systems.	Everything above, and directly by the engagement's roadmap.

03The problem

One surface, two very different audiences: The public needs published, trustworthy values with context. Internal measurement staff need unpublished observations, screening results, and a way to approve or correct before anything becomes public. Two apps would double the integration surface; one app with a hard audience boundary is the harder but better problem.
The data already has a home: The division adopted a HydroServer-style platform as the authoritative repository, exposed through OGC SensorThings. The dashboard must be a client of that system of record, never a second copy of it.
Scale is geographic: Roughly 1,200 active monitoring sites of several kinds (stream gages, hydro dams, groundwater wells, lake gauges) across a whole state. Navigation is spatial first; a list alone would not work, and a map alone would not be accessible.
Quality control is a domain workflow, not a feature: Observations arrive from telemetry, get screened automatically, and wait for a human decision. The status of a value (provisional, approved, corrected) is part of the data's meaning and must be visible to the right audience.
Modernization, not replacement: Legacy mapping and reporting applications continue to exist. Whatever gets built must coexist with them and take over capabilities incrementally (Strangler Fig), which pushes toward a thin, replaceable client over stable APIs.
Public sector constraints are first-class: ADA compliance, responsive behavior down to phones, cross-browser support, state identity (single sign-on), and data classification are requirements, not polish.

04Assumptions

Assumptions by confidence: known from the brief, assumed in the design, and needing validation
Known	Assumed	Needs validation
HydroServer is the authoritative repository; integration is through SensorThings, HydroServer APIs, and HydroServerPy.	The dashboard is a thin client that never stores measurement data of its own; it may cache.	Which reads must be live vs. cached? What are the API's rate limits and latency at 1,200 sites × 15-minute telemetry?
Internal users must enter observations and run QC workflows; the public sees published data.	QC is a queue fed by automated screening; approval publishes, correction routes for sign-off. Values are "provisional" until approved.	What are the actual screening rules and thresholds? Who has approval authority? Is there a two-person rule? How are corrections audited?
~1,200 active sites; desktop, tablet, and mobile access.	Four site types with different primary parameters (discharge, generation, depth to water, level) and type-specific screening rules.	Real site taxonomy and parameters. Do field staff need offline entry on phones, or is mobile read-only?
A state identity tool for authentication and authorization.	Audience (public vs. internal) is a claim on the session, not a separate app; internal-only UI is hidden and internal-only API routes are denied without the claim.	Role model beyond two audiences (reviewer, approver, admin, other-agency). Are there partner agencies with partial internal access?
GIS is central; legacy MapServer and ArcGIS Maps SDK 3.x exist and must be modernized.	The concept uses an open map engine to stay vendor-neutral; production would standardize on ArcGIS Maps SDK 5.x per state investment.	Which legacy map layers must be preserved? What does the state's ArcGIS Enterprise/Online footprint look like?
ADA compliance, responsive design, cross-browser compatibility.	WCAG 2.2 AA, verified in both themes and both audience modes; the list is the accessible equivalent of the map; charts have tabular alternatives for internal users.	Does the state have an accessibility review process and a design system the dashboard must adopt?
Cloud deployment on GCP; AI capabilities may be evaluated under state policy.	Serverless containers for the web tier and API façade; the authoritative platform is a dependency, not something the dashboard hosts.	Where does HydroServer run today? Existing landing zone, VPC, and IAM conventions? Is there an AI acceptable-use policy to design against?

05Key decisions

Thin client over an authoritative repository, API-first

Decision: The dashboard holds no measurement data of its own. Every panel corresponds to a SensorThings request, and each site's metadata shows the literal request (for example GET /api/sensorthings/v1.1/Datastreams(3686)/Observations?$top=96&$orderby=phenomenonTime desc).
Instead of: A dashboard database synced from HydroServer, which is faster to build and creates a second source of truth that drifts.
Why: It keeps the UI replaceable, which is what a Strangler Fig migration needs, and it makes the integration contract visible to reviewers instead of buried in code.
Consequence: Performance depends on the API. Caching, pagination, and pre-aggregated statistics become architecture concerns, not UI ones.

One surface, two audiences, boundary enforced by identity

Decision: Public and internal modes share the same application. Internal mode (a mock state-identity session in the concept) reveals the QC review tab, the unpublished observations table, the QC halo on the map, and the pending count in the header.
Instead of: Two applications, or a public site plus an admin tool.
Why: Internal staff need the public view constantly (to see what the public sees) and the public view benefits from the same components. One codebase, one integration, one design system.
Consequence: Authorization must be enforced server-side on every internal route; hiding UI is not security. The concept only demonstrates the UI half.

Quality control modeled as a domain workflow with type-specific rules

Decision: Automated screening produces flags per site type: stream gages get spike, rating-shift, gap, and flatline checks; dams get spike, gap, flatline; wells get sensor drift, gap, flatline; lake gauges get drift, gap, and a seiche-aware spike screen. Flags feed a review queue; approving publishes, correcting drafts a change routed for sign-off. Recent values carry a "provisional" notice.
Instead of: A generic "flagged data" list, or hiding QC from the dashboard entirely.
Why: A rating shift only means something where a stage-discharge rating exists. Type-appropriate rules are what make a hydrographer trust the tool, and they are exactly the kind of detail a discovery workshop should confirm or correct.
Consequence: The real rule set, thresholds, and approval authority must come from measurement staff. The concept's rules are placeholders chosen to be plausible, not correct.

Map as primary navigation, list as its accessible equivalent

Decision: All sites render as a data-driven map layer (color by type, size by significance) with filters for watershed, telemetry status, and site type applied identically to the map and the list. A bundled offline basemap fallback keeps the app usable if the tile service is unavailable.
Instead of: Map-only navigation, or a table-first interface with a small map.
Why: 1,100 points are a spatial problem, but a map cannot be the only route to a site for keyboard and screen-reader users. Two synchronized views satisfy both.
Consequence: Clustering and search become necessary at production scale; the concept demonstrates search and filters but not clustering.

Context over raw numbers

Decision: Every current value is shown against a climatological expectation for the same calendar day ("% of normal", "vs long-term average" on IGLD 1985 for lakes, "% of nameplate" for dams), with a one-year daily-conditions heatmap and period-of-record statistics.
Instead of: Showing the latest reading and a chart and leaving interpretation to the user.
Why: A public user cannot judge whether 161 cfs is high or low; "96% of normal" answers the question they actually have. This is the same comparison real gage networks publish.
Consequence: Normals must be computed and served by the platform (or a statistics service), not by the browser.

Three responsive shells, not one squeezed layout

Decision: Desktop: indicators, site explorer, map, and a detail drawer side by side. Tablet: the same with a collapsible explorer and the detail floating over the map. Phone: map first, a bottom action bar with the site count that opens the explorer as a side panel, and the site detail as a bottom sheet with half and full stops; on a landscape phone the detail becomes a side panel so the map keeps its height.
Instead of: A single fluid layout that stacks panels on small screens.
Why: The brief names desktop, laptop, tablet, and mobile. On a phone the map is the first impression; on a desktop, depth is. Different shells let each device lead with what it does best.

Concept stack chosen for zero friction, not for production

Decision: Plain HTML/CSS/JavaScript with no build step, MapLibre GL for the map, and a deterministic synthetic dataset generated in the browser from a seeded random generator so the demo renders identically on every load. Loading skeletons are part of the spec because production is network-bound against the API.
Instead of: React and ArcGIS Maps SDK, which is what I would recommend for production given the state's stated preferences and existing GIS investment.
Why: A discovery artifact should be trivially hostable, inspectable by non-engineers, and cheap to throw away. Committing to the production stack before discovery would anchor the team on implementation before requirements. In practical terms: I wanted zero API keys and zero vendor setup, so the prototype runs anywhere, including offline. Choosing the open engine here was a way to prove the map layer is swappable, not a preference.
Consequence: Nothing in the concept is reusable as production code, by design. The reusable outputs are the information architecture, the workflows, the design tokens, and the API contract.

Design tokens and validated palettes from day one

Decision: All color, type, radius, and motion values are CSS custom properties. The four site-type colors were checked for contrast and color-vision-deficiency separation in both light and dark themes, with secondary encodings (legend, labels, marker size) so color is never the only signal.
Why: Migrating to a state design system becomes a token swap rather than a redesign, and accessibility is cheaper to build in than to retrofit.

06The solution

One web application for the state's water measurement data, serving two audiences from the same screens.

Public

Today's conditions with context: is this river high or low for the time of year? Published values only, on any device.

Internal

The same views plus the work behind them: unpublished observations, automated screening results, and a review queue where approving publishes a value and correcting routes it for sign-off.

The integration target comes from the brief: HydroServer, SensorThings, the state identity platform and the ArcGIS ecosystem it names.

What is in it

Statewide indicators: Active sites, streaming telemetry, observations today, streamflow against normal, and hydro fleet output, in an expanded or compact band.
Site explorer: Filters by watershed, telemetry status and site type, plus search. The list mirrors the map exactly, so keyboard and screen-reader users have the same route to every site.
Map: About 1,100 sites as a data-driven layer: color by type, size by significance. A bundled offline basemap takes over if the tile service is unavailable.
Site detail: Current value against the same-day normal, station views, the provisional-data notice, a one-year chart with 30, 90 and 365-day ranges, a daily-conditions heatmap, period-of-record statistics, and the site's metadata with the SensorThings request it would run.
Internal mode: A QC review queue fed by type-specific screening rules (spike, gap, flatline, drift, rating shift), the unpublished observations table, and approve or correct actions.
Foundations: Three responsive shells (desktop, tablet, phone), light and dark themes, and WCAG 2.2 AA verified in both.

UX flow and site map

Fig. 5. UX flow and site map. Solid screens exist in the concept; dashed ones are engagement scope. Screen numbers are the ones the journeys below refer to.

Journey 1 · Public user

Is my river high or low for this time of year? Opens the dashboard (1.0), filters the explorer by watershed or searches the river by name (1.1), opens the site (1.2), reads the current value against the same-day normal and the one-year chart, and checks the daily-conditions heatmap for the season. Every value is published data.

Journey 2 · QC reviewer

Clear the morning's flags. Signs in (0.0), switches to internal mode (1.0), opens the queue sorted by rule (2.0), reviews a spike flag with the raw values around it (2.1), approves it, and confirms on the public detail that the value is now published (1.2). A correction would be drafted here and routed for sign-off.

What is real, what is simulated, and where they connect

Real: the interface and its interactions (working code), the map engine, the basemap (OpenStreetMap data served by CARTO) and the river and shoreline geometry that places the sites (Natural Earth).
Simulated: the site inventory and every measurement, generated in the browser by a seeded model of Michigan hydrology. Nothing is fetched from a water-data API.
The seams, left visible on purpose: the site layer is one GeoJSON source that becomes a SensorThings Things and Locations request; each chart is one Datastreams(id)/Observations request, shown verbatim in the site's metadata; approve and correct in the QC queue become calls to HydroServer's management API; and the map layer sits behind one interface so it can be replaced by the ArcGIS Maps SDK and the state's own ArcGIS Server services.

07System context

Fig. 1. System context. The dashboard never receives telemetry directly and never owns measurement data; it is one client of the authoritative platform, alongside the legacy applications it is meant to gradually replace. Solid lines are within the concept's scope; dashed lines are integrations the engagement would specify.

Migration path for the map layer

The legacy application is built on the ArcGIS Maps SDK for JavaScript 3.x, a line that has reached end of life. Moving to the current SDK is a rewrite of the map layer, not a version bump, which is why the dashboard keeps that layer behind one interface. The Strangler Fig pattern applies to the map the same way it applies to the rest of the system:

Coexist. The new dashboard consumes the same state GIS services the legacy application uses (basemaps, hydrography, administrative layers) through the current ArcGIS Maps SDK. Both applications run side by side, with the same identity, and traffic is split by capability: current conditions and site lookup go to the dashboard; water distribution and reporting stay on the legacy application.
Take over. Capabilities move one at a time (measurement views, QC review, then distribution and reporting), each retirement gated by a parity check with measurement staff and a period where both paths remain open. Nothing is rewritten that has not first been observed working in the new client.
Retire. When the last capability reaches parity, the legacy application is decommissioned. What remains is the state's ArcGIS Server as the single source of geometry and HydroServer as the single source of measurements, with the dashboard as one replaceable client over both.

08Observation lifecycle & QC

Fig. 2. Observation lifecycle. In the concept, the review queue, the "provisional data" notice, the unpublished observations table, and the approve/correct actions are all present in internal mode; only published values and context appear in public mode. Screening rules are type-specific because a rating shift only exists where a stage-discharge rating exists.

09Conceptual deployment on Google Cloud

Fig. 3. Conceptual deployment. The dashboard tier is stateless and serverless so it scales with public traffic (a flood event is the peak-load scenario) without touching the authoritative platform's capacity. Where HydroServer itself runs, and whether it sits inside the same project, is a discovery question.

11What this concept does not solve

No real integration. The SensorThings requests are shown, not executed. The API contract, pagination, caching, and error handling are engagement deliverables.
No real identity. Audience is a toggle in a mock session. The role model, token validation, and server-side authorization are engagement deliverables.
No ArcGIS. The concept deliberately uses an open map engine. The migration path in section 07 is a sequence, not a plan: the capability inventory of the legacy application, the parity criteria and the dates are engagement deliverables.
No observation entry. Internal users can act on flags but cannot enter field observations. Whether this belongs in the dashboard or in a field tool is a discovery question.
No roadmap, backlog, or cost model. These are the core of the engagement and cannot be inferred from a prototype. The concept gives them a concrete starting point.
No AI features. The brief asks to evaluate them under state policy. My starting position: assistive uses only (anomaly triage, metadata help, natural-language search over published data), never as a source of truth for a measurement.

12From concept to engagement

The required deliverables of the brief, what the concept already contributes to each, and what discovery must add
Required deliverable	What the concept already contributes	What discovery must add
Architecture documentation
Solution Architecture Document	Decisions D1 to D8 as draft ADRs; the thin-client model over the authoritative repository.	Validated requirements, non-functional requirements, trade-off analysis.
System Context Diagram	Fig. 1.	Confirmed integrations and the legacy inventory.
Component Diagram	The client's component structure: indicators, explorer, map, detail drawer, QC queue.	Component boundaries in the API tier and the statistics service.
Deployment Diagram	Fig. 3 as a conceptual GCP baseline.	Landing-zone fit, environments, disaster recovery, network topology.
Data Flow Diagrams	Fig. 2, the observation lifecycle with QC.	Real screening rules; observation entry and correction flows.
API Integration Specifications	The SensorThings request behind every panel; the Thing and Datastream model surfaced in site metadata.	Full contract, pagination, caching, error handling; HydroServerPy for staff tooling.
Security Architecture Documentation	Audience boundary, provisional-data classification, the rule that the client never enforces authorization.	State identity tool role model, token flow, audit logging, data classification policy.
Implementation Roadmap	A concrete target to slice into Strangler Fig phases; the gaps list as the first backlog.	Phasing, milestones and dependencies agreed with the technology services division.
UX deliverables
Refined and finalized Figma designs	Working information architecture, three responsive shells, design tokens, palettes validated for contrast and color vision.	Migration into the state design system; the Figma source; refinement from user testing.
High-fidelity dashboard mockups	The prototype itself, in public and internal modes, light and dark, desktop to phone.	Mockups for the flows not built: observation entry and the correction dialog.
User workflow documentation	Fig. 5, the UX flow with numbered screens and two journeys (public browse to detail; internal queue to approve and publish), plus Fig. 2 for the observation lifecycle.	Field observation entry, approval authority, edge cases.
UX recommendations and improvements	Context over raw numbers (% of normal), the list as the map's accessible twin, the provisional-data notice, the two-stop detail sheet; the known-gaps list in section 10.	Findings from testing with division staff and public users.
Planning deliverables
Comprehensive implementation backlog	The gaps list and the third column of the assumptions table.	Prioritization, owners, acceptance criteria.
Phased development roadmap	The sequencing implied by D1: thin client first, legacy coexistence, capabilities taken over one at a time.	Phases with dependencies and release gates.
Project schedule and milestones	The phased roadmap below, as structure: phases, exit criteria and what leaves the legacy application. No dates.	Built with the division and technology services once phases are set.
Cost estimation model	The cone of uncertainty below, as method: ranges that narrow as assumptions close. No figures.	Cone-of-uncertainty estimates per phase, narrowed as discovery closes assumptions.
Recommended development and deployment approach	D7 (React and the ArcGIS Maps SDK for production) and Fig. 3.	Confirmed against the state's technology standards and existing GIS investment.
Training and transition strategy	Nothing yet.	Knowledge transfer plan for long-term ownership by internal teams.

What the planning deliverables would look like

Three of the planning artifacts cannot be filled in without the division, but their shape can be shown. Everything below is illustrative: the structure is the deliverable, the contents are placeholders.

Illustrative phased roadmap: phase, goal, exit criterion, and what leaves the legacy application
Phase	Goal	Exit criterion	Leaves the legacy application
Discovery	Validated personas, workflows and QC rules; assumptions closed or rejected.	Assumptions table with no rows left in "assumed"; prioritized backlog signed by measurement staff.	Nothing yet.
Foundation	Thin client over HydroServer with state identity and the state GIS services wired in.	Public site conditions readable end to end from live SensorThings data; authorization enforced server-side.	Site lookup and current conditions.
Take-over	Capabilities move one at a time: measurement views, QC review, distribution, reporting.	Each capability passes a parity check with staff and runs in parallel for one review cycle.	One capability per release.
Retire	Legacy application decommissioned; one client over two authoritative sources.	Last capability at parity; legacy traffic at zero for a full cycle; training and transition complete.	Everything.

Fig. 4. Illustrative cone of uncertainty. Estimates are published as ranges tied to milestones, not as single numbers: the width of the range is a function of how many assumptions remain open. Percentages are the method's conventional bands, not this project's figures.

Illustrative backlog slice: one epic with three user stories, their acceptance criteria and dependencies
Story	Acceptance criterion	Depends on
Epic: approve and publish an observation
As a QC reviewer, I see why an observation was flagged.	The queue shows the rule, the threshold and the raw values around the flag, on desktop and phone.	Screening rules confirmed in discovery.
As a QC reviewer, I approve an observation and it becomes public.	Approval writes the quality flag through the management API, the public view updates within one refresh, and the action is audited with user and time.	HydroServer management API; state identity role claim.
As a QC reviewer, I draft a correction that someone else signs off.	The draft is stored unpublished, routed to an approver, and the original value stays public until sign-off.	Approval authority defined in discovery.

How I would use it in the first workshops

Put it in front of measurement staff with one instruction: break it. Every "that's not how we do it" becomes a requirement with a name and an owner. Capture the assumptions table live, move rows from "assumed" to "known" or "rejected," and leave the workshop with the discovery backlog already prioritized. The concept's job is to make that conversation fast and specific; the engagement's job is everything that comes after.

This concept was built independently with no access to any agency, its users, or its data. Everything measured on the dashboard is synthetic. It is shared to support a conversation, not to represent any state's official information.

13Glossary

ADR: Architecture decision record: a short note that states a decision, the alternative not taken, why, and the consequence. Section 05 is eight of them.
ArcGIS Maps SDK: Esri's JavaScript library for maps in the browser. The legacy application runs on its 3.x line; production would use the current line behind the same map interface.
Basemap: The background map (roads, water bodies, place names) under the data layers. The concept uses OpenStreetMap tiles served by CARTO, with an offline fallback.
Cone of uncertainty: An estimating method that publishes ranges instead of single numbers, wide at the start and narrower as assumptions close. Fig. 4.
Datastream: In SensorThings, the series of observations of one property at one station. Each chart in the site detail is one Datastream.
HydroServer: The open-source platform adopted as the authoritative repository for water measurement data. It exposes SensorThings and its own management APIs.
Identity claim: A statement in the sign-in session (for example, audience: internal) that the server uses to decide what a user may see and do. The client never enforces authorization on its own.
IGLD 1985: International Great Lakes Datum of 1985: the vertical reference against which Great Lakes water levels are reported.
MapLibre: The open-source map engine the concept uses to render the map. Chosen for the prototype because it needs no keys or vendor setup.
Observation: In SensorThings, one measured value with its timestamp and quality flag. A point on the chart, a row in the QC table.
Provisional value: A measurement that has arrived from telemetry but has not been approved by measurement staff. Shown to the public with a notice; the approved value replaces it.
QC: Quality control: the workflow in which automated screening flags observations and staff approve or correct them before publication.
Rating shift: A change in the relationship between water level and flow at a stream gage, usually after the channel changes. A flag that only makes sense where a stage-discharge rating exists.
Screening rule: An automated check on incoming observations (spike, gap, flatline, drift, rating shift). Rules are specific to each site type.
SensorThings: OGC SensorThings API: an open standard for publishing sensor data on the web, with Things, Datastreams and Observations as its core entities.
Strangler Fig: A modernization pattern in which a new system takes over capabilities of a legacy one incrementally, coexisting with it until the legacy system can be retired.
Telemetry: Automatic transmission of measurements from a monitoring site, typically every 15 minutes, by satellite or cellular link.
Thin client: A user interface that holds no data of its own and reads and writes everything through the authoritative repository's APIs, so it can be replaced without losing anything.
Thing: In SensorThings, the monitoring station itself, with its Location. A marker on the map is one Thing.
WCAG: Web Content Accessibility Guidelines. The concept is verified against WCAG 2.2 level AA in both themes.