Travel: product requirements

1. What this is

Travel is an AI companion for a group of family or friends taking a trip together. It carries the trip from "where should we go?" through planning, through the trip itself, and into the memories afterward.

Two modes define it:

• Planning mode. The group decides where to go and when, locks in the skeleton (flights and the moves between major destinations), then fills in lodging, cities, each day, and finally the hours inside each day.
• Travel mode. The trip is underway. The system knows where everyone is, helps them find each other, handles delays and changes, suggests restaurants, lets people propose what to do tomorrow, collects everyone's photos into one album tied to the map, and acts as a tour guide that can explain whatever someone points their phone at.

The goal is a trip that is better than the group could have planned or run on their own, with less friction among the people on it.

2. Who uses it

Person	What they need
Organizer	Starts the trip, invites people, makes final calls when the group is split. Usually does most of the planning work.
Co-planner	Shares the planning: researches, proposes, books their share.
Traveler	Goes on the trip. May contribute little to planning but needs the plan, the schedule, and help on the ground. Includes kids, grandparents, the less technical.
Follower	Stays home and follows along: the itinerary, where the group is today, the album. Read-only.

These are roles within a trip, and one person can hold different roles on different trips. They are separate from the app-wide ladder (customer, staff, admin, superadmin), which governs the site itself.

Design for the least technical traveler. If grandma can't see today's plan and find the group from her phone, the feature isn't done.

3. The trip lifecycle

Decide  ->  Dates  ->  Skeleton  ->  Fill in  ->  Day by day  ->  Travel  ->  Remember
|------------------- planning mode ---------------------------|  travel mode  |  after

Phases overlap. People keep refining the plan while booking, and travel mode replans constantly. The trip is one living plan throughout, with no export or handoff between phases.

3a. What real trips taught us

Draft 2 draws on how this family already plans: years of trip folders in Google Drive, itinerary spreadsheets, confirmation PDFs, document trackers and a trip journal. What they show:

• The itinerary is a grid of days split into morning, afternoon and evening, and every entry is typed: Fly, Drive, Check in, Check out, an activity or a meal. Each entry links to its booking and a map.
• Ground transfers are as big as flights. Private drivers between cities, pickup windows, a price per person in local currency, who arranged it, the vehicle, and drives of five hours or more that take a whole day.
• Not everyone is on every segment. Some fly out a day early from a different airport; someone joins only for the flight home.
• Each flight carries a lot: two confirmation numbers (the airline's and the booking site's), a ticket number and seat for each traveler, loyalty numbers, layover lengths, arrivals on the next calendar day across time zones, and baggage rules that differ by airline.
• Documents are tracked per person: passport expiry, a visa whose valid dates must cover that person's days in the country, trusted traveler status.
• Travel credits and gift cards expire and are often tied to one traveler's name, and they get spent in pieces across several bookings.
• Booking evidence is kept: screenshots of the options considered, the upgrade offered, the checkout page, the cancellation.
• Things go wrong, and the journal remembers. Food poisoning far from a hospital, a closed road, a flat tire, a booked apartment given to someone else on arrival, a "luxury" boat that wasn't, rainy days stuck indoors. The family turned it into stories and poems afterward, with AI help.
• Some legs are visits to relatives, who speak another language and are not users of the site.
• The same destination comes back. A second trip to the same country is already being planned, and the lessons of the first one should carry over.

Each of these shows up as a requirement below.

4. Planning mode

4.1 Decide where to go

• An idea board: anyone in the group adds candidate destinations with notes, links and photos.
• Shared social media links: someone sends a TikTok, Instagram Reel or YouTube Short ("we have to do this!"), by pasting it, sharing it from the phone's share sheet, or forwarding it on WhatsApp. The system works out what it recommends (the place, activity or restaurant, where it is, rough cost) from the caption, hashtags, location tag and, where allowed, the spoken audio, and files it on the idea board or the right day with the link kept as the source. When it cannot tell, it asks the sender one short question instead of guessing.
• Group input: each person states interests, budget comfort, mobility limits, must-haves and dealbreakers, privately if they prefer.
• AI suggestions that fit the group's stated constraints, with the reasoning shown (season, cost, travel time from each person's home, kid-friendliness).
• Voting and discussion on candidates; the organizer closes the decision.

