# Weather Standard

Production architecture and deployment gates: [docs/production-readiness.md](docs/production-readiness.md). Local worker, backup, monitoring, and recovery runbook: [docs/operational-infrastructure.md](docs/operational-infrastructure.md). Current backup facts: [docs/backup-inventory-2026-11-03.md](docs/backup-inventory-2026-11-03.md). Staging package: [docs/staging-release-checklist.md](docs/staging-release-checklist.md) and `render.staging.yaml`. Technical-review master index: [docs/technical-review-packages/MASTER-REVIEW-INDEX.md](docs/technical-review-packages/MASTER-REVIEW-INDEX.md). Latest launch gates: [docs/launch-readiness-audit-2026-11-03.md](docs/launch-readiness-audit-2026-11-03.md).

Weather Standard is an in-progress, source-attributed weather and work-planning platform. It uses provider data only: when a live provider fails or returns an unsupported response, the app reports that failure and does not substitute sample or simulated weather.

## Public recommendation service

The root page is the anonymous public checker: select a supported activity, a Canadian or US location, and an eligible verified product. The server calls the existing forecast and shared assessment rules; products without an exact published rule, mismatched jurisdictions, stale/missing weather, and unmet essential onsite evidence cannot become favourable recommendations. Results show forecast source/time, manufacturer document/version, rule method, and missing onsite checks. The public experience does not require an account.

- `/` and `/check` — public checker.
- `/verify` — look up a saved reference.
- `/r/WS-…` — immutable, public HTML recommendation record; the versioned read-only JSON is `GET /api/public/v1/recommendations/:referenceId`.
- `/methodology` and `/about` — public limitations and process.
- `/workspace` — retained authenticated project workspace; `/admin` remains the administration entry point.

Anonymous catalog/check/save endpoints are under `/api/v1/public/`. Saved records use migration `016_public_recommendations.sql`, retain the weather forecast and observation snapshot, document and rule versions, decision, missing evidence, timestamps, and integrity digest, and cannot be edited through public routes. Public location display is reduced to locality/region. Do not expose tenant assessment history through public APIs. Production publication is not authorized; review the deployment gates in [production readiness](docs/production-readiness.md) first.

## Local development

Requirements: Node.js 20+, Docker Desktop with Compose, and a network connection to Nominatim, NOAA/NWS, ECCC GeoMet, and OpenStreetMap tiles.

In PowerShell, from this directory:

```powershell
Copy-Item .env.example .env
```

Edit `.env`: set a unique `POSTGRES_PASSWORD`, the migration/bootstrap-only `DATABASE_URL`, and `WS_USER_AGENT` to an operator contact. After database migrations, run `npm run db:runtime-role`; it creates `WS_APP_DATABASE_URL` with a generated non-superuser role and writes the credential privately into `.env`.

For a new local installation, start the database once and apply migrations:

```powershell
docker compose up -d db
npm install
npm run db:migrate
npm run db:runtime-role
```

Then bootstrap the first admin with the private PowerShell procedure in [production readiness](docs/production-readiness.md), run `npm start`, and open `http://localhost:3000`. The deployment readiness probe is `http://localhost:3000/healthz` and returns only a status. In local development, `/api/health` includes sanitized provider and worker diagnostics; production returns only a minimal status there as well. Detailed system health is available only through the authenticated admin API. Keep `.env` private. The included Compose file is for a new local database; never use it to recreate the existing host database during an app restart.

### Restart and maintain the existing development runtime

