RVA James

A family-friendly James River conditions dashboard for Richmond, Virginia.

There are a half-dozen places to read raw USGS gage data, NWS forecasts, and James River Watch bacterial samples. None of them tell a parent in Richmond, in plain language, whether it's safe to take a four-year-old to skip rocks at Belle Isle today. This app does — by pulling the data on a schedule, running it through a deterministic safety-rules engine, and layering a small amount of AI on top to translate conditions into experience.

Who it's for

Richmond families with kids who want to spend a day at the river without spending an hour piecing together gauge readings, advisories, weather, and trail closures from five different websites first.

The app shows nine specific access points — Belle Isle, Pony Pasture, Texas Beach, Browns Island, Mayo Island, Shiplock Trail, North Bank Trail, Buttermilk Trail, Pump House — with status, recommendations tailored to the youngest family member's age band, and a per-location detail page with resources and activity guidance.

What it does

Pulls live data from USGS (two gages, historical percentiles), NWS (forecast + alerts), NOAA AHPS (72-hour flood forecast), James River Association (water quality), and rva.gov (CSO + park closures) on Cloudflare Cron Triggers.
Applies a deterministic rules engine (lib/safety/rules.ts + lib/safety/thresholds.json) to compute a status (safe / caution / danger / closed) per access point. The same thresholds drive the at-a-glance UI and the AI prompt — single source of truth.
Layers AI on top, lazily. Anthropic Claude (Haiku by default, Sonnet on high-severity advisories) generates a metro-river summary and per-location interpretations only when a visitor requests them. Results are cached in Supabase keyed by a prompt hash so repeat visits cost nothing.
Respects age bands. A "youngest child" selector (0-2 / 3-5 / 6-9 / 10-13 / 14+ / none) tailors the language and the recommended activities, grounded in AAP, NPS, and USCG guidance.
Surfaces closures and advisories prominently. A trail being out for months structurally outranks "the river is fine today" in the UI — closed locations sort to the top with a distinct treatment (gray with a lock icon, not danger red).

Tech stack

Layer	Choice	Why
Framework	Next.js 15, App Router, React 19, TypeScript	Server Components + streaming + edge-runtime support
Hosting	Cloudflare Workers via `@opennextjs/cloudflare`	Cheap, fast, global. Replaced `@cloudflare/next-on-pages` (deprecated) early.
Database	Supabase (Postgres)	Generated TypeScript types, RLS for anon read-only access, service-role for ingest writes
AI	Anthropic Claude API — Haiku default, Sonnet on escalation	Prompt caching keeps cost negligible; lazy on-demand generation cached in Supabase
Styling	Tailwind CSS v4 (CSS-first via `@theme`)	No JS config; container queries native
Validation	Zod	Runtime validation at every external boundary (API ingest, AI output)
Scraping	cheerio	Works on Workers with `nodejs_compat`
Auth (admin only)	Cloudflare Access	Zero-trust gate; no auth code to maintain
Tests	Vitest	Pure-function rules-engine coverage

Architecture at a glance

                                                                  
   ┌──────────────────┐    ┌──────────────────┐                     
   │ USGS  (15 min)   │    │ NWS+NOAA (hourly)│   Cloudflare Cron   
   │ JRA   (daily)    │    │ RVA closures (1d)│   Triggers          
   │ RVA CSO (12h)    │    │ USGS pct (daily) │                     
   └────────┬─────────┘    └────────┬─────────┘                     
            │                       │                               
            └───────────┬───────────┘                               
                        ▼                                           
                ┌───────────────┐                                   
                │   Supabase    │   conditions_snapshots,           
                │   (Postgres)  │   advisories, location_status,    
                │               │   usgs_percentiles, ...           
                └───────┬───────┘                                   
                        │                                           
                        ▼                                           
            ┌───────────────────────┐                               
            │   Next.js Server      │                               
            │   Components on       │                               
            │   Cloudflare Workers  │                               
            └───────────┬───────────┘                               
                        │                                           
              Rules engine (deterministic)                         
                        │                                           
                        ▼                                           
            ┌───────────────────────┐                               
            │   Page render         │                               
            │   • Deterministic UI  │                               
            │   • <Suspense>        │                               
            │      └─► Lazy AI ─────┼──► Anthropic (Haiku/Sonnet)    
            │           cached     │      + cached system prompt    
            │           in DB      │                                
            └───────────────────────┘

