Trip Planning & Itineraries
Relevant source files
The following files were used as context for generating this wiki page:
The Trip Planning & Itineraries module serves as the central hub for users to organize their stay in Medellín. It integrates AI-driven discovery with structured scheduling, allowing users to move from chatting with an assistant to managing a concrete itinerary. The system handles trip metadata, itemized scheduling, and spatial visualization of planned activities.
The workspace is designed to transition users from a "shortlist" phase (Ideas) to a committed schedule (Itinerary), while providing tools to detect scheduling conflicts and visualize trip items on a map.
Sources: README.md, src/app/trips/page.tsx:41-43, src/components/trips/trip-workspace-view.tsx:10-15
System Architecture
The trip system follows a hierarchical structure where a trip acts as a container for multiple trip_items. These items can represent diverse activities such as rentals, restaurant reservations, or events.
Component Hierarchy
The diagram above shows the navigation flow from the main trips dashboard to specific workspace views.
Sources: src/app/trips/page.tsx, src/app/trips/[id]/page.tsx, src/components/trips/trip-workspace-view.tsx:37-65
Data Flow: Trip Loading
Trips are fetched from Supabase using RLS (Row Level Security) to ensure users only access their own data. The loading process aggregates trip metadata with counts of associated items.
Data Models
Trip Entity
A trip stores high-level planning information including budget, status, and destination.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (UUID) |
title | string | User-defined name for the trip |
status | string | planning, active, completed, or cancelled |
start_date | string | ISO date string for trip commencement |
end_date | string | ISO date string for trip conclusion |
budget | number | Optional financial limit |
currency | string | Optional currency code (e.g., USD) |
Sources: src/lib/trips/load-user-trips.ts:5-16, src/lib/supabase/database.types.ts:2516-2531
Trip Item Entity
Items are specific instances scheduled within a trip.
| Field | Type | Description |
|---|---|---|
item_type | string | event, restaurant, rental, poi, or other |
start_at | string | ISO timestamp for item start |
end_at | string | ISO timestamp for item end |
location_name | string | Name of the venue or place |
latitude | number | Geographical coordinate for mapping |
longitude | number | Geographical coordinate for mapping |
Sources: src/lib/supabase/database.types.ts:2478-2495, src/lib/trips/itinerary-logic.ts:133-141
Itinerary Management Logic
The itinerary is generated by grouping trip_items by calendar day based on their start_at timestamp.
Day Grouping & Sorting
Items are sorted chronologically within each day. Items without a start_at timestamp are placed in an "Unscheduled" bucket.
// src/lib/trips/itinerary-logic.ts:47-56
export function groupTripItemsByDay(items: TripItemRow[]): ItineraryDayGroup[] {
const buckets = new Map<string, TripItemRow[]>();
for (const item of items) {
const key = item.start_at ? dayKeyFromIso(item.start_at) : UNSCHEDULED_KEY;
const list = buckets.get(key) ?? [];
list.push(item);
buckets.set(key, list);
}
// ... sorting logic
}
Sources: src/lib/trips/itinerary-logic.ts:47-75
Conflict Detection
The system automatically identifies overlapping schedules. A conflict occurs when two items on the same day have intersecting time windows. If an item lacks an end_at time, the system assumes a default duration of 60 minutes for the purposes of overlap detection.
UI Components
Trip Workspace View
This component manages the state for different perspectives of a trip (Tabs). It handles the transition between list-based itinerary views and geographical map views.
Sources: src/components/trips/trip-workspace-view.tsx:19-25
Itinerary Panel
The ItineraryPanel renders the grouped items and displays alerts if conflicts are detected.
- Conflict UI: Displays a warning box with specific overlap details (e.g., "10:00 AM Coffee overlaps 10:30 AM Meeting").
- Empty State: Encourages users to save rentals or events from the chat interface to populate the trip.
Sources: src/components/trips/itinerary-panel.tsx:14-43
Trip Map Panel
Visualizes scheduled items that have valid coordinates.
- Filter: Only items with
latitudeandlongitudeare included in the map pin list. - Fallback: If no coordinates exist, it informs the user that items need a location from chat saves.
Sources: src/components/trips/itinerary-panel.tsx:100-110
Summary
The Trip Planning & Itineraries module provides a structured environment for users to manage their Medellín travel plans. By leveraging a centralized Supabase database and intelligent grouping logic, it allows for seamless transitions between AI-driven discovery and practical scheduling. Key features include automated day-grouping, conflict detection, and integrated mapping, all while maintaining strict user data isolation via RLS.