4.2 Pick the dates

• Each person marks availability and blackout dates (school calendars, work, events).
• The system weighs availability against season, weather, prices, local holidays and events, and proposes date windows with the tradeoffs spelled out.
• Trip length and rough shape (one base, or several stops) are settled here.

4.3 Lock the skeleton

The skeleton is the set of big, hard-to-change commitments.

• Legs: the sequence of major destinations and how long in each.
• Long-haul and intercity transport: flights, trains, ferries, rental cars, and hired drivers between legs. A multi-day driver who carries the group across several legs is one booking with many segments.
• Ground transfers are first-class: pickup place and time window, who arranged it and how to reach them, vehicle and seats, price and currency, and the driving time, so a five-hour drive is planned as most of a day.
• Different origins: members may fly from different home cities and converge. Each person's own route in and out is part of the plan, and arrival times are visible to everyone.
• Who is on each segment: every flight, transfer and night of lodging lists its travelers. People can join late or leave early, and the plan shows who is where on any day.
• Flights in full: airline and booking-site confirmation numbers, each traveler's ticket number and seat, loyalty numbers applied, layover length (with a warning when it is very long or too tight), and times shown in each airport's local zone with a "next day" marker.
• Baggage rules per segment, with the strictest one across a journey called out, since the cheapest leg usually sets the limit.
• Checks across trips, not only within one. A person's travel is one timeline, and conflicts happen between separate trips: landing from one trip at dawn and leaving on the next one that night, from a different airport in the same city. The system checks every traveler's trips together for overlaps, tight turnarounds and airport changes, and makes the connection between trips (rest, a transfer, a shower) part of the plan.
• Overnight flights land a calendar day later. Every arrival is placed on the day it actually lands, so a hotel night that is booked but never used, or needed but never booked, is flagged. A dawn arrival before check-in time prompts an early check-in or a day room.
• Fare and schedule research, with AI comparing options against the group's constraints (cost, layovers, kids, arrival time).
• Booking happens on airline and travel sites. The trip records what was booked, by whom, and for whom (see 4.6).
• Each element has a state: idea, proposed, agreed, booked, confirmed.

4.4 Fill in

• Lodging for every night, with a check that no night is uncovered and no one is unhoused. One stay can hold several rooms, each with its own booking and occupants.
• An arrival card for every stay, available offline: the address in the local language for a driver, check-in and check-out times, entry codes and lock instructions, Wi-Fi, the host's and manager's contacts, parking, and checkout instructions. Rental hosts send these in emails; AI pulls them out.
• Which cities or towns within each leg, and day trips.
• Local transport between them.
• Key reservations with limited availability (popular restaurants, timed museum entries, tours) flagged early so they get booked in time.
• Vendor vetting before booking: recent reviews over old ones, photos checked against what guests report, and what is actually included (meals, drinks, transfers). A place advertised as "luxury" with recent complaints gets flagged.
• Reconfirm before arrival: a few days ahead, the system reminds someone to reconfirm each stay and transfer, so a double-booked apartment is found from home instead of at the door.

4.5 Day by day, then within the day

• Each day gets a plan: where the group sleeps, where it goes, what is fixed and what is open.
• Morning, afternoon and evening are the default slots, the way the family already plans. Exact times are added where they matter (a flight, a pickup, a reservation).
• Every entry has a type (fly, drive, check in, check out, activity, meal, visit) and links to its booking and a map. Costs are kept in the local currency with the home-currency equivalent beside them.
• Within a day: activities, meals, travel time between them (realistic, with kids), rest, and deliberately open time.
• The group can split for part of a day and reconvene; the plan shows who is where.
• AI drafts days on request and checks plans for problems: closed on that weekday, too far apart, too much packed in, no lunch.
• Pacing awareness: jet lag on day one, a lighter day after a heavy one.

4.6 Planning tools that span every phase