Decisions and references

Highlights:

Mobile-first, always. Families check on the way to the river. Touch targets ≥44px, single-column at 375px viewport, no hover-only affordances. Desktop is responsive (capped at ~896px in the main column) but the design language is mobile.
Two USGS gages, different datums, never compared numerically. Westham (02037500) for safety thresholds (gage height in feet, established normal range). City Locks (02037705) for downriver tidal context (NAVD 1988 elevation). The system prompt and rules engine explicitly know they're not comparable.
Lazy AI, not cron. Original plan generated 45+ interpretations daily on a cron. That's pure waste at low traffic. Switched to on-demand generation with lib/ai/get-or-generate.ts cached in Supabase by prompt hash. UNIQUE constraint handles concurrent-write races. Net cost at current traffic: pennies per month.
Rules engine + AI hybrid, not pure AI. The homepage location cards are deterministic — a status pill computed from lib/safety/rules.ts. AI narration only appears in the metro summary at top and on per-location detail pages, where its voice and nuance earn their keep. Avoids 9 AI calls per homepage visit.
Prompt caching is critical. The cached system prompt (~6200 tokens) holds brand voice, location encyclopedia, activity matrix, age-band reference (AAP/NPS/USCG-grounded), and safety thresholds. Per-call input is just today's conditions + advisories + age bucket. First call of the day pays cache-create; everything else reads cache.
Modern web platform over polyfills. Native <dialog> with closedby="any". Container queries via Tailwind v4 @container. text-wrap: balance and pretty. Speculation Rules for prefetch. The GoogleChrome/modern-web-guidance skill (installed via skills-lock.json) informs component-level decisions.
Closures are operational state, not weather advisories. Stored in a separate location_status table with kind enum (open / restricted / closed / closed_indefinite). A closed location overrides weather-based status entirely.
Manual admin entry for closures; rva.gov scrape produces drafts for review. No automated Facebook/Instagram ingest — ToS and brittleness. Admin route at /admin/closures (Cloudflare Access-gated).

Running locally

Prerequisites

Node.js 20+ and pnpm (npm i -g pnpm)
Docker Desktop (for the local Supabase stack)
Supabase CLI (brew install supabase/tap/supabase)
An Anthropic API key for AI generation (optional for most local work; required to test the lazy AI path end-to-end)

One-time setup

git clone <this repo>
cd rva-james
pnpm install

# Start the local Supabase stack
supabase start
# Note the printed URL, anon key, and service_role key

# Copy env templates
cp .env.development.local.example .env.development.local

# Wrangler requires the filename .dev.vars — symlink it to the single source of truth
ln -s .env.development.local .dev.vars

Populate .env.development.local with:

Variable	Value
`NEXT_PUBLIC_SUPABASE_URL`	Supabase API URL (`http://127.0.0.1:54321` locally)
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	anon key from `supabase start`
`SUPABASE_URL`	same as `NEXT_PUBLIC_SUPABASE_URL`
`SUPABASE_ANON_KEY`	same as anon key
`SUPABASE_SERVICE_ROLE_KEY`	service_role key from `supabase start`
`ANTHROPIC_API_KEY`	your Anthropic API key (optional locally)
`CRON_SECRET`	any random string for local cron testing

Run

pnpm dev                 # Next.js dev at http://localhost:3000

For a faithful preview of the Cloudflare Worker build:

pnpm build:cf            # OpenNext build
pnpm preview             # Local Worker at http://localhost:8787

Triggering cron jobs locally

Hit each cron route directly with the CRON_SECRET header:

curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/usgs
curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/nws
curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/jra
curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/cso
curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/usgs-percentiles
curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/noaa-ahps
curl -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/cron/rva-closures

Each returns { ok, rowsWritten } on success.

Tests

pnpm test                # Vitest — pure-function rules engine + ingest

Key commands

