# Urban Journeys — Full Documentation for LLMs

> Walk your city with intention.

Urban Journeys is a web application that generates themed walking routes through cities. It combines AI creativity with algorithmic route optimization to compose walking journeys that connect interesting places along a theme.

Website: https://urban-journeys.com

---

## How It Works

Urban Journeys uses a 5-phase pipeline to compose walking routes:

1. **Discovery** — Searches for points of interest (POIs) matching selected themes near the starting location using the Google Places API.
2. **Curation** — An LLM selects the most interesting and walkable stops from the discovered candidates.
3. **Optimization** — A TSP (Traveling Salesman Problem) solver orders the stops to minimize total walking distance using nearest-neighbor + 2-opt + or-opt improvements.
4. **Adjustment** — Iteratively adds or removes stops until the route distance is within ±15% of the target.
5. **Narration** — An LLM generates a journey title, description, and per-stop notes that tell the story of the walk.

Progress streams to the user in real time via Server-Sent Events (SSE).

---

## Themes (12 Available)

Each theme maps to specific types of places:

1. **Theater Trail** (🎭) — Performance venues, cinemas, playhouses, comedy clubs
2. **Street Art Tour** (🎨) — Murals, galleries, public art installations, sculpture
3. **Caffeine Crawl** (☕) — Local coffee shops, roasters, espresso bars
4. **Brewery Walk** (🍺) — Craft breweries, taprooms, brewpubs
5. **Bookshop Safari** (📚) — Independent bookstores, used books, libraries
6. **Live Music Venues** (🎵) — Concert halls, jazz clubs, music halls
7. **Parks & Green Spaces** (🌳) — Parks, gardens, botanical areas, trails
8. **Historic Buildings** (🏛️) — Landmarks, monuments, heritage sites
9. **Food Tour** (🍽️) — Local restaurants, bakeries, food spots
10. **Architecture Walk** (🏢) — Notable buildings, skyscrapers, architectural gems
11. **Vintage & Antiques** (🪑) — Antique shops, vintage stores, thrift shops
12. **Markets & Shops** (🛍️) — Farmers markets, flea markets, local shops

Users can select multiple themes to create mixed-theme journeys.

---

## Journey Sizes (6 Presets)

| Size | Duration | Distance | Stops |
|------|----------|----------|-------|
| Quick Walk | 30-45 min | 1-2 miles | 3-4 |
| Short Walk | 1-1.5 hrs | 2-3 miles | 4-6 |
| Good Walk | 2-2.5 hrs | 4-5 miles | 6-8 |
| Long Walk | 3-4 hrs | 6-8 miles | 8-10 |
| Half Day | 4-5 hrs | 8-10 miles | 10-12 |
| Epic Trek | 5+ hrs | 10+ miles | 12+ |

---

## Route Types

- **Loop routes** — Start and end at the same location. The route forms a circuit.
- **Point-to-point routes** — Start at one location and end at the final stop. Does not return to start.

---

## Export Formats

- **GPX** — Download a GPX file for use with hiking/GPS apps (Gaia GPS, AllTrails, etc.)
- **Google Maps** — Open the route in Google Maps with waypoints for turn-by-turn walking directions
- **Apple Maps** — Open the route in Apple Maps with waypoints

---

## Features by Tier

### Free Tier
- 3 journey compositions per month (resets each calendar month)
- All 12 themes available
- GPX, Google Maps, Apple Maps export
- Save up to 5 journeys
- Interactive map with walking path visualization

### Premium ($7/month or $60/year)
- Unlimited journey compositions
- Unlimited saved journeys
- Share journeys via public link
- Early access to new cities and themes
- All Free tier features included

---

## Journey Data Structure

A composed journey includes:

- **Title** — AI-generated descriptive title
- **Description** — Narrative overview of the walk
- **Stops** — Ordered list, each with:
  - Name
  - Address
  - Latitude/Longitude
  - Per-stop notes (AI-generated context about why this stop is interesting)
  - Associated themes
- **Route geometry** — Walking path as a GeoJSON LineString
- **Distance** — Total walking distance in miles/km
- **Duration** — Estimated walking time (excludes time spent at stops)
- **Themes** — List of selected themes
- **Route type** — Loop or point-to-point

---

## Public Journeys

Users can share journeys by making them public. Public journeys are:
- Accessible via a unique URL: `https://urban-journeys.com/journey/{slug}`
- Indexed in the sitemap
- Include OpenGraph and Twitter Card meta tags for social sharing
- Include Schema.org TouristTrip structured data
- Viewable by anyone without authentication

## Browsing by City

Public journeys are also browsable by location:
- `https://urban-journeys.com/walks` — every city with at least one public walking tour
- `https://urban-journeys.com/walks/{city}` — all public walks in that city (e.g. `/walks/denver`)
- `https://urban-journeys.com/walks/{city}/{neighborhood}` — a curated neighborhood-scoped subset where one exists (e.g. `/walks/denver/rino` for the RiNo Art District)
- Each page includes Schema.org CollectionPage + ItemList structured data listing every walk on it

---

## Technical Stack

- Next.js 15 (React 19, TypeScript)
- Mapbox GL JS for interactive maps
- Supabase (PostgreSQL + PostGIS) for data storage
- Stripe for payments
- Deployed on Render

---

## Contact

Built by Skylark Creations.
Website: https://urban-journeys.com