The web app and weather refresh worker run as separate processes. `npm start` runs `--web-only`; the registered `WeatherStandardRefreshWorker` Windows Task Scheduler task is configured to run `--worker-only` under `SYSTEM` at startup, with a five-minute retry trigger and one-minute task restart policy. The worker heartbeat is currently live, but controlled crash recovery has not yet been verified: the restricted development process could not terminate its SYSTEM-owned worker process (`Access is denied`). Restart instructions and verification commands are in [production readiness](docs/production-readiness.md) and the [development handoff](docs/development-handoff.md). A PostgreSQL advisory lock prevents overlapping refreshes across processes. Settings are validated before the worker timer starts (`WS_REFRESH_INTERVAL_MINUTES` 10–1,440; `WS_MAX_REFRESH_LOCATIONS` 1–100). Migration 006 marks abandoned `running` refresh rows older than 15 minutes as failed with a recovery note. Migration 008 labels those as `interrupted_recovery`, classifies later provider/system failures, records structured provider-health events, and soft-archives closed refresh rows after 730 days by setting `archived_at`; it deletes no history. PostgreSQL is independent and retains its files and data when the app stops. Do not use `docker compose down -v` or remove the configured PostgreSQL data directory when restarting the app.

In PowerShell from this directory, identify the port-3000 app and gracefully stop only that Node process:

```powershell
$listener = Get-NetTCPConnection -LocalPort 3000 -State Listen
$appPid = $listener.OwningProcess
$app = Get-CimInstance Win32_Process -Filter "ProcessId = $appPid"
if ($app.CommandLine -notmatch 'server/index.js') { throw 'Port 3000 is not the Weather Standard app.' }
& node -e "process.kill($appPid, 'SIGTERM')"
```

Start the app again from the project directory and verify database health:

```powershell
Start-Process node -ArgumentList @('--env-file=.env', 'server/index.js') -WorkingDirectory (Get-Location).Path -WindowStyle Hidden
Invoke-RestMethod http://localhost:3000/api/health
```

