# ywcharles/itinerary architecture

> Architecture diagram of the GitHub repository ywcharles/itinerary, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ywcharles/itinerary
- Repository: https://github.com/ywcharles/itinerary

## Overview

Tripcident is a collaborative trip-itinerary planner. Travelers create or join trips, then build and share a schedule of activities; the itinerary view adds maps, travel times, weather, place suggestions, and AI-assisted schedule reviews. The central state is the itinerary’s stops, synchronized through Supabase. Review discovery checks free-time gaps, nearby places, opening hours, and travel legs before asking Gemini for proposals; users can preview and accept changes. The README documents the Google Maps view, while the sampled excerpts do not establish every page-to-component or suggestion-search connection.

Main entry points: [`app/itinerary/ItineraryView.tsx`](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/ItineraryView.tsx) (Itinerary view), [`app/itinerary/components/ReviewPanel.tsx`](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/ReviewPanel.tsx) (Review panel), [`app/page.tsx`](https://github.com/ywcharles/itinerary/blob/main/app/page.tsx) (Landing page), [`lib/reviewContext.ts`](https://github.com/ywcharles/itinerary/blob/main/lib/reviewContext.ts) (Review context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trip_entry["Trip entry"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_create_trip["Create trip<br/>[CreateTripForm.tsx]"]
  node_join_trip["Join trip<br/>[JoinTripForm.tsx]"]
  node_recent_trips["Recent trips<br/>[RecentTrips.tsx]"]
end

subgraph group_itinerary["Itinerary planning"]
  node_trip_page["Itinerary page<br/>[page.tsx]"]
  node_itinerary_view["Itinerary view<br/>[ItineraryView.tsx]"]
  node_stops_hook["Stop state<br/>[useStops.ts]"]
  node_stop_components["Schedule and edits<br/>[Schedule.tsx]"]
  node_calendar["Calendar<br/>[Calendar.tsx]"]
  node_maps["Map display<br/>[Maps.tsx]"]
  node_travel_legs["Travel legs<br/>[useTravelLegs.ts]"]
  node_weather_ui["Day weather<br/>[DayWeather.tsx]"]
end

subgraph group_discovery["Ideas and review"]
  node_review_panel["Review panel<br/>[ReviewPanel.tsx]"]
  node_review_context["Review context<br/>[reviewContext.ts]"]
  node_review_discovery["Gap discovery<br/>[reviewDiscovery.ts]"]
  node_suggestions["Place suggestions<br/>[suggestions.ts]"]
  node_review_api["Review endpoint<br/>[route.ts]"]
  node_ai_review["Proposal validation<br/>[aiReview.ts]"]
end

subgraph group_services["Data and integrations"]
  node_weather_api["Weather endpoint<br/>[route.ts]"]
  node_maps_link_api["Maps link resolver<br/>[route.ts]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_supabase[("Supabase")]
  node_routes["Route calculation<br/>[routes.ts]"]
  node_google_maps["Google Maps APIs<br/>[googleMaps.ts]"]
end

node_traveler(("Traveler"))
node_gemini["Gemini"]
node_open_meteo["Open-Meteo"]

node_traveler -->|"opens"| node_landing
node_landing -->|"offers"| node_create_trip
node_landing -->|"offers"| node_join_trip
node_landing -->|"shows"| node_recent_trips
node_traveler -->|"submits trip"| node_create_trip
node_traveler -->|"joins trip"| node_join_trip
node_trip_page -->|"renders"| node_itinerary_view
node_itinerary_view -->|"loads stops"| node_stops_hook
node_itinerary_view -->|"displays schedule"| node_stop_components
node_itinerary_view -->|"displays calendar"| node_calendar
node_itinerary_view -->|"displays map"| node_maps
node_stops_hook -->|"reads and writes"| node_supabase_client
node_supabase_client -->|"accesses"| node_supabase
node_itinerary_view -->|"derives legs"| node_travel_legs
node_travel_legs -->|"requests routes"| node_routes
node_routes -->|"computes routes"| node_google_maps
node_itinerary_view -->|"shows forecast"| node_weather_ui
node_weather_ui -->|"requests weather"| node_weather_api
node_weather_api -->|"fetches forecast"| node_open_meteo
node_review_panel -->|"collects context"| node_review_context
node_review_context -->|"finds gaps"| node_review_discovery
node_review_context -->|"searches places"| node_suggestions
node_review_context -->|"checks travel"| node_routes
node_review_panel -->|"sends review request"| node_review_api
node_review_api -->|"reads stops"| node_supabase
node_review_api -->|"requests proposals"| node_gemini
node_review_api -->|"parses and validates"| node_ai_review
node_review_panel -->|"validates proposals"| node_ai_review
node_review_panel -->|"saves accepted changes"| node_supabase_client
node_maps_link_api -->|"returns resolved link"| node_traveler

click node_landing "https://github.com/ywcharles/itinerary/blob/main/app/page.tsx"
click node_create_trip "https://github.com/ywcharles/itinerary/blob/main/app/components/start/CreateTripForm.tsx"
click node_join_trip "https://github.com/ywcharles/itinerary/blob/main/app/components/start/JoinTripForm.tsx"
click node_recent_trips "https://github.com/ywcharles/itinerary/blob/main/app/components/start/RecentTrips.tsx"
click node_trip_page "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/%5Bslug%5D/page.tsx"
click node_itinerary_view "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/ItineraryView.tsx"
click node_stops_hook "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/hooks/useStops.ts"
click node_stop_components "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/Schedule.tsx"
click node_calendar "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/Calendar/Calendar.tsx"
click node_maps "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/Maps.tsx"
click node_travel_legs "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/hooks/useTravelLegs.ts"
click node_weather_ui "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/DayWeather.tsx"
click node_review_panel "https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/ReviewPanel.tsx"
click node_review_context "https://github.com/ywcharles/itinerary/blob/main/lib/reviewContext.ts"
click node_review_discovery "https://github.com/ywcharles/itinerary/blob/main/lib/reviewDiscovery.ts"
click node_suggestions "https://github.com/ywcharles/itinerary/blob/main/lib/suggestions.ts"
click node_review_api "https://github.com/ywcharles/itinerary/blob/main/app/api/itinerary-review/route.ts"
click node_ai_review "https://github.com/ywcharles/itinerary/blob/main/lib/aiReview.ts"
click node_weather_api "https://github.com/ywcharles/itinerary/blob/main/app/api/weather/route.ts"
click node_maps_link_api "https://github.com/ywcharles/itinerary/blob/main/app/api/resolve-maps-link/route.ts"
click node_supabase_client "https://github.com/ywcharles/itinerary/blob/main/lib/supabase.ts"
click node_routes "https://github.com/ywcharles/itinerary/blob/main/lib/routes.ts"
click node_google_maps "https://github.com/ywcharles/itinerary/blob/main/lib/googleMaps.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_create_trip,node_join_trip,node_recent_trips toneBlue
class node_trip_page,node_itinerary_view,node_stops_hook,node_stop_components,node_calendar,node_maps,node_travel_legs,node_weather_ui toneAmber
class node_review_panel,node_review_context,node_review_discovery,node_suggestions,node_review_api,node_ai_review toneMint
class node_weather_api,node_maps_link_api,node_supabase_client,node_supabase,node_routes,node_google_maps toneRose
class node_traveler,node_gemini,node_open_meteo toneIndigo
```

## Components

### Trip entry

- [Landing page](https://github.com/ywcharles/itinerary/blob/main/app/page.tsx): `app/page.tsx`
- [Create trip](https://github.com/ywcharles/itinerary/blob/main/app/components/start/CreateTripForm.tsx): `app/components/start/CreateTripForm.tsx`
- [Join trip](https://github.com/ywcharles/itinerary/blob/main/app/components/start/JoinTripForm.tsx): `app/components/start/JoinTripForm.tsx`
- [Recent trips](https://github.com/ywcharles/itinerary/blob/main/app/components/start/RecentTrips.tsx): `app/components/start/RecentTrips.tsx`

### Itinerary planning

- [Itinerary page](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/%5Bslug%5D/page.tsx): `app/itinerary/[slug]/page.tsx`
- [Itinerary view](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/ItineraryView.tsx): `app/itinerary/ItineraryView.tsx`
- [Stop state](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/hooks/useStops.ts): `app/itinerary/hooks/useStops.ts`
- [Schedule and edits](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/Schedule.tsx): `app/itinerary/components/Schedule.tsx`
- [Calendar](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/Calendar/Calendar.tsx): `app/itinerary/components/Calendar/Calendar.tsx`
- [Map display](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/Maps.tsx): `app/itinerary/components/Maps.tsx`
- [Travel legs](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/hooks/useTravelLegs.ts): `app/itinerary/hooks/useTravelLegs.ts`
- [Day weather](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/DayWeather.tsx): `app/itinerary/components/DayWeather.tsx`

### Ideas and review

- [Review panel](https://github.com/ywcharles/itinerary/blob/main/app/itinerary/components/ReviewPanel.tsx): `app/itinerary/components/ReviewPanel.tsx`
- [Review context](https://github.com/ywcharles/itinerary/blob/main/lib/reviewContext.ts): `lib/reviewContext.ts`
- [Gap discovery](https://github.com/ywcharles/itinerary/blob/main/lib/reviewDiscovery.ts): `lib/reviewDiscovery.ts`
- [Place suggestions](https://github.com/ywcharles/itinerary/blob/main/lib/suggestions.ts): `lib/suggestions.ts`
- [Review endpoint](https://github.com/ywcharles/itinerary/blob/main/app/api/itinerary-review/route.ts): `app/api/itinerary-review/route.ts`
- [Proposal validation](https://github.com/ywcharles/itinerary/blob/main/lib/aiReview.ts): `lib/aiReview.ts`

### Data and integrations

- [Weather endpoint](https://github.com/ywcharles/itinerary/blob/main/app/api/weather/route.ts): `app/api/weather/route.ts`
- [Maps link resolver](https://github.com/ywcharles/itinerary/blob/main/app/api/resolve-maps-link/route.ts): `app/api/resolve-maps-link/route.ts`
- [Supabase client](https://github.com/ywcharles/itinerary/blob/main/lib/supabase.ts): `lib/supabase.ts`
- **Supabase**
- [Route calculation](https://github.com/ywcharles/itinerary/blob/main/lib/routes.ts): `lib/routes.ts`
- [Google Maps APIs](https://github.com/ywcharles/itinerary/blob/main/lib/googleMaps.ts): `lib/googleMaps.ts`

### Other components

- **Traveler**
- **Gemini**
- **Open-Meteo**

## Connections

- Traveler → Landing page: opens
- Landing page → Create trip: offers
- Landing page → Join trip: offers
- Landing page → Recent trips: shows
- Traveler → Create trip: submits trip
- Traveler → Join trip: joins trip
- Itinerary page → Itinerary view: renders
- Itinerary view → Stop state: loads stops
- Itinerary view → Schedule and edits: displays schedule
- Itinerary view → Calendar: displays calendar
- Itinerary view → Map display: displays map
- Stop state → Supabase client: reads and writes
- Supabase client → Supabase: accesses
- Itinerary view → Travel legs: derives legs
- Travel legs → Route calculation: requests routes
- Route calculation → Google Maps APIs: computes routes
- Itinerary view → Day weather: shows forecast
- Day weather → Weather endpoint: requests weather
- Weather endpoint → Open-Meteo: fetches forecast
- Review panel → Review context: collects context
- Review context → Gap discovery: finds gaps
- Review context → Place suggestions: searches places
- Review context → Route calculation: checks travel
- Review panel → Review endpoint: sends review request
- Review endpoint → Supabase: reads stops
- Review endpoint → Gemini: requests proposals
- Review endpoint → Proposal validation: parses and validates
- Review panel → Proposal validation: validates proposals
- Review panel → Supabase client: saves accepted changes
- Maps link resolver → Traveler: returns resolved link