StayTonight.app

- architecture, components & workflow -

Enter PIN to continue

BETA live at staytonight.app · repo mfugel/staytonight · Next.js 16 on Vercel

"Where should I sleep tonight?" — given a start (typed or GPS), an optional destination or heading, and a drive budget, StayTonight finds campsites within reach, ranks them with an LLM for the traveler's rig, and overlays weather, cell coverage & points of interest.

Input Our code / platform External enrich LLM

The stack

Framework	Next.js 16.2 (App Router, Turbopack), React 19.2, TypeScript 5
Styling	Tailwind CSS 4 + CSS variables (6 themes: 4 dark, 2 light)
Auth	Clerk (`@clerk/nextjs` v7) — Google, email 6-digit code, password
Database	Neon serverless Postgres (`@neondatabase/serverless`)
Maps	MapLibre GL (demo tiles)
AI ranking	OpenAI `gpt-4.1` (default) · Anthropic `claude-sonnet-4-6` (alt)
Hosting	Vercel (team `jerseymark`), push-to-`main` auto-deploy; DNS at Namecheap

External data sources

Source	Used for	Module
RIDB (Recreation.gov)	Federal campgrounds (50mi radius)	`lib/ridb.ts`
OSM Overpass	Dispersed/backcountry sites, RV parks; rest areas, dump stations	`lib/osm.ts`, `lib/pois.ts`
Geoapify Places	Points of interest (fast, reliable)	`lib/pois.ts`
NOAA / NWS	Tonight's forecast + alerts	`lib/noaa.ts`
OpenCellID	Per-carrier cell signal	`lib/opencellid.ts`
Nominatim (OSM)	Geocoding place names → lat/lng	`api/geocode`
OpenAI Whisper	Voice input (gpt-4o-transcribe)	`api/transcribe`

API routes

/api/recommend	Candidates → preRank → enrich → LLM rank (the main search)
/api/pois	Geoapify POIs + best-effort Overpass (overnight, dump) — lazy/opt-in
/api/geocode	Nominatim proxy (place name → coords)
/api/transcribe	Whisper voice → text
/api/profile	GET/PUT/DELETE — Neon profile (prefs, address, account delete)
/api/favorites	GET/PUT — saved spots
/api/feedback	POST bug/idea → GitHub issue + Neon; GET (owner-only) list

Key components

RouteInput	Origin/dest/heading + drive budget (mi/km/hours), voice mic
CandidateMap	MapLibre map: numbered pins + per-category POI markers + Show/Hide POI
CandidateList	Ranked cards: weather, cell, pros/cons, ♥ favorite, Reserve/Find/Directions
SearchPrefsSummary	Search-settings recap + transient per-category POI map filter
PreferencesPanel	Rig, travel, POI cats, theme, profile (photo/address), account, delete
FavoritesPanel · HelpPanel	Saved spots; About + bug/idea feedback (+ owner admin list)

Notes

Auth & data sync. Clerk gates the app in-page (useAuth + RedirectToSignIn), not in middleware. Preferences & favorites load instantly from localStorage, then reconcile with the Neon-backed account on sign-in (server wins; first sign-in migrates local up) — so they sync across devices.

14 POI categories. scenic · historical · towns · food · fuel (diesel-aware) · overnight parking · grocery · laundry · gyms · propane/supply · mechanic · dump station · hospital/ER · police. Most via Geoapify; overnight & dump via best-effort Overpass (8s timeout, degrade gracefully).

Status — beta, not yet "production-grade." Open items: production map tiles (currently MapLibre demo tiles), privacy policy + terms (we store email/address), API rate limiting, automated tests, and broader real-world testing. Passkeys deferred (Clerk Pro). Full detail in the repo's docs/ARCHITECTURE.md, TESTER_GUIDE.md, TEST_PLAN.md.