The health response must report `status: ok` and `database: connected`; `providerHealth` shows the latest persisted success or failure for NWS and ECCC. App logs emit structured JSON events for provider checks and worker failures. Provider requests identify the client with `WS_USER_AGENT`; transient network, HTTP 429, and HTTP 5xx errors receive at most two bounded retries, honoring `Retry-After` when present. HTTP 4xx errors such as NWS 403 are logged and not retried. NWS requires a descriptive `User-Agent` and documents cache-friendly responses and rate limits; configure a real operator contact before external deployment ([NWS API documentation](https://www.weather.gov/documentation/services-web-api)).

The worker uses `WS_REFRESH_INTERVAL_MINUTES` (default 30; supported range 10–1,440 minutes) and `WS_MAX_REFRESH_LOCATIONS` (default 25; supported range 1–100). The current local configuration runs every 10 minutes for up to 25 saved locations. Invalid values fall back to defaults and log a warning before its timer is created. Refresh rows keep their original status, and archival is an in-place timestamp so history remains queryable.

Apply migrations to the existing database without reinstalling or recreating it:

```powershell
npm run db:migrate
```

The migration runner records each applied migration in `schema_migrations` and skips it on later runs. This command does not drop or reset tables.

## Live data providers

- **United States:** NOAA/National Weather Service point metadata selects hourly and period forecasts, timezone, and nearby observation stations. The adapter checks the five nearest returned stations and selects a fresh observation within two hours. NWS source: [API documentation](https://www.weather.gov/documentation/services-web-api).
- **Canada:** ECCC/MSC GeoMet City Page Weather selects the nearest city forecast feature, normalizes its current, hourly, and multi-day fields, and includes its linked observation/station where present. This ECCC collection is experimental and may be unavailable or change schema; an unsupported response is an error. Review [ECCC data documentation and licence](https://eccc-msc.github.io/open-data/msc-data/citypage-weather/readme_citypageweather_en/) before deployment.
- **Address search:** server-side OpenStreetMap Nominatim, country-limited to Canada and the United States, with a basic one-request-per-second throttle and attribution. This is a minimal development adapter, not a high-volume geocoding service; check current Nominatim policy or replace it before production.
- All forecast snapshots persist provider, fetch time, issue time, source URLs, normalized payload, observations, and forecast periods. Assessments keep the snapshot ID, source/version, method version, inputs, findings, and timestamp. Scheduled refreshes run every 10 minutes locally for locations requested in the past seven days (the default interval for a new configuration is 30 minutes).

## Five-city live smoke check

After starting the app and confirming provider/network access, run:

```powershell
./scripts/smoke-live.ps1
```

The script geocodes Langley, Abbotsford, Vancouver, Toronto, and Buffalo, then checks provider selection, local timezone, snapshot time, hourly and daily series, station-observation presence, and saved snapshot IDs. Station observations are provider-dependent; a missing observation is reported and does not fabricate a value. Use its output to identify a provider-specific failure. This check passed during local verification: all five returned real provider data, the expected timezones, at least 24 hourly and seven daily periods, and a linked station observation.

## Assessments and current coverage

The shared rules module returns `favorable`, `conditional`, `not_recommended`, `restriction_identified`, or `insufficient_data`, with findings and supporting documents. The searchable product picker filters verified products by manufacturer or product name and the selected activity; pending/review items are not exposed. Ten verified manufacturer products currently have product-specific rules: Benjamin Moore Element Guard 0765, GAF fiberglass asphalt shingles, Sika Canada Sikaflex Construction Sealant, Sika Sikafloor-264, Sika Sikafloor-161, Sika Sikaflex-1A, MAPEI Mapelastic AquaDefense, Euclid DURALPREP A.C., Sherwin-Williams Duration Exterior Acrylic Satin K33-Series (PDS 102.14B, March 2026), and Tremco Dymonic FC (current TDS DFC-DS/1026 plus official product page accessed November 2, 2026). Sikaflex-1A cites the official [October 2025, Version 01.09 PDS](https://usa.sika.com/content/dam/dms/us01/q/sikaflex_-1a.pdf) (020511010000000008). Its 40–100°F recommended application-temperature range is used only as an air-forecast screen; assessment remains conditional in-range because weather cannot establish actual joint temperature/preparation or the required 65–75°F product conditioning. For damp concrete, the PDS allows use after standing/excess water is displaced and a 60-minute wait. Sikafloor-161 cites its official PDS, December 2024 Version 05.03 (document 020811020010000049), and screens 50–85°F ambient temperature; it also keeps substrate temperature/dew-point, concrete moisture and RH, ambient RH, material preconditioning, and three-hour onsite rechecks as explicit jobsite requirements. The Duration PDS specifies 35°F (1.7°C) minimums, a 48-hour temperature screen, 5°F (2.8°C) dew-point clearance, and avoiding rain/snow within 2–3 hours. Tremco's product page lists 40–90°F (4–32°C) for application; its current TDS says not to apply over damp or contaminated surfaces. Missing onsite readings remain conditional or insufficient data. Exact source versions and links are stored with each requirement. General guidance records also cover ACI cold-weather concrete planning and FHWA snow/ice context. Regional applicability is checked. Unknown surface/substrate temperatures, moisture, humidity, dew point, material temperature, and protection measures remain unknown; forecast air temperature is not treated as a site measurement. Many other listed activities are explicitly marked research in progress and produce no inferred recommendation.

Work-window suggestions are forecast screens, not guarantees. The website generates downloadable PDF assessment reports. The station map uses Leaflet and OpenStreetMap tiles. The administrator dashboard supports source/review workflows, account/project administration, reset-token issuance, monitoring, and health events. Reviewer and assessment creator identities come from the authenticated database session; company/project scope is enforced by PostgreSQL RLS. Only verified requirements and sources, attached to verified products, are used by public assessments.

## Tests and checks

```powershell
npm test
npm run check
```

Tests use local fixtures only and never feed fixture weather into the live app. Run `npm test` for provider normalization, worker config bounds, candidate validation, and rules; run `npm run check` for JavaScript syntax checks. For five-city real-provider verification, run `./scripts/smoke-live.ps1` after checking `/api/health`. Each new manufacturer rule must cover in-range forecast with missing site inputs, out-of-range forecast, source/version citations, and the available forecast horizon. Enter candidates through `/admin` or authenticated `POST /api/v1/admin/requirements`; candidates start unpublished in `pending`, move to `review`, then `PATCH /api/v1/admin/requirements/{id}/status` to publish after checking the official source. The transition validates supported rule inputs and writes an audit event. Verify `/api/v1/products`, `/api/v1/requirements`, `POST /api/v1/assessments`, `POST /api/v1/work-windows`, and `GET /api/v1/reports/{assessmentId}` with a live persisted `weatherSnapshotId`.

Inspect the scheduler history without starting a second worker by querying PostgreSQL: `SELECT started_at, finished_at, status, locations_attempted, locations_succeeded, error_summary FROM refresh_runs ORDER BY started_at DESC LIMIT 10;`. Compare snapshot rows by provider and refresh type with `SELECT provider_id, refresh_kind, count(*), max(fetched_at) FROM weather_snapshots GROUP BY provider_id, refresh_kind ORDER BY provider_id, refresh_kind;`.

The existing Windows app and persistent PostgreSQL database were verified together. Chromium desktop/mobile checks fetched actual ECCC data for Langley, Abbotsford, Vancouver, and Toronto, and NWS data for Buffalo. Product assessments against saved Buffalo NWS snapshots persisted their weather-source IDs and returned conditional for Benjamin Moore when surface temperature was unavailable; Sikafloor-264 and Sikafloor-161 when required moisture, humidity, and dew-point measurements were unavailable; Tremco Dymonic FC when substrate condition was unknown; and Sikaflex-1A when joint preparation and sealant conditioning were unknown. Source-linked saved reports and PDF downloads were retrieved. The app restart preserved PostgreSQL, and the first scheduled worker run after restart completed for all seven eligible locations; no database reset was performed. Tenant/RLS tests additionally ran in a rollback-only transaction under a non-superuser runtime role and confirmed company isolation.

## Limits before production use

This local platform has not been publicly deployed. ECCC's data collection and Nominatim service have usage/licensing constraints. Requirements are source-attributed weather screens, not legal, engineering, manufacturer, or jurisdictional approval for every product/job. Validate the current product label, exact SKU/region, project specifications, applicable code, and onsite conditions. Do not use this advisory system as a substitute for an official warning or competent jobsite decisions.

Before a public launch: complete company/project onboarding and password-reset handoff; set a TLS public origin and trusted proxy; configure an approved off-host backup target/key and verify an actual encrypted upload/isolated restore; add external monitoring and alert routing; move the worker to the production host's supervisor and service identity; validate providers, source terms, target-region coverage, legal/privacy obligations, accessibility, and RPO/RTO. A previous local encrypted backup/restore passed, but its key is not currently available for a repeat drill; there are no verified off-host successes. See the current [backup inventory](docs/backup-inventory-2026-11-03.md). Never deploy publicly until the remaining gates pass.
## Standards governance and public library

Rule revisions are stored in `standard_rules`; append-only technical reviews and lifecycle/source-verification events preserve their history. Apply migrations 019 and 020 using `npm run db:migrate` against the existing database. The additive migration imports the already verified rules as explicitly marked legacy revisions; it does not rewrite assessments or weather snapshots. Winter Risk remains unpublished and returns insufficient data without thresholds.

System administrators can review the register at `/admin` → **Standards governance**. A new revision starts as draft. Record exact HTTPS sources and citations, move it to technical review, append an internal technical approval from an admin other than the creator, and source-verify it. Weather Standard criteria and external-guidance interpretations also require an external reviewer record with qualifications evidence, no-conflict declaration, and a second system administrator’s evidence check. Then approve with the required evidence, set an effective date, publish, and publish a replacement before superseding an older revision. External reviewer identity is not authenticated by the form, and legacy entries explicitly state that no external expert approval is recorded.

Public consumers can read `/standards` or `GET /api/v1/public/standards`. Only current published source-verified revisions are returned. The API response is read-only and includes rule class, revision, geography, citations, criteria, and determination. `npm run db:governance-check` performs a read-only PostgreSQL/PostGIS, migration, legacy-count, and runtime-role visibility check. `npm run test:public-browser-readonly` audits the public library and checker in headless Chrome at 375, 390, 430, 768, and 1440px without saving public recommendations.
