WEPPcloud
UserSummary Docs

← Back to usersum index

Roads NoDb Inslope End-to-End Implementation

Status: Open (2026-03-23)

Overview

This work package plans and then executes the first end-to-end WEPPcloud Roads NoDb integration for inslope road designs (Inslope_bd, Inslope_rd). The goal is to deliver a complete, queue-backed Roads workflow that starts from uploaded road GeoJSON, produces segment WEPP runs, injects road effects into watershed routing, and exposes observable run-page/preflight/report behavior.

Objectives

  • Implement a first-class Roads(NoDbBase) controller with a stable run-scoped persisted state contract (roads.nodb).
  • Wire Roads enablement through canonical /tasks/set_mod with explicit WBT backend gating and no hidden fallback paths.
  • Integrate Roads across run header, run page, TOC/preflight, task enum, Flask routes, rq-engine routes, and RQ workers.
  • Complete phase-1 segment utility behavior (Inslope_bd + Inslope_rd), single-OFE run assembly, and pass-file combination per Roads spec.
  • Deliver implementation-ready validation gates, including fixture-backed integration/e2e checks on clogging-starch.

Scope

This package includes all implementation and validation work required by wepppy/nodb/mods/roads/specification.md for phase-1 inslope Roads integration.

Included

  • Roads controller, API routes, queue workers, and run-page/report integration.
  • Mod registration and enable/disable behavior through set_mod.
  • WBT-only backend guard for Roads enablement.
  • Task/preflight wiring (TaskEnum.run_roads, emoji 🚗, checklist key roads, TOC selector map).
  • Monotonic segment utility parity for both inslope designs plus lowpoint channel/hillslope attribution.
  • Single-OFE WEPP road segment run assembly and watershed rerun via pass injection.
  • Pass combiner implementation in wepppyo3 using the phase-1 rules in the Roads specification.
  • Roads artifact layout under wepp/roads/{segments,runs,output} with watershed reruns launched from wepp/roads/runs/pw0.run.
  • Queue-governance updates (wepppy/rq/job-dependencies-catalog.md, wctl check-rq-graph).
  • Targeted, integration, and fixture-backed e2e validation.

Explicitly Out of Scope

  • Non-inslope road designs (Outslope_*, etc.).
  • Exact legacy WEPP:Road 3-OFE parity in phase 1.
  • New fallback wrappers that mask missing dependencies or unsupported backends.
  • UI redesign beyond required Roads section placement and control/report inclusion.

Stakeholders

  • Primary: WEPPcloud users running disturbed watershed scenarios that require Roads impact analysis.
  • Reviewers: NoDb maintainers, WEPPcloud route/UI maintainers, rq-engine maintainers, wepppyo3 maintainers.
  • Informed: Preflight service maintainers, operations owners monitoring queue/job graph drift.

Success Criteria

  • Roads(NoDbBase) exists with the specified state contract and lifecycle transitions.
  • Roads can be enabled only via /tasks/set_mod and returns an explicit error on non-WBT runs.
  • Run header Mods includes Roads and run page renders Roads immediately after Debris Flow (TOC + content).
  • TaskEnum.run_roads (🚗) and preflight checklist key roads are integrated, with Roads completion dependent on WEPP completion.
  • Roads API/blueprint routes and rq-engine/RQ jobs execute prepare + run stages asynchronously with observable status updates.
  • Segment utility meets inslope parity/invariant requirements from the Roads spec (topaz_id_chn_lowpoint, topaz_id_hill_lowpoint).
  • Single-OFE run assembly and pass combiner produce a successful watershed rerun with all hillslope pass references resolved from wepp/roads/output.
  • Queue governance checks pass (wepppy/rq/job-dependencies-catalog.md updated, wctl check-rq-graph clean).
  • Required targeted tests, lint/doc checks, and fixture e2e checks pass using clogging-starch defaults.

Dependencies

Prerequisites

  • wepppy/nodb/mods/roads/specification.md (canonical behavior/spec contract).
  • Existing baseline WEPP outputs for fixture run clogging-starch in /wc1/runs/cl/clogging-starch.
  • WBT delineation backend in fixture/config path (disturbed9002-wbt-mofe.cfg).
  • wepppyo3 checkout at /workdir/wepppyo3 for pass combiner implementation.

Blocks

  • Future Roads phases (non-inslope designs, advanced hydrograph merge) depend on this phase-1 integration.
  • Any Roads-related operational rollout depends on queue graph and route-contract governance updates landing with this package.
  • Depends on: Roads phase-1 specification (wepppy/nodb/mods/roads/specification.md).
  • Related: docs/work-packages/20260321_rusle_nodb_ui/ (recent NoDb mod + run-page + preflight integration pattern).
  • Follow-up: Planned Roads phase-2 package for non-inslope designs and higher-fidelity hydrograph merging.

Timeline Estimate

  • Expected duration: 1-2 weeks (implementation + validation).
  • Complexity: High.
  • Risk level: High.

References

  • wepppy/nodb/mods/roads/specification.md - Canonical Roads phase-1 specification.
  • wepppy/weppcloud/routes/nodb_api/project_bp.py - Canonical mod toggle endpoint and backend guards.
  • wepppy/weppcloud/routes/run_0/run_0_bp.py - Run-page mod registry, TOC task mapping, and mod section rendering.
  • wepppy/weppcloud/templates/header/_run_header_fixed.htm - Header Mods dropdown source.
  • wepppy/nodb/redis_prep.py - TaskEnum and emoji/label contract.
  • services/preflight2/internal/checklist/checklist.go - Checklist completion logic.
  • wepppy/rq/job-dependencies-catalog.md - Queue dependency governance artifact.
  • /workdir/wepppyo3/wepp_interchange/src/hill_pass.rs - Existing pass parser used as combiner foundation.
  • Fixture defaults:
    • run id: clogging-starch
    • wd: /wc1/runs/cl/clogging-starch
    • config: disturbed9002-wbt-mofe.cfg
    • roads input: /wc1/runs/cl/clogging-starch/roads/UM1_roads_info.geojson
    • DEM: /wc1/runs/cl/clogging-starch/dem/wbt/relief.tif

Deliverables

  • Active ExecPlan: prompts/active/roads_nodb_inslope_e2e_execplan.md.
  • Package tracker with milestones, risks, and validation checklist: tracker.md.
  • Implemented Roads phase-1 code and tests across NoDb, WEPPcloud, rq-engine, RQ, preflight2, and wepppyo3.
  • Validation artifacts (e2e logs, review notes, final validation summary) under artifacts/.

Follow-up Work

  • Road designs beyond Inslope_bd and Inslope_rd.
  • Physics-aware hydrograph merge beyond phase-1 approximation rules.
  • Additional production hardening from post-implementation telemetry.