Disney Wait Planner

A mobile-first Disney park planning app focused on fast decisions, low cognitive load, and clean UX. Disney Wait Planner pairs live attraction wait times with a local-first, multi-day trip planner — and Tom, a built-in assistant that can answer Disney questions and read-only questions about what you've planned.

---

🌐 Overview

Disney Wait Planner supports Disneyland Resort (DLR) and Walt Disney World (WDW). It combines live attraction wait times, a multi-day trip planner (attractions, dining, entertainment, and custom entries), Lightning Lane tracking, and a built-in assistant (Ask Tom) into a single mobile-first interface.

The system enforces a strict boundary between live data and local planner state, and all attraction/plan matching is canonical and deterministic — there is no fuzzy logic.

---

✨ Features

Today

• Resort-local home view with a resort/park selector and a shortcut to Waits & Shows

Waits & Shows

• Live attraction wait times for DLR and WDW, with a resort/park selector (Queue-Times remains the authority for attraction waits and open/closed status)
• Deterministic status handling: planned closures take priority, then live "not operating" status, then a live wait time
• Planned closures are lifecycle-aware — temporary refurbishments (with a known end date or open-ended) and permanent closures are tracked and displayed distinctly, with permanent closures aging out of the active list over time
• Mobile-first ride cards with sorting and land filtering
• Selected-park park hours for today (park operating window; shown as "Closed" only when provider data safely establishes it, otherwise "Unavailable")
• Entertainment showtimes for today on curated Entertainment entries that are mapped to ThemeParks.wiki, including multi-showtime events. Entries with no posted, remaining, or available showtimes say so rather than guessing; unmapped entries show no showtime line. Showtimes are today-only — there is no future-date showtime lookup

My Plans

• Manual, day-scoped itinerary builder across attractions, dining, entertainment, and custom entries
• Smart Entry suggestions for known attractions, dining locations, and entertainment, with automatic type detection; unmatched names fall back to a manual type selector
• Multi-day planning with per-day labels/dates, and day-scoped Lightning Lane reservations
• Day-aware park context (auto-derived from your plans, or manually overridden)
• Exact-date park hours for the active day: when a day has a valid date, My Plans shows that park's hours for that specific date using the day's existing park context (no separate park selector). Dates the provider hasn't published yet show as not yet available, and failures show as unavailable — hours are never extrapolated
• TXT/CSV import, plus three export/restore scopes — Full Backup (all days, Plans and Lightning Lane), Plans Backup (all days, Plans only), and Day Export (just the active day's Plans and Lightning Lane) — with a metadata preview shown before restoring
• Cross-day duplicate detection (attractions and Lightning Lane) and conflict detection (overlapping times, Lightning Lane vs. plan conflicts), shown as informational signals — the app never modifies your itinerary automatically

Lightning Lane

• Manual Lightning Lane reservation tracking, day-scoped alongside My Plans
• Live countdown and deterministic bucket sorting, with live wait overlay and inline editing

Profiles & Sync

• Multiple profiles with isolated planner data
• Optional sign-in with cloud sync across devices
• Signed-in profiles and profile names are available across devices
• Pull-before-push and conflict-safe sync protect cloud data from being silently overwritten

Ask Tom

Tom is Disney Wait Planner's built-in assistant. Tom can:

• Answer general Disney questions — parks, lands, attractions, dining, entertainment, experiences, and news, including where known attractions, dining locations, and experiences are located
• Answer supported wait time questions
• Use schedule context from My Plans: for planner days with a valid date that is today or later, Disney Wait Planner can send that day's park hours (and, for a day dated today, today's Entertainment showtimes) so Tom can reference them. This is optional and bounded — if it can't be gathered quickly, Tom is simply asked without it
• Look up today's Entertainment showtimes for a park independent of your planner, via a server-to-server endpoint (GET /api/tom/showtimes, authenticated with DWP_CATALOG_API_KEY) that Tom calls with a structured park (and optionally a show name). Like all showtimes in the app, this is today-only and covers only curated, ThemeParks-mapped Entertainment
• Answer Planner Insights questions: read-only, planner-aware questions and analytics about your local trip planner — what you have planned, conflicts, repeats, park assignments, and simple analytics like "which day has the most planned"
• Hold a conversation, including natural follow-up questions

When an answer uses ThemeParks.wiki schedule data, the Tom page shows a linked "Powered by ThemeParks.wiki" attribution; planner-only answers show none.

Tom does not edit your plans, generate or optimize itineraries, reason about transportation or travel time, or make predictions/recommendations it isn't designed to support. Planner data shared with Tom is a compact, read-only summary — Tom cannot write back to your planner. See the in-app Tom Help Guide (/tom/help, linked from the Ask Tom Help modal) for the full, current list of what Tom can do.

