SideQuest

AI-generated real-world adventure quests. Tell it how much time you have and how you're getting around; it picks a short route of real nearby places and writes a quest narrative to go with it.

Setup

npm install
npm run dev

Open http://localhost:3000.

The app runs entirely in mock mode out of the box — no API keys required. Every external integration (auth/DB, location data, weather, the LLM narrative, map tiles, analytics) has a mock fallback, so you can sign up, onboard, and generate full quests with zero configuration.

Environment variables

Copy .env.example to .env.local and fill in whichever you want to enable. Each is independently optional:

• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY — real Postgres/PostGIS storage and auth via Supabase. Unset → an in-memory/local JSON mock store handles users, profiles, locations, and quests instead. If you do configure Supabase, run the migration in supabase/migrations/0001_init.sql against your project first.
• GOOGLE_PLACES_API_KEY — pulls candidate locations from Google Places Nearby Search in addition to OpenStreetMap (Overpass). Unset → OSM only, with synthetic mock locations filling in if neither source returns enough results.
• OPENWEATHER_API_KEY — real current-weather lookup, used to favor/penalize outdoor stops. Unset → a neutral "clear" mock weather snapshot.
• ANTHROPIC_API_KEY — Claude (Haiku) writes the quest title/intro/objective copy. Unset, or any API failure → a template-based mock narrative is used instead. Note: the LLM only ever writes copy; stop selection is always done by the scoring engine, never the model.
• NEXT_PUBLIC_MAPBOX_TOKEN — nicer map tiles on the quest screen. Unset → free OpenStreetMap raster tiles.
• NEXT_PUBLIC_POSTHOG_KEY / NEXT_PUBLIC_POSTHOG_HOST — product analytics. Unset → tracking calls no-op.
• NEXT_PUBLIC_SENTRY_DSN — error monitoring (client, server, and edge runtimes, plus a global error boundary). Unset → Sentry's SDK initializes as a no-op. SENTRY_ORG / SENTRY_PROJECT / SENTRY_AUTH_TOKEN are optional on top of that and only enable source-map upload on build for nicer stack traces.

How it works

1. Onboarding — user picks interests and (optionally) shares their home location.
2. Quest generation (/quest/new → POST /api/quest/generate) — given a time budget, transport mode, and budget tier, the backend:
   • fetches candidate nearby locations (cache → OpenStreetMap → Google Places → mock, in that order, stopping once it has enough),
   • scores them with a transparent weighted-sum formula (interest match, novelty, distance fit, weather fit, popularity — weights in lib/scoring.ts),
   • greedily picks a 2-3 stop route,
   • asks Claude to write a short narrative and per-stop objective text (or falls back to a template),
   • saves the quest and returns it.
3. Active quest (/quest/[id]) — shows the route on a map, lets the user check off objectives as they complete them (recorded to visit history so future quests favor novelty), and mark the quest complete once all stops are done.
4. History (/history) — past and in-progress quests.

Notable simplifications (documented in code)

• Geo filtering uses haversine distance in application code rather than a PostGIS spatial query/RPC — simpler to reason about at MVP scale, easy to swap later if location volume grows.
• Scoring weights in lib/scoring.ts are a hand-picked starting point, not tuned on real usage data yet.
• Auth is a single httpOnly session cookie holding a user id — no JWT/refresh-token machinery, sufficient for an MVP behind HTTPS.

Tech stack

Next.js 14 (App Router, TypeScript), Tailwind CSS, Supabase (Postgres/PostGIS + Auth, optional), Anthropic Claude (Haiku) for narrative copy, OpenStreetMap Overpass + Google Places for location data, OpenWeatherMap for weather, Leaflet/react-leaflet for maps, PostHog for analytics.