User stories

Every story, traced to code

The 16 user stories from the product spec, in the traveler's own words, each paired with the exact tool or component that delivers it — a requirements trace, not a checklist.

💰

Smart Date, Budget & Accommodation Optimization

Stories 1–4
1Seasonality
As a flexible traveler, I want the app to identify the main, shoulder, and off-seasons for my destination, so that I can find dates that are less crowded and more budget-friendly.
How: the system prompt drives seasonality reasoning and the agent verifies crowd/weather peaks via grounded web search, surfacing them as scenario highlights (e.g. "Peak crowd").
2Flight date recommendation
As a budget-conscious traveler, I want to provide a broad timeframe (e.g., 10 to 15 days in September) and have the app recommend the exact best dates to fly based on live prices.
How: find_cheapest_dates (Kiwi.com MCP) plus the grounded web-search fallback surface cheap date windows, rendered in the cheapest-dates card.
3Comprehensive budgeting
As a thorough planner, I want the app to estimate and include accommodation costs alongside transportation costs, so that I can see accurate subtotals and a grand total for my entire trip.
How: CostBreakdown renders transport/stay subtotals plus a grand total. Both sides are live: flights and ground transport from Kiwi/research, stays from live accommodation searches.
4Hotel availabilityPhase 6
As a traveler with specific tastes, I want the app to check availability of my preferred hotels for different date windows, so that I don't book flights for dates when my ideal accommodation is sold out.
How: search_accommodations (SerpApi Google Hotels) returns live options for the exact stay dates; min_rating/max_price honor taste and budget, feeding the scenario's stay cost.
🚆

Intelligent Transportation Logistics

Stories 5–6
5Travel parameters & filtering
As a traveler who values convenience, I want to set parameters for my travel (direct flights only, journey length, morning/night flights), so that I avoid inconvenient routes like flights with three layovers.
How: preferences are extracted via gather_preferences, collected through the interactive clarifying-question card when ambiguous, and pre-settable in the global settings modal.
6Route syncing & detailPhase 7
As a trip planner, I want the app to automatically synchronize my connecting travel modes and provide specific routing notes ("Fly to Athens and take the first ferry out to Milos"), so that I have a foolproof logistical plan immediately after landing.
How: search_ground_transport supplies grounded routing for onward hops; the system prompt aligns each departure to the prior arrival plus a realistic transfer buffer, flagging tight and overnight connections in the timeline.
⚖️

Scenario Comparison & Scoring

Stories 7–8
7Comparative layoutPhase 5
As an analytical planner, I want to view multiple travel scenarios side-by-side in a comparative table, so that I can easily weigh the differences in cost, travel flow, and duration.
How: generate_scenarios returns 2–3 scenarios rendered side-by-side with cost breakdowns, stress gauges, and best-value / lowest-stress badges.
8Stress scoring
As a traveler who balances budget with comfort, I want the app to calculate an "overall stress level" for each itinerary, taking into account flight times and difficult connections (like overnight ferries), so that I can make a holistic decision.
How: a 1–5 stress_score backed by structured stress factors, with scoring heuristics in the system prompt.
🧭

Activity & Destination Discovery

Stories 9–10
9Vibe questionnaire
As an explorer unfamiliar with a new location, I want the app to ask me questions to determine the "vibe" I am looking for, so that it can provide tailored recommendations.
How: the human-in-the-loop clarifying card asks focused questions — concrete option pills plus a free-text "Other" — and the answers become persisted vibe tags.
10Manual overridesPhase 10
As an independent traveler, I want the ability to manually override suggestions or tell the app exactly what I plan to do, so that it focuses on logistical heavy-lifting rather than spoon-feeding me sightseeing.
How: system-prompt directive 9: "I already have flights, just plan ground transport" → the agent skips that data tool, zeroes its cost, and plans only the rest, honoring hard constraints.
🖥️

User Interface & Output Formats

Stories 11–12
11Visual summary
As a user reviewing my trip, I want to see a high-level visual summary of the itinerary, so that I can quickly grasp the overall flow of my travel.
How: scenario cards give price/stress/legs at a glance; the detail modal adds a travel timeline and day-by-day plan; the interactive map plots the route with mode-colored legs and stop/stay markers.
12Tabular breakdowns
As a detail-oriented planner, I want the option to view detailed text and tabular breakdowns of my itinerary, so that I can thoroughly understand the specific logistical details.
How: the "View details" modal shows itemized costs, stress factors, a per-direction timeline with connection chips and booking links, an accommodation list, and an expandable time-blocked day-by-day itinerary.
🧠

Session Management & Memory

Stories 13–15
13Iterative feedback
As an iterative planner, I want to provide feedback on the generated itinerary and have the app regenerate the response, so that I am not forced to rely on a single, perfect initial output.
How: native to the chat loop; Phase 10 adds targeted refinement — "make Scenario B direct-only" regenerates just that scenario, carrying the others over unchanged.
14Session persistencePhase 3
As a busy user, I want the app to save my specific trip conversations, so that I can leave the app and return another day to pick up exactly where I left off.
How: trips persist to SQLite with the full AG-UI message history (tool calls included), so every generative-UI card rehydrates on resume from the sidebar.
15Global profile persistencePhase 3+10
As a frequent user, I want the app to remember my baseline likes and dislikes globally, so that when I start a new trip conversation, it automatically applies my previous preferences.
How: a singleton profile loads as the baseline each run and merges conversation preferences on top; the settings modal edits it directly.
🤖

Autonomy & Manual Labor Reduction

Story 16
16Autonomous draft itinerary
As a traveler overwhelmed by manual planning, I want the app to act with a high degree of autonomy (8–9 out of 10) to generate a complete draft itinerary from a high-level prompt, so that I am saved the manual labor of cross-referencing multiple booking sites.
How: the agent plans end-to-end from one prompt — dates, flights, stays, ground transport, day-by-day plans — asking at most a few focused clarifying questions along the way.