# Tripline — Product Specification (Interview Reference)

Use to answer candidate questions. Let them probe. How they explore the problem is a signal.

---

## 1. Overview

**Concept:** Group trip planning app. Multiple travelers coordinate an itinerary — flights, accommodation, activities, meals — with shared budget tracking, voting for decisions, and AI trip building.

**Users:** Group of 2–8 travelers planning a trip together. One trip organizer (creator), rest are participants with edit permissions.

**Platform:** Responsive web app. Mobile-first (on-the-go trip planning, checking directions, sharing expenses). Desktop for heavy planning sessions.

---

## 2. Personas

### Primary: Trip Organizer
- 25–45, planning a 5–10 day group trip (family vacation, friend trip, couples getaway)
- Does the bulk of planning upfront. Coordinates preferences, budget, timing.
- Pain: back-and-forth messages "what do you want to do?", surprise costs nobody agreed to, itinerary drift (too ambitious)
- Wants: structured timeline, budget visibility, clear decision points, ability to propose options for group vote

### Secondary: Trip Participant
- Joins via invite link, adds limited input (vote on activities, suggest changes to single day)
- Less investment in overall structure. Cares about: their budget share, free time, must-see items
- Wants: quick view of what's happening each day without reading the full itinerary

### Tertiary: Passive Follower (not traveling)
- Parent, partner not going on trip. Wants read-only access to see itinerary.
- No edit ability. No vote. No expense visibility.

---

## 3. Core Features (v1)

### 3.1 Trip Creation & Setup

- Create trip: name, destination city/country, date range, expected number of travelers
- Budget: total budget, per-category breakdown (flights / hotels / food / activities / transport). Optional — trip can be budget-agnostic.
- Invite: generate share link. Invited user creates account or joins as guest (limited to voting + suggestions).
- Trip template: save trip as template for reuse (e.g., "Annual Japan Trip" with same structure, different dates).

### 3.2 Itinerary Builder

- Day-by-day view. Each day has flexible event slots (no fixed 3-meal structure like MealPlan).
- Event types:
  - **Flight / Transport** — departure/arrival time, terminal, confirmation number, cost, traveler group
  - **Accommodation** — check-in/out times, address, confirmation number, cost, room assignments
  - **Activity** — name, location, start/end time, cost, tickets needed, booking link, notes
  - **Meal / Dining** — restaurant name, cuisine, price estimate, reservation status, party size
  - **Free time** — unstructured block, no cost, optionally suggested activities
- Drag-reorder events within a day. Drag between days (future).
- Time conflict detection: two events overlapping → warning (non-blocking — organizer may intentionally overlap e.g. parallel activities for subgroups).
- Each event can have cost assigned: total, per-person basis, or who-paid + split method (equal / proportional / custom).
- Weather data: location-based weather forecast shown on each day header (external API). Rainy day → indoor activity suggestions.

### 3.3 Budget & Expense Tracking

- Trip-level budget: category targets. Visual bars per category (spent vs budget).
- Per-event cost: tracked in trip currency. Conversion from local currency if receipts in different currency.
- Expense split: manual assignment per traveler (equal split default). Future: receipt scan AI for auto-detection.
- Per-traveler summary: total spent, total owed, per-category breakdown.
- Settlement: "Sara owes Haijun ¥12,000" — suggested transfers at trip end.
- Overspend detection: category exceeds budget → warning shown on event creation + budget panel.

### 3.4 Group Voting

- Trip organizer creates a poll: propose multiple options for a decision point (which restaurant, which day trip, which hotel).
- Participants vote. Single vote per person. No ranked choice (v1).
- Results: public real-time. Tally shown with bars.
- Winner: simple plurality. No tiebreaker rule — organizer decides.
- Poll expiry: time-limited ("vote by Nov 1") or decision-deadline-bound.
- Poll suggestions: participants can add write-in option. Organizer approves or rejects.

### 3.5 AI Trip Builder

- Chat interface. System prompt includes: destination, dates, traveler count, budget, dietary preferences, mobility constraints, interests (collected during trip creation)
- Capabilities:
  - **Full itinerary generation:** "Plan 7 days in Tokyo for a family with teens, mix of culture and fun, budget ¥650k" → produces structured 7-day plan with estimated costs per event
  - **Day refinement:** "Day 3 is too packed — suggest removing one activity and adding more free time"
  - **Budget rebalancing:** "We're over on food — suggest cheaper lunch options on Days 4–6"
  - **Weather-aware suggestions:** "Day 4 forecast is rain — suggest indoor alternatives"
  - **Activity gap detection:** "Day 5 has nothing after 3pm — suggest evening options"
- Output is structured events with time estimates, cost estimates, and booking links (where available). User accepts individually or as batch.
- AI never books anything. It generates proposals. User confirms → event added to itinerary.

### 3.6 AI Feature — Smart Itinerary Generation

> "Here's my trip: Tokyo, Nov 3–10, family of 4, budget ¥650k, love food and culture, one picky teen. Build me a plan."

- Input: structured form (destination, dates, travelers, budget, interests, constraints) OR natural language prompt.
- Process: AI generates day-by-day plan including:
  - Morning/afternoon/evening allocations
  - Meal suggestions with cuisine diversity
  - Travel time estimates between locations (geocoding + distance API)
  - Cost estimates per event, per day, total
  - Free time buffers to avoid over-scheduling
- Constraints enforced:
  - Budget (total + per-category)
  - Time (open/close hours of attractions)
  - Travel time (geographic feasibility — not "breakfast in Shinjuku, morning in Kamakura")
  - Dietary restrictions
  - Pace (family with teens ≠ solo backpacker pace)
