Nidus Reveal Customer UI — Design Doc for Review #174
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
@eliribble @ned — here is the customer-facing UI design for Nidus Reveal. This covers the read-only web interface where district users view pool detections, review individual pool histories with imagery, and export selected pools. Please review and provide feedback before this is committed to
doc/nidus-reveal/.Nidus Reveal is satellite-based swimming pool detection for mosquito control districts. This document defines the read-only, export-only web interface that lets district users find pools by status or address, review individual pool detection histories with imagery, and export selected pools in multiple formats. The UI lives inside the Nidus web application and follows the established three-panel workbench pattern.
User Stories
User Story 1 — Export / Report Generation. A supervisor or GIS user selects pools by detection status and exports them to CSV, PDF, KML, shapefile, or file geodatabase for field assignment.
User Story 2 — Single-Pool History Lookup. An admin or field staff member searches for a pool by address, reviews its detection timeline, and clicks detection points to view the satellite imagery that produced each result.
Layout
The interface uses a three-panel layout consistent with other Nidus workbenches.
2024 ●———2025 ●———2026 ●—✕det det det exportLeft Panel — Pool List & Filter
Search bar at the top. Accepts an address and scrolls the pool list to the match. This is the primary entry point for User Story 2 (address lookup).
Filter buttons below the search bar. MVP supports filtering by detection status only: unmaintained, dry, and all. Additional filters (geography, date range) are deferred.
Pool list shows every pool in the district. Each row includes a checkbox, the situs address, and the current detection status. Pools with status "maintained" appear in the list so users can search and review them.
Checkboxes let users select and deselect individual pools for export. The list respects the active filter — filtering to "unmaintained" narrows the visible list and only visible, checked pools are staged for export. Select All and Select None shortcuts operate on the visible filtered list.
Center Panel — Map View
The center panel occupies the largest area and serves three states.
Default state (no pool selected). The map fills the panel. Non-filtered pools are displayed as points or cells symbolized by detection status. Below the map, a dashboard strip shows aggregate stats: pool counts by status across the entire district, date of last detection round.
Multiple pools selected. When two or more pools are checked, the area below the map shows aggregate stats for just the selected set: counts by status within the selection. This helps users understand what they are about to export without losing the map view. No individual timeline is shown.
Single pool selected. The map remains visible at the top. Below the map, the pool's history timeline appears. Clicking a pool row in the left panel or clicking a pool marker on the map enters this state.
Map-based selection. Users can click pool markers on the map to toggle them into the export selection. Map selection and list checkbox selection are synchronized.
Imagery display. When a user clicks a detection point on the timeline, the corresponding satellite imagery layer loads on the map via tile services. This lets staff show residents the actual image that produced a detection result.
Right Panel — Export Tools
Format selection. Five checkboxes (or radio-style toggles, since multiple formats can be exported in one action): CSV, PDF, KML, Shapefile, File Geodatabase. All five are in scope for MVP.
Export button. Exports the currently selected pools in the chosen formats. Export contents include address, pool status, and any other available metadata.
Post-export. After a successful export, the system tags each exported pool with an "exported" marker and timestamp on its timeline. Future exports should not overwrite or remove prior export markers.
Pool History Timeline
When a pool is selected, a horizontal timeline appears below the map. The timeline shows the pool's detection history from left (oldest) to right (newest).
Data points on the timeline:
Interaction. Clicking any detection point loads the satellite imagery for that detection run onto the map. The imagery replaces or overlays the current basemap until the user dismisses it or selects a different point.
Available Data
In MVP, each pool carries:
Field activity data (treatments, inspections, technician notes) is not available in MVP. It becomes available if the district adopts the full Nidus platform.
Constraints
@ned, if you would please take a look and ask any questions. The idea is that this UI is much like the already designed UI we have for communications so that we don't have to rebuild something from scratch.
Great design, neighborino! A few questions and observations as I chew through it.**1. Pool Data Model — Where does it live?**Is there already a pool detection schema in the database, or is this greenfield alongside Nidus Notes/Reveal? The doc mentions detection runs, statuses (unmaintained/dry/maintained), satellite imagery tile access — I want to understand what we have and what we need to build.**2. Pool list volume — Pagination or virtual scroll?**Hundreds of pools with checkboxes is workable in a scrollable list, but at 200+ rows it starts to churn the DOM. Should we paginate (say 50 per page) or use virtual scrolling? The Communications Workbench list doesn't face this scale since it shows active comms, not everything.**3. PDF export — template-driven or tabular?**CSV, KML, Shapefile, and File Geodatabase all follow a data-export pipeline — query pools → serialize to format. PDF is a different beast: it needs a layout/template (letterhead? map inset? table styling?). Is the expectation a simple tabular printout, or something more presentation-ready (with district logo, map, signature lines)?**4. Timeline imagery — tile layer per detection run?**When clicking a detection point on the timeline, what loads on the map? Is this a pre-baked tile layer from a specific satellite pass (e.g. a Planet/MAXAR tile URL stored for that detection run), or a dynamic link to an external imagery service? Knowing this affects whether we store tile URLs per detection event or build the imagery URL at query time.**5. Map selection ↔ list checkbox sync — new pattern?**The communications overview map (PR #169) selects markers but doesn't drive list checkboxes. This design calls for bidirectional sync: clicking a pool marker checks the box, checking the box highlights the marker. That's a richer interaction than what exists. Should I plan this as an extension of the SourceGeoJSON / Feature components, or a new pattern?**6. Pool geometry — points, polygons, or cells?**The design says pools shown as "points or cells" on the map. Are pools derived from parcel polygons (situs → parcel → centroid), raster detection cells (H3/Grid), or point detections? This affects how we store and render them.**7. Relationship to Issue #153 / Nidus Notes (field app)?**Nidus Notes is about field technician mosquito surveys; Nidus Reveal is satellite-based pool detection for district staff. They share concepts (addresses, pools, districts) but serve different users. Should they share data infrastructure (the same pool/address tables), or are these separate systems that happen to live in the same app?**8. Detection statuses — "others TBD"**The constraint table lists statuses as "unmaintained, dry, others TBD." How many more statuses are expected? If it grows beyond 5-6, filter buttons might get crowded — a dropdown might age better. Worth clarifying before committing to a button row layout.**9. Timeline export markers — new tracking table?**Post-export markers on the timeline imply we need to persist export events. Is this something like an export_log table (export_id, pool_id, timestamp, format), or is a simpler in-memory / flat-file approach acceptable for MVP?**10. Right panel — export formats as checkboxes vs radio+multi-pass?**The design shows checkboxes so users can select multiple formats in one click. That's solid. Just confirming: one click of "Export Selected" generates all checked formats in a single backend call, rather than one-at-a-time? That's the right experience but the backend needs to orchestrate multiple export pipelines per request.Overall this looks clean and follows the workbench pattern nicely. Happy to start building once we settle these.
Thanks Ned. Here are answers to each:
1. Pool Data Model — Where does it live? Likely greenfield — Benjamin isn't aware of an existing pool detection schema. If there is one buried somewhere, flag it, otherwise plan to build.
2. Pool list volume — Pagination or virtual scroll? Simple scroll, no pagination needed.
3. PDF export — template-driven or tabular? Tabular is fine. The PDF is meant to be a simple printable list a supervisor can hand to a field tech.
4. Timeline imagery — tile layer per detection run? Pre-built tile layers produced as part of the detection pipeline from weekly Planet data, stored per detection event.
5. Map selection ↔ list checkbox sync — new pattern? The design requirement is that map and list stay in sync. Selected pools (whether clicked on the map or checked in the list) should be visually distinct from unselected but visible pools. Implementation approach is your call.
6. Pool geometry — points, polygons, or cells? Vector polygons — but Eli should confirm.
7. Relationship to Nidus Notes? Nidus Reveal should be standalone (usable without Nidus Notes), but when a district also runs Nidus Core, the two should integrate immediately.
8. Detection statuses — how many? Four: maintained, unmaintained wet, unmaintained dry, dry. Buttons are fine at that count.
9. Timeline export markers — new tracking table? Should be persisted as part of each pool's history. Eli can confirm the exact approach.
10. Export formats — one click? Yes. User selects all desired formats, clicks one button, and all are processed and delivered. Implementation details are yours.
Thanks for the thorough answers, Benjamin! A few thoughts and follow-ups on each:
1. Data model — Greenfield it is. I'll draft a schema covering pools, detection events, detection runs (the weekly Planet tile batches), and export tracking. I'll flag any existing tables I find that might relate.
2. Scroll — Simple scroll, no pagination. Got it.
3. PDF — Tabular printable list. Straightforward.
4. Timeline imagery — Pre-built tile layers per detection event. Makes sense — the backend API will need a tile URL field per detection event so the frontend can load/replace them on the map.
5. Map ↔ list sync — I'll keep them bidirectionally synced: check in the list → highlight on the map, click on the map → check in the list. I think the cleanest approach is shared reactive state (selected pool IDs) that both the list and the map source read/write from.
6. Pool geometry — Vector polygons noted. We'll need @eliribble to confirm whether the pool geometries come from digitized parcel polygons, the pool detection output (which could be raster-to-vector), or a separate AOI table.
7. Nidus Notes integration — Standalone MVP with immediate integration when Nidus Core is present. Good — I'll make sure the architecture supports this cleanly from day one.
8. Four statuses — maintained, unmaintained wet, unmaintained dry, dry. Four buttons is perfect.
9. Export markers — I agree on persisting into pool history. @eliribble, does a simple
export_logtable with (pool_id, export_timestamp, formats[]) referencing a pool's detection history sound right, or did you have something else in mind?10. One-click multi-format — All formats in one go. I'll build it as a parallel pipeline: validate selection, run each format, zip the results, deliver the download.
Next steps from here:
Pools are already defined in the database, you can check the implied schema in db/migrations or the explicit schema via generated code in db/gen. The important table is
feature_pool.The geometry for a pool is stored in
feature_pool.geometryin SRID 4326.Don't worry about this for now.
This is going to be a really complex topic because it touches on multiple data sources. We're not going to solve it here. For now we'll build a UI mock, then in follow-on work sort out how we're extracting the historical information.
Go ahead and create a feature branch and pull request that creates a mockup of the UI. I want to get agreement on the UI design before we sort out how to do the underlying data model and APIs.
PR #175 created with the UI mockup: #175
What is included:
What this is deferred to follow-on (per Eli):