Command	Description
`pnpm dev`	Next.js dev server
`pnpm build:cf`	OpenNext Cloudflare bundle
`pnpm preview`	Local Worker preview
`pnpm deploy:cf`	Deploy to Cloudflare Workers
`pnpm test`	Vitest
`pnpm lint`	ESLint
`supabase db push`	Apply migrations to linked project
`supabase gen types typescript --local > lib/supabase/types.ts`	Regenerate DB types

Project structure

app/
  page.tsx                       Homepage (deterministic + lazy AI)
  layout.tsx                     Brand font, metadata
  globals.css                    Tailwind v4 @theme + tokens
  locations/[slug]/              Per-location detail
  safety/                        Safety + sources page
  status/                        Ingestion + cost dashboard
  admin/closures/                Cloudflare Access-gated closure admin
  api/cron/<source>/route.ts     Each ingest job
  _dev/                          Dev-only routes (NODE_ENV gated)
  brand/                         Brand token showcase (dev-gated)
components/
  metro/                         RiverSegmentPanel, MetroSummaryPanel,
                                 RiverConditionsDetailDialog,
                                 RiverWideActivityGrid
  tiles/                         RiverLevelTile, AdvisoriesBanner, ...
  ui/                            PageContainer, HorizontalGauge,
                                 Sparkline, TrendArrow
  filters/                       ConditionsForm
  location/                      ActivityMatrix, ResourceList
  legal/                         DisclaimerFooter, FirstVisitModal
  banners/                       FloodBanner
lib/
  ai/                            client, get-or-generate, system-prompt,
                                 prompts/{interpret-location, summarize-metro}
  ingest/                        One file per data source + run.ts wrapper
  queries/                       Server-side data fetchers per surface
  safety/                        rules.ts + thresholds.json (single source
                                 of truth shared with the AI prompt)
  supabase/                      Server + browser clients, generated types
supabase/migrations/             0001..0009 schema evolution

Adapting this to your own river / city / location

The architecture is general-purpose; the data is local. To stand up a version for another waterway:

1. Replace the location data

In supabase/migrations/0001_init.sql (and 0003 for the gauge entries), replace:

The 9 access-point seed rows with your own access points
The two USGS gauge entries with the gauges that cover your river (find them at waterdata.usgs.gov). Confirm which parameter codes are useful — 00065 (gage height), 00060 (discharge), 00010 (water temp), 62620 (tidal/regulated elevation).

2. Replace the data-source URLs