---

📡 Live Data

Live attraction wait times are powered by the Queue-Times API, accessed through a server-side proxy rather than called directly from the browser. All wait data flows through a single unified path (liveWaitApi.ts), which returns the same shape regardless of source and falls back to a mock dataset if live data is disabled or unavailable — so the UI never breaks on a live-data outage.

Park hours and Entertainment showtimes come from the ThemeParks.wiki (Free API), accessed only server-side (themeParksApi.ts; the browser never calls the provider) and normalized before use (parkHours.ts, parkHoursService.ts, entertainmentShowtimes.ts). It is used for:

• Park hours — today's hours on Waits & Shows and exact-date hours in My Plans (/api/park-hours)
• Today's Entertainment showtimes on Waits & Shows (/api/entertainment/showtimes)
• Optional schedule context for Ask Tom (see above)

ThemeParks.wiki does not replace Queue-Times for attraction waits, and it does not decide which attractions or Entertainment exist: the curated DWP catalog stays the canonical identity authority, and Entertainment is matched to the provider only through an explicit mapping. It needs no environment variables. Surfaces that display ThemeParks.wiki data show the linked attribution via components/ThemeParksAttribution.tsx ("Powered by ThemeParks.wiki").

---

🏗 Architecture

• Next.js (App Router) + TypeScript, in a pnpm monorepo (apps/*, packages/*)
• Deployed on Vercel (see Development below for branch/deploy workflow)
• Planner state (My Plans, Lightning Lane) is local-first: localStorage is the source of truth, and cloud sync mirrors it when signed in
• Live wait data is unified behind a single provider path (see Live Data above)
• Tom is integrated through a server-side proxy (/api/tom/ask) to the Tom Railway API — Tom credentials are never exposed to the browser
• Attraction naming is resolved deterministically through coordinated canonical-identity paths — one for live data and planned closures, one for My Plans and Lightning Lane — kept in parity so naming differences never cause mismatches or duplicates

For implementation-level invariants, data flow details, and correctness constraints, see AGENTS.md.

---

📁 Project Structure

This is a pnpm workspace:

• apps/web — the Next.js frontend app
• packages/shared — shared types and mock data

The Next.js App Router lives at apps/web/src/app (not apps/web/app).

---

🛠 Development

Development happens on feature branches; main is the production branch, and Vercel builds a preview deployment for every branch.

# Install dependencies
pnpm install

# Run the web app locally (http://localhost:3000)
pnpm --filter web dev

# Production build
pnpm --filter web build

# Run a production build
pnpm --filter web start

# Type-check the shared package
pnpm --filter @disney-wait-planner/shared typecheck

# Apply/migrate the Postgres schema (see apps/web/src/lib/db-schema.sql)
DATABASE_URL=... pnpm --filter web run db:migrate

Never run dev/build at the repo root without --filter web — the monorepo root has no app of its own to run.

db:migrate is safe to run repeatedly against a fresh or already-migrated database (it's a no-op the second time) — see AGENTS.md's Deployment section for the required production ordering (migrate schema, then deploy app code) whenever db-schema.sql changes.

Environment Variables

Live wait data

• NEXT_PUBLIC_WAIT_API_ENABLED — true to enable live wait data; unset or false runs the app mock-only
• NEXT_PUBLIC_WAIT_API_BASE_URL — optional override for the wait API base URL; defaults to the same-origin proxy

Authentication & sync (optional; required for sign-in and cloud sync)

• NEXTAUTH_URL — canonical app URL (e.g. https://your-app.vercel.app)
• NEXTAUTH_SECRET — random secret (openssl rand -base64 32)
• DATABASE_URL — Postgres connection string used by the auth adapter and sync
• EMAIL_SERVER, EMAIL_FROM — email provider settings for magic-link sign-in

Daily park-hours refresh (server-only)

• CRON_SECRET — required by /api/cron/park-hours (Vercel Cron, 02:00 UTC daily via apps/web/vercel.json); the route fails closed (500) when unset. Vercel sends it as Authorization: Bearer.

Ask Tom (server-only — never expose these as NEXT_PUBLIC_*)

• TOM_API_URL — Tom Railway API base URL
• TOM_API_KEY — Tom Railway API key
• DWP_TOM_PROXY_KEY — shared secret used by the server-side Tom proxy
• DWP_CATALOG_API_KEY — shared secret Tom presents (via the x-dwp-catalog-api-key header) to call the read-only GET /api/catalog/query catalog lookup endpoint

---

🧭 Contributing

See AGENTS.md for repository conventions, scope discipline, and the correctness invariants (local-first/profile safety, canonical attraction identity, planned-closure enforcement, and Tom's read-only planner integration) that must be preserved when touching those areas.