• Proposals and votes on anything: a destination, a hotel, a day's plan.
• Comments on any item.
• Assignments: who is researching or booking what, with due dates.
• Who controls each booking, and how it was paid. Every booking records the seller (the airline, a credit card's travel portal, a booking site), the payment type (cash, points, a voucher or credit, or a mix), the refund and change rules, and the right contact with hours and time zone. A flight bought with card points is changed through the card's travel desk, not the airline, and in a 2am cancellation that decides what the options are.
• Bookings and documents: confirmations kept with the item they belong to. Forwarding a confirmation email, or uploading a PDF, adds it to the trip; AI extracts the details (times, locations, confirmation numbers, travelers) and places it in the itinerary for review.
• Checklists: entry rules, vaccinations, insurance, things to do before leaving home, and packing lists from reusable templates (clothes, toiletries, medicine, electronics, documents), adjusted for each person, the weather and the activities.
• Booking evidence: screenshots of options considered, upgrade offers, checkout pages and receipts are kept with the booking, and canceled bookings stay on record with their cancellation, so a dispute or refund claim has what it needs.
• Compare options side by side: two date windows or two routings, each with its total for flights, lodging, car and activities.
• Budget and shared expenses: estimated cost by category, actual spend, who paid, and who owes whom.
• Traveler profiles: each person's name exactly as on their passport, passport expiry, visas, trusted traveler status, loyalty numbers, seat and meal preferences. The system warns when a passport expires too soon for the destination's rules, when a visa's valid dates don't cover that person's days in the country, and when the name on a booking doesn't match the passport.
• Visa photos: each traveler takes the photo their visa needs with their own phone, checked against the destination's rules before it is sent (Visa photos; Vietnam first).
• Credits and vouchers wallet: airline credits and gift cards with their balance, expiry, and whose name they are tied to, with partial use tracked. The system suggests applying them when booking and warns before they expire.
• Versions: the plan's history, so a change can be seen and undone.
• Calendar export: each person's own itinerary in their calendar.

5. Travel mode

Travel mode turns on as the trip starts. The phone is the main device.

5.1 Today

• One screen with now and next: where to be, when, how to get there, what is booked, confirmation numbers at hand.
• Reminders timed to reality: "leave in 15 minutes to make the 2:00 tour," adjusted for where the person actually is.
• A morning briefing and an evening wrap-up, by app or message.

5.2 Where everyone is

• Opt-in location sharing per trip, limited to the trip's dates, with a visible indicator when it is on and a one-tap pause.
• A group map: where everyone is right now.
• Finding each other: meeting points, "walk me to Dad," a suggested regrouping spot when the group is scattered.
• The server knows the group's progress against the plan and can notice when the plan has drifted (running late, someone off course).

5.3 Changes and exceptions

• Watch for disruptions: flight delays and cancellations, strikes, weather, closures.
• When something breaks, propose concrete alternatives that respect the rest of the trip (rebook options, reshuffled days, a replacement activity) and show what each one changes downstream.
• Send the traveler to whoever actually controls the booking (section 4.6), with the number, the confirmation codes and a script of what to ask for, and check the knock-on effects on any other trip that traveler has.
• Handle the personal ones too: someone sick, a lost item, a missed train.
• Illness: track symptoms across the group, find the nearest clinic or hospital with good reviews for foreigners, help decide when it is time to go, buy what is needed nearby (a thermometer, a pulse oximeter, oral rehydration salts), and replan the next days around recovery.
• On the road: closed roads, breakdowns and flat tires, with the driver's contact and the next stay told about a late arrival.
• A stay that falls through on arrival: find a vacancy nearby right now, even on a holiday, and record what happened for the refund claim.
• A washed-out day: indoor alternatives ready when the forecast turns.
• Safety information at hand: emergency numbers, nearest hospital or pharmacy, embassy, each traveler's emergency contacts and medical notes.

5.4 Visiting family and local hosts

• Some stops are visits to relatives or friends who are not users of the site. The plan holds their address, contacts, and what to bring.
• Translation both ways for conversations, messages and directions, so the driver and the relatives can be reached in their own language.
• Optional pages in the language of the people being visited, so relatives can see when the group arrives and add photos without an account.

5.5 Food

• Restaurant suggestions near the group or along the route, weighing dietary needs, kids, budget, cuisine preferences, and whether it is open now.
• Reservations where possible, and realistic wait times.
• Remember what the group liked.

5.6 Open time and tomorrow

• Anyone can propose an idea for an open slot or for tomorrow; the group votes or the organizer decides.
• When time is left open, the AI suggests things that fit the moment: the weather, energy levels, what is nearby, what the group has already seen.
• Saved social media finds come back at the right moment: "the dumpling place from the TikTok your daughter sent is a ten-minute walk from here."

5.7 Tour guide

• Location-aware narration: as the group moves, the guide tells them about what is around them, at a depth they choose (kids' version, quick facts, deep history).
• Point the phone at something (a building, a painting, a menu, a sign, a plant) and the guide identifies it and explains it. Follow-up questions are a conversation.
• Translation of signs, menus and conversations.
• Self-guided tours built for the group's interests, for a museum, a neighborhood or a whole city.

5.8 Shared photo album

• Everyone contributes photos from their phones, with as little effort as possible (bulk upload, ideally automatic for the trip's dates).
• Photos are placed by time and location into the trip's days and onto the map.
• Duplicates and near-duplicates are grouped; the best shots rise to the top.
• AI captions and identifies places, and builds daily highlights.
• Each person controls which of their photos are shared.
• The album is a map-integrated story of the trip, viewable by followers at home during the trip.

6. After the trip

• The album becomes a finished trip story: map replay of the route, day pages, highlights, shareable with family.
• An optional printed photo book.
• Trip stories: the journal, the day's events and the photos become a written account, and on request a poem or a funny retelling in a chosen style. The family already does this by hand with an AI chat; here it uses everything the trip knows.
• Reviews and claims: draft honest reviews of places from the group's notes, and follow refunds, chargebacks and disputes until they close.
• Settle up shared expenses.
• Capture what worked and what didn't, as notes for the next trip.
• Reuse a trip as the template for a future one.
• Carry lessons forward: returning to the same country brings up what went well and badly last time: the hotel worth repeating, the boat to avoid, the food to be careful with.

7. The AI throughout

• One assistant that knows the trip: the plan, the bookings, the people and their preferences, where everyone is, what has already happened. Reachable from any screen and from messaging.
• Acts, with confirmation. It drafts, proposes and fills in; anything that commits the group (a change to a booked item, a message to everyone, a purchase) waits for a person to approve.
• Remembers people across trips: dietary needs, interests, pace, who gets carsick, what someone loved last time. Each person can see and edit what is remembered about them.
• Shows its sources for facts that matter (opening hours, entry rules, prices) and says when information may be stale.
• Cost-aware: model usage is tracked per trip, and expensive features (vision, long narration) are used where they earn it.

8. Where people use it

Surface	Role
Web app	Planning, on a laptop: the full itinerary, maps, research, budgets.
Phone	Travel mode: today, the group map, the guide, the camera, photo upload. A mobile web app first; a native app if location tracking, background upload and offline use require it (open question 1).
WhatsApp	A low-effort channel for everyone, especially the less technical: ask the assistant, get the morning briefing, receive alerts. The switchboard already provides this.
Email in	Forward booking confirmations to the trip.
Calendar out	Each person's itinerary in their own calendar.
Google Drive and TripIt	Import past trips from the family's existing Drive folders (itinerary spreadsheets, confirmation PDFs) and from TripIt, so history and lessons are there from day one. Optionally mirror each trip's documents back to a Drive folder per stop.

9. Cross-cutting requirements

• The trip is the unit of sharing. Today the app scopes every record to one user. Trips are shared by several people with different roles, so a trip-membership model is the first architectural change, and every feature above depends on it.
• Privacy and consent. Location, documents (passport details) and medical notes are sensitive. Location is opt-in, time-boxed and visible when on. Documents are visible only to the person and whoever they choose. Minors' data is controlled by their guardian. Passport numbers, ticket numbers, gift card numbers and PINs, door codes and Wi-Fi passwords are kept encrypted, shown only to the travelers they belong to, never shown to followers, and sent to the AI only when a task needs them. Today these sit in plain spreadsheets; moving them into the site has to be safer than that.
• Works with bad connectivity. Today's plan, bookings, confirmation numbers, maps for the area and emergency info must be available offline. Photo uploads queue and resume.
• Time zones are first-class. Every time is stored with its place's zone; a flight's departure and arrival show in their own local times.
• International. Currencies, units, and languages of the places visited.
• Accessibility. Large text, simple flows, screen reader support; usable by kids and older travelers.
• Reliability during the trip. An outage at home is an inconvenience; an outage at a train station abroad is a failure. Travel mode degrades gracefully to the offline copy.

10. External capabilities needed

From the inventory of ~/projects/common (2026-10-04). "Exists" means a shared module already does it; the rest needs building, ideally into common where another app would want it.

Capability	Status
Sign-in, roles, database, UI kit, feedback, docs	Exists, wired into this app
Geocoding, distance, nearby places, map links	Exists (common/location, OpenStreetMap); needs production hardening
Photo location and time from EXIF, HEIC conversion	Exists (common/media)
PDF and email text extraction, OCR, Claude client	Exists; the booking extraction built on them does not
WhatsApp, email, SMS notifications	Exists (switchboard, common/notify)
File storage (local, S3-compatible)	Exists; needs byte uploads and direct browser upload
Interactive maps on a page	Missing
Time zone from a location	Missing
Calendar export (.ics) and Google Calendar	Missing
Thumbnails and resizing	Missing
Sharing records among a group	Missing
Flight search and status, weather, currency rates, restaurant data and reservations, translation, landmark recognition	Missing; each needs a provider decision
Live location from phones, push notifications, offline storage	Missing
Reading shared TikTok, Instagram and YouTube links	Missing; access is restricted by each platform (open question 8)

11. Out of scope for now

• Being a booking engine or travel agency. The app records and organizes bookings made elsewhere; it may deep-link to booking sites.
• A public social network. Trips are private to their members and the followers they invite.

12. Suggested build order

Each step is usable on its own and builds toward the next.

1. Trips and members: create a trip, invite people, trip roles, the shared-record model. Replaces the demo pages. Built 2026-10-24; its detailed PRD is Trips and members.
2. The skeleton: legs, transport, lodging, on a map and a timeline, with time zones. Its draft PRD, for review before it is built, is The skeleton.
3. Day by day: days and items within them, proposals and votes, the assistant drafting and checking plans.
4. Bookings in: forward or upload a confirmation, AI places it.
5. Shared album: upload, place by time and location, map view.
6. Travel mode basics: today screen, reminders, WhatsApp briefings.
7. Location and finding each other.
8. Exceptions and replanning.
9. Tour guide: narration, then point-and-ask with the camera.
10. Decide and dates: destination ideas, availability, AI suggestions. Last because a group with a trip already in mind gets value from 1 to 9 without it.

13. Decisions

#	Date	Decision	Why
D1	2026-10-04	Travel runs its own sign-in (AUTH_MODE=own), not the fleet's shared login. Each person gets an account valid only on this site, held in Travel's own users table.	Mike's call. It also lets trip membership be a foreign key to Travel's own user rows.
D2	2026-10-04	Sign-in methods: email and password, with invitations sent as one-time setup links, plus Google sign-in with the same address as an option. Two-factor available and required for admins once enrolled.	common.web_auth own mode already provides all three. The account is still Travel's either way; Google only proves the email.
D3	2026-10-04	The demo bookmarks migration stays (0001_bookmark_title). When trips replace bookmarks, a new revision drops the table.	A deployed database records the revisions it has run; deleting a shipped migration breaks every later upgrade. Keeping it means the first deploy can go ahead whenever it is ready.
D4	2026-10-24	Travel moves to Node and TypeScript, built like speechpad-new: a Fastify API, a Next.js site, Postgres, and common's TypeScript packages. Sign-in is @common/auth (Better Auth) with the methods of D2. D1 holds: accounts are Travel's own. D3 no longer applies; the Node site has no demo pages.	Mike's call. TypeScript is now the reference for the platform's web features, and a later web app builder generates this layout.
D5	2026-10-24	The app-wide ladder is customer, staff, admin, superadmin, the platform's default. Family members are customers; Mike is superadmin.	Every shared feature and its tests run on it. Trip roles (section 2) are separate either way.

14. Open questions

Answer each question in place; your answers are saved for everyone reading this page.