Roamly — the spec

Roamly is a personal AI travel agent that turns individual preferences into ready-to-book daily itineraries, then scales that same experience to groups. Everyday consumers who want expert-level trip planning without the back-and-forth use it solo or invite travel companions, with the system handling preference matching, consensus-building, and booking end-to-end.

---

Decisions locked

---

The core loop

1. Profile setup — User answers a short preference questionnaire (budget, travel style, dietary needs, accommodation type) on first sign-in.
2. Itinerary generation — Roamly produces a day-by-day plan with flights, hotels, and activities matched to those preferences.
3. Refine or accept — User taps a single adjustment control to swap any element; the rest of the plan rebalances automatically.
4. Group merge (optional) — User invites companions; each member's preferences feed into a re-generated shared itinerary and open votes settle any conflicts.
5. Book — User (or the group lead) confirms; Roamly executes bookings across flights, hotels, and restaurants through live integrations.
6. Budget dashboard — Per-person costs and shared expenses are tracked in real time throughout the trip.

---

v1 scope

Preference-based itinerary generation with one-tap adjustment
Generates a complete day-by-day travel plan from a user's preference profile. Lives on the main Itinerary screen; a single adjustment rail lets the user swap flights, hotels, or activities without rebuilding the whole plan.

Real-time group voting and consensus on activities
When a group itinerary is active, each member votes thumbs-up or thumbs-down on proposed activities; the highest-consensus option locks in automatically. Lives on the Group Plan screen.

Integration with booking — flights, hotels, restaurants
Connects to third-party booking APIs so confirmed itinerary items convert to real reservations in one step. Confirmation details surface on the Booking Confirmation screen and sync to each user's calendar.

Shared group itinerary with role-based permissions
An Organiser role can edit and confirm; Member roles can vote and view. Role assignment happens at group creation and is visible on the Group Plan screen.

Budget tracking per person and shared expenses
Tracks the cost of each booked element, splits shared costs across the group, and shows each person's running total. Lives on the Budget screen; alerts fire when a selection would breach a personal budget cap.

---

Deliberately later

• Past trip history and preference learning engine — needs a meaningful dataset of completed trips before personalisation signals are reliable; v2 is the right time.
• Offline access to downloaded itineraries and maps — requires a separate caching and sync layer that adds build complexity before the core booking flow is proven.
• Push alerts for group changes and time-sensitive deals — valuable retention tool, but only after the core loop drives completed bookings consistently.

---

Data model sketch

• users — id, name, email, phone, hashed password, created_at
• preferences — user_id, travel_style, budget_range, dietary_needs, accommodation_type, updated_at
• itineraries — id, user_id, group_id (nullable), destination, start_date, end_date, status, generated_at
• itinerary_items — id, itinerary_id, type (flight/hotel/restaurant/activity), provider_ref, cost, day_index, status
• groups — id, name, organiser_user_id, created_at
• group_members — group_id, user_id, role (organiser/member)
• votes — itinerary_item_id, user_id, value (up/down), cast_at
• bookings — id, itinerary_item_id, user_id, provider_confirmation_ref, amount_charged, booked_at
• expenses — id, group_id, user_id, booking_id, amount, split_share, settled (bool)
• payments — id, user_id, stripe_customer_id, last4, created_at

---

Screens

• Onboarding / Preference Setup — captures travel style, budget, and logistics preferences on first use.
• Itinerary — displays the generated day-by-day plan with the one-tap adjustment rail.
• Group Plan — shows the shared itinerary, member list, roles, and the live voting interface.
• Booking Confirmation — summarises confirmed reservations and syncs them to the user's calendar.
• Budget — displays per-person costs, shared expense splits, and budget-cap warnings.
• Account / Settings — manages profile, notification preferences, and payment methods.

---

How to use this document

• Bring it into Mind Palace, where the guided platform and its AI coach pick up from exactly this document and build Roamly with you step by step.
• Hand it to a developer as the complete v1 brief — scope, data model, and screens are defined and ready.
• Keep it as the single source of truth so every product, design, and engineering decision traces back to one agreed baseline.