- Post-generation: user can accept whole day, single events, or regenerate specific days. AI retains context of what was accepted/rejected.

---

## 4. Data Model (Core Entities)

```
Trip
  id, creator_id, title, destination, country, currency,
  start_date, end_date, status (draft/finalized/ongoing/completed),
  template_id?, created_at, updated_at

Traveler
  id, trip_id, user_id?, guest_token?, role (organizer/participant/follower),
  name, dietary_restrictions[], interests[], joined_at

Day
  id, trip_id, date, day_number, weather_forecast? (cached),
  notes? (free-text for organizer)

ItineraryEvent
  id, day_id, event_type (flight/accommodation/activity/meal/transport/free_time),
  title, description, location, latitude?, longitude?,
  start_time, end_time, duration_min,
  cost_amount, cost_currency, cost_paid_by (traveler_id),
  cost_split_method (equal/proportional/custom),
  confirmation_number?, booking_url?,
  status (proposed/confirmed/cancelled/tentative),
  source (user/ai),
  tags[], created_by, created_at, updated_at

Poll
  id, trip_id, question, created_by, expires_at?, status (open/closed/decided),
  created_at

PollOption
  id, poll_id, text, added_by (organizer only)

Vote
  id, poll_option_id, traveler_id, created_at

Expense (alternative: event-centric where each event carries cost)
  id, trip_id, event_id?, payer_id (traveler), amount, currency,
  category, description, date, split_map (traveler_id → amount),
  receipt_url?, created_at

TripSettlement
  id, trip_id, from_traveler_id, to_traveler_id, amount,
  status (pending/settled), settled_at?

ChatMessage
  id, trip_id, role (user/assistant), content,
  suggested_event_ids[], created_at

TripTemplate
  id, creator_id, name, description, destination?,
  duration_days, itinerary_events[] (template with relative days),
  budget_template (category limits), used_count
```

---

## 5. Non-Functional / Constraints

### 5.1 Performance
- Itinerary for a 7-day trip loads in <2s (max 50 events per day × 7 = 350 events).
- Budget recalculation <1s on any event add/edit/delete.
- AI itinerary generation: first chunk visible in <5s, full plan in <15s. Stream as structured content, not raw text.

### 5.2 Offline
- Itinerary read + event check (confirmation numbers, times) must work offline for use during trip.
- Adding/modifying events requires network (conflict avoidance in shared trip).
- AI features: unavailable offline. Graceful fallback with cached suggestions.
- Budget: read-only offline. Fresh calculations need network.

### 5.3 Real-time
- Vote tally updates live across all travelers.
- Itinerary edits by one traveler appear in real-time to others (WebSocket push, not polling).
- Budget update on event change pushes to all viewers.

### 5.4 Scale
- 3,000 trips year 1, 30,000 year 2.
- Average trip: 7 days, 15 events/day, 4 travelers.
- AI generation: most expensive operation. Budget: 5 AI itinerary generations per trip per day max.
- Public API query (weather, maps, place data) — rate limits matter. Cache weather forecast for 6h per city.

### 5.5 Data Privacy
- Trip visibility: only invited travelers can see itinerary. No public listing.
- Guest travelers (no account): data linked to device token. If device lost, organizer must re-invite.
- AI prompt data: trip details sent to LLM API. Must disclose in privacy policy. Opt-out available (no AI features).
- Expense data: visible to all travelers in trip. Settlements visible to relevant pair only.

---

## 6. Open Ambiguities (Deliberate for Interview)

- **Invite flow:** Guest traveler vs account — what's the difference in permissions? How does guest identity persist across devices?
- **Time zone handling:** Trip to Japan, organizer is in US, participants join from different time zones. Events shown in local time? Trip time? Configurable per traveler?
- **Event conflict resolution:** What counts as a conflict? Same time + same traveler? Or two events at same time acceptable if travelers split into subgroups? Not specified.
- **Currency conversion:** Events booked in JPY, expense reported in USD. What exchange rate? Live rate at time of booking? Fixed rate set by organizer? Not specified.
- **Vote tiebreaker:** Poll with 2 options × 2 votes each. No mechanism defined.
- **Cancellation policy:** Event cancelled — does its cost come back to budget? Full amount or penalty? Not specified (varies by real booking). Candidate may ask.
- **Day structure flexibility:** Some trips have no "days" — road trip with flexible timeline. Is day-based model too rigid? Not addressed.
- **AI suggestion relevance quality:** How to handle AI suggesting a restaurant that closes permanently last month? Data freshness for place info.
- **Group messaging vs chat:** "Group Chat" is in sidebar but spec only defines AI chat. Human-to-human messaging within trip — not specified.
- **Itinerary export:** Users want PDF/calendar export. Not in v1. Candidate may ask.

---

## 7. Interview Guidance

| Candidate behavior | Signal |
|---|---|
| Asks about invite flow (guest vs account) unprompted | Strong — thinks about auth + identity |
| Questions time zone handling across travelers | Strong — real-world distributed system aware |
| Asks how AI knows place data freshness | Strong — considers data quality, not just "call API" |
| Brings up currency conversion + exchange rate volatility | Strong — financial feature rigor |
| Notices "Group Chat" sidebar item isn't specified | Strong — detail-oriented, cross-references spec with mockup |
| Asks how event conflict detection handles subgroup splits | Strong — nuanced understanding of group dynamics |
| Accepts voting as simple plurality without questioning edge cases | Weak — misses ties, strategic voting, approval thresholds |
| Doesn't ask about offline itinerary access during actual trip | Weak — misses core use case (you need your plan at the destination) |
| Assumes all travelers have equal editing permissions | Weak — doesn't distinguish organizer vs participant roles |