lib/ingest/usgs.ts — gage IDs and parameter codes
lib/ingest/usgs-percentiles.ts — historical percentile fetch (same station list)
lib/ingest/nws.ts — NWS grid point for your city (find via https://api.weather.gov/points/{lat},{lon})
lib/ingest/noaa-ahps.ts — AHPS forecast gauge ID (find at water.noaa.gov)
lib/ingest/jra.ts — replace with your region's bacterial water-quality program (Riverkeeper, Waterkeeper Alliance member, etc.); may require rewriting the scrape entirely
lib/ingest/cso.ts — your city's combined-sewer-overflow advisory page (may not exist for separate-sewer cities; remove if so)
lib/ingest/rva-closures.ts — your city/parks closure announcement page

3. Replace safety thresholds

Edit lib/safety/thresholds.json for your river's characteristics:

Gage height bands (normal_max_ft, flood_stage, etc.) — pull from NWS AHPS for your gauge
Activity-specific thresholds (gage_safe_max_ft per activity)
Rapids class bands (varies by river; James River below the Fall Line is unusual — your river may not have rapids at all)
Bacterial CFU thresholds (usually EPA standards: 235 E. coli / 100mL)

The rules engine in lib/safety/rules.ts reads from this JSON — no code changes needed if your river fits the same value shape.

4. Rewrite the cached AI system prompt

lib/ai/system-prompt.ts is the heart of the personality. Update:

The location encyclopedia (terrain notes, hazards, parking, distance from gauges)
Brand voice section
Any city-specific guidance (e.g., the James River's Fall Line and tidal vs. free-flowing reach distinction will differ for your river)

Note: the AI is told to derive nothing it shouldn't — every safety claim is grounded in thresholds.json. Maintain this discipline.

5. Replace brand tokens

app/globals.css @theme block defines colors. Replace Richmond's rva-blue etc. with your city's brand or an independent palette. Verify AA contrast programmatically (e.g. via wcag-contrast) on every foreground/background pair.

6. Replace per-location resource links

supabase/migrations/0006_location_resources.sql seeds the resource links per access point. Rewrite for your locations — your local parks department, riverkeeper, NPS unit, etc.

7. Update copy

app/safety/page.tsx — your local emergency services + relevant authorities
components/legal/DisclaimerFooter.tsx — adjust if local liability framing differs
components/legal/FirstVisitModal.tsx — first-visit copy
Site metadata in app/layout.tsx

8. Cloudflare + Supabase + domain

Create a Cloudflare Workers account and a Supabase project
wrangler secret put the four secrets (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ANTHROPIC_API_KEY, CRON_SECRET)
Add public vars to wrangler.jsonc
supabase link --project-ref <yours> and supabase db push
pnpm deploy:cf
Configure your domain in the Cloudflare dashboard
Set up Cloudflare Access for /admin/* with allowed admin email(s)

9. Test the full data flow

Trigger each cron route against the deployed Worker, confirm ingestion_runs rows show ok=true, visit the homepage. The deterministic side renders instantly; the AI side warms on first visit per (date, age bucket) combo.

What this codebase is and isn't

Is: A serviceable starting point for any city-river dashboard targeting families. The patterns — deterministic rules + lazy AI cached in Supabase, cron-driven ingest, modal-and-disclosure UX — are reusable.

Isn't: A turnkey SaaS, a generic data dashboard framework, or production code for high-traffic use. It's tuned for one specific river, one specific audience, and traffic that fits in Cloudflare Workers' free tier. If your river is dramatically different — significant ice formation, tidal-only with no free-flowing reach, no public gauges — expect to rewrite more than you reuse.

License

See LICENSE. The data sources have their own licenses and terms; respect upstream attribution requirements (USGS public domain, NWS public domain, James River Association attribution requested, OSM if you add map tiles, etc.).

Acknowledgments

USGS Water Services and NOAA AHPS for the public hydrology data that makes any of this possible
The James River Association for their volunteer-driven James River Watch bacterial sampling program
The City of Richmond Department of Public Utilities for the CSO advisory feed
The James River Park System volunteers who keep the access points open
The GoogleChrome/modern-web-guidance team for the guide library that informs many UI decisions in this codebase

Name		Name	Last commit message	Last commit date
Latest commit History 117 Commits
.claude		.claude
.lighthouseci		.lighthouseci
app		app
components		components
docs		docs
lib		lib
scripts		scripts
supabase		supabase
types		types
.env.development.local.example		.env.development.local.example
.env.read-prod.example		.env.read-prod.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
lighthouserc.json		lighthouserc.json
middleware.ts		middleware.ts
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
open-next.config.ts		open-next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
wrangler.jsonc		wrangler.jsonc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

RVA James

Who it's for

What it does

Tech stack

Architecture at a glance

Decisions and references

Running locally

Prerequisites

One-time setup

Run

Triggering cron jobs locally

Tests

Key commands

Project structure

Adapting this to your own river / city / location

1. Replace the location data

2. Replace the data-source URLs

3. Replace safety thresholds

4. Rewrite the cached AI system prompt

5. Replace brand tokens

6. Replace per-location resource links

7. Update copy

8. Cloudflare + Supabase + domain

9. Test the full data flow

What this codebase is and isn't

License

Acknowledgments

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

RVA James

Who it's for

What it does

Tech stack

Architecture at a glance

Decisions and references

Running locally

Prerequisites

One-time setup

Run

Triggering cron jobs locally

Tests

Key commands

Project structure

Adapting this to your own river / city / location

1. Replace the location data

2. Replace the data-source URLs

3. Replace safety thresholds

4. Rewrite the cached AI system prompt

5. Replace brand tokens

6. Replace per-location resource links

7. Update copy

8. Cloudflare + Supabase + domain

9. Test the full data flow

What this codebase is and isn't

License

Acknowledgments

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages