Flights/ROUTE_EXPLORER_GUIDE.md

# Route Explorer Features — Implementation Guide

How "Find Connections" and "Where can I go?" are wired up in the Flights iOS app, end-to-end. Pick this up cold and you should be able to find the right file in 30 seconds.

For the **upstream API surface** (route-explorer.com proxy endpoints, request/response shapes, captured fixtures), see `api_docs/route_explorer_api.md`. This doc is the *app side* — how we consume it.

---

## What these features do

### Find Connections (`RoutePlannerView`)
Origin → destination, one date. Returns direct *and* multi-stop itineraries (up to 2 stops) in a single API call. Each itinerary is a complete chain of legs with valid layover times, full per-leg seat/equipment data, and a `score` from the upstream ranking. User flow:

1. Tap "Find Connections" on the home screen.
2. Pick origin (IATA picker), pick destination, pick date.
3. Choose **Max Stops** (Direct / 1 / 2) and **Sort By** (Departure / Duration). Optional: "Interline carriers only".
4. Tap "Search Routes" → list of `ConnectionRow` cards.
5. Tap any leg in any itinerary → opens the existing `FlightLoadDetailView` for that flight, which calls into `AirlineLoadService` to pull live load if the carrier is supported.

### Where can I go? (`WhereToGoView`)
Pick an airport, see every flight leaving in the next N hours. Useful for non-rev "what's about to leave" planning. User flow:

1. Tap "Where can I go?" on the home screen.
2. Pick airport.
3. Pick **window** (2/4/6/12/24h) and starting time (defaults to now; "Now" button resets).
4. Tap "Where can I go?" → list of departure cards sorted by departure time, color-coded countdown ("in 23m" red / "in 1h 15m" yellow / further out grey), capacity pills (F / J / W / Y).
5. Tap any flight → load detail (same as Find Connections).

Cross-midnight windows are handled by firing two `/departures` calls (today + tomorrow) and merging.

---

## File layout

```
Flights/
├── Models/
│   └── RouteExplorerModels.swift       # Codable types + bridge helpers + custom JSON decoder
├── Services/
│   └── RouteExplorerClient.swift       # actor: token cache + flight-search proxy
└── Views/
    ├── RoutePlannerView.swift          # feature (a)
    ├── WhereToGoView.swift             # feature (b)
    └── Components/
        ├── IATAAirportPicker.swift     # local-only IATA autocomplete
        └── ConnectionRow.swift         # itinerary card with chained legs
```

Wired in:
- `FlightsApp.swift` — instantiates `RouteExplorerClient` once, passes through.
- `ContentView.swift` — adds `SearchRoute.routePlanner` / `.whereToGo` cases plus two entry-point cards above the favorites list.

---

## RouteExplorerClient

Actor (so concurrent searches share the token cache safely). Two public methods:

```swift
func searchRoutes(
    from origin: String,        // IATA, e.g. "DFW"
    to destination: String,     // IATA, e.g. "MCO"
    date: Date,
    maxStops: Int = 1,          // 0 = direct only, 1 = 1-stop, 2 = 2-stop
    includeInterline: Bool = false,
    sortBy: RouteSortOption = .departureTime,
    limit: Int = 100
) async throws -> RouteSearchResult

func searchDepartures(
    from origin: String,
    date: Date,
    maxStops: Int = 0,
    limit: Int = 200
) async throws -> RouteSearchResult
```

Returns `RouteSearchResult { connections: [RouteConnection], appendix: RouteAppendix? }`. Each connection has `flights: [RouteFlight]` (one for direct, more for multi-stop), plus `durationMinutes`, `score`, `totalLayoverMinutes`, `carrierIatas`.

### Auth flow

Anonymous HMAC token from `https://route-explorer.com/api/token`, IP-rate-limited at **10/min**. Cached for 30 minutes (defensive — actual TTL not measured). On HTTP 401/403 from the search endpoint, the cache is dropped and the call retries once.

### Browser-shaped headers (important)

`/api/token` and `/api/flight-search` are gated by `Origin` / `Referer` checks in production. We send these on every request:

```
User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 ...)
Accept-Language: en-US,en;q=0.9
Referer: https://route-explorer.com/
Origin: https://route-explorer.com
```

Without them iOS gets 403. Same trick is used for United in `AirlineLoadService.applyUnitedBrowserHeaders`.

### Error surface

```swift
RouteExplorerClient.ClientError {
    case tokenFetchFailed(status: Int)
    case requestFailed(status: Int, body: String?)
    case decodingFailed(underlying: Error)
}
```

All cases conform to `LocalizedError`. The views show `errorDescription` directly in a `ContentUnavailableView`.

### Date handling

Upstream returns ISO-8601 timestamps with offsets (e.g. `"2026-04-28T16:45:00-05:00"`). We use a custom decoder factory `JSONDecoder.routeExplorer()` that handles both `withFractionalSeconds` and plain `withInternetDateTime`. Date params (`startDate`, `endDate`, `departureDates`) go up as `"yyyy-MM-dd"` formatted in UTC for stability.

---

## The bridge to FlightLoadDetailView

Tap-through is the key UX coupling. `RouteFlight.toFlightSchedule(appendix:on:)` synthesizes a `FlightSchedule` from a route-explorer leg so the existing detail view doesn't need to know anything about route-explorer.

```swift
// In a tap handler:
selectedDepCode = leg.departure.airportIata
selectedArrCode = leg.arrival.airportIata
selectedDate = leg.departure.dateTime
selectedFlight = leg.toFlightSchedule(appendix: appendix, on: leg.departure.dateTime)
```

Then `.sheet(item: $selectedFlight) { ... FlightLoadDetailView(...) }` and the existing flow runs unchanged. `FlightLoadDetailView` calls `AirlineLoadService.fetchLoad(airlineCode:flightNumber:date:origin:destination:departureTime:)`, which:

- Routes to a per-airline fetcher for **UA, AA, NK, KE, B6, AS, EK, XE**
- Returns `nil` for unsupported carriers → the detail view shows "Load data not available for {airline name}" (intentional graceful degrade — the user still sees the schedule/equipment/seat capacity from route-explorer)

The `appendix` from `/route` and `/departures` (we always pass `includeAppendix: true`) supplies the airline display name and the equipment friendly name. Without it the detail view falls back to IATA codes.

### Logo limitation

Synthesized `Airline.logoFilename = "\(iata.lowercased()).png"`. Most route-explorer carriers won't have a matching file in the FlightConnections CDN, so `AsyncImage` drops to its placeholder (colored circle with first letter). This is fine but noticeable — the regular FlightConnections-sourced search shows real logos. Two ways to upgrade if it bothers you:

1. Pull logos from `images.stafftraveler.com` (in the route-explorer CSP allowlist) — would need a separate filename convention.
2. Bundle a static `Resources/airlines.json` mapping IATA → FC logo filename, look it up at synthesis time.

---

## RoutePlannerView (Find Connections)

Renders three configuration sections (airports / date / stops+sort+interline), a search button, then a list of `ConnectionRow` cards. State:

```swift
@State origin: MapAirport?
@State destination: MapAirport?
@State date: Date
@State maxStops: Int = 1
@State sortBy: RouteSortOption = .departureTime
@State includeInterline: Bool = false

@State isLoading: Bool
@State error: String?
@State connections: [RouteConnection]
@State appendix: RouteAppendix?
```

Search button is disabled until both airports are picked. On submit, calls `client.searchRoutes(...)` and stores `connections` + `appendix`. Empty results render a "No routes found from X to Y" `ContentUnavailableView`.

### ConnectionRow

One card per itinerary, top-level shows:
- Stops badge ("Direct" / "1 stop" / "2 stops")
- Carrier names (single carrier shown by full name, multi-carrier as IATA list)
- Total duration ("4h 23m")

Then per-leg `LegSummary` rows separated by layover indicators ("Layover at SEA · 1h 12m"). Each leg is its own `Button` so the per-leg tap doesn't conflict with any future expand-row UX.

---

## WhereToGoView (Where can I go?)

Renders an airport picker, window selector, time anchor (date+time picker with "Now" button), search button, then departure cards. State:

```swift
@State origin: MapAirport?
@State windowHours: Int = 6
@State referenceDate: Date    // "starting from"

@State connections: [RouteConnection]   // each is one single leg
@State appendix: RouteAppendix?
```

`/departures` with `maxStops: 0` returns one connection per single-leg flight. We flatten and filter:

```swift
private var filteredFlights: [RouteFlight] {
    let windowEnd = referenceDate.addingTimeInterval(TimeInterval(windowHours * 3600))
    return connections.flatMap { $0.flights }
        .filter { $0.departure.dateTime >= referenceDate
               && $0.departure.dateTime <= windowEnd }
        .sorted { $0.departure.dateTime < $1.departure.dateTime }
}
```

Cross-midnight: if `referenceDate` and `windowEnd` are different calendar days, fire a second `/departures` for the next day and merge.

### DepartureLegRow

Per-flight card with:
- Carrier IATA + flight number, airline name
- Local departure time + relative countdown ("in 23m") with traffic-light color
- IATA codes as big airport-signage text + tiny airplane icon between
- Aircraft pill
- Capacity pills (F·12, J·20, W·0, Y·176) — only shown for cabins with seats

---

## Known limitations / risks

1. **Tenancy on route-explorer.com.** The whole feature relies on StaffTraveler's free public proxy. They could flip a referer/origin check we don't satisfy, rotate the HMAC scheme, or just rate-limit harder at any time. No SLA. For load-bearing personal use this is fine; for shipped users you'd want a fallback or a paid `api.stafftraveler.com` integration.

2. **Rate limit (10/min per IP).** Hitting search rapidly (e.g. user retries) can get you 429-ish. The token cache softens this since `/api/token` is the rate-limited bit; subsequent `/api/flight-search` calls reuse the cached token.

3. **Schedule, not loads.** Capacity pills show *seat layout* (e.g. 196 total, 20 J / 176 Y), not *available* seats. Live load requires the per-airline fetchers in `AirlineLoadService` and is only available for the 8 supported carriers. For unsupported carriers, the detail view degrades to schedule-only.

4. **No test target in the project.** None of this code has unit tests. The pieces worth testing (date decoder, layover math, `toFlightSchedule` bridge, `RouteCabins.asCabinClass`) all have JSON fixtures saved at `api_docs/route_explorer_captures/*.json` ready for use.

5. **Time-zone display.** Leg times are formatted using device local time, not the airport's local time. For most users browsing their own region this looks correct; for cross-timezone planning the times will display in the user's zone. Fix would require an IATA → IANA timezone map.

6. **Single date per call.** `departureDates` accepts an array but we only ever pass one date. For "any of next 3 days" you'd fire N parallel calls and merge in the view layer (or extend the client API to accept multiple dates).

---

## Adding a new feature to this surface

### A new sort order

Add a case to `RouteSortOption` (in `RouteExplorerModels.swift`):
```swift
enum RouteSortOption: String, CaseIterable, Sendable {
    case departureTime = "departure_time"
    case duration = "duration"
    case score = "score"            // ← upstream supports this; not yet exposed
    ...
    var label: String { ... }       // user-facing label
}
```
The picker in `RoutePlannerView` iterates `allCases` so it auto-shows up.

### A new airline supported by load lookup

Add a case to the `switch code` block in `AirlineLoadService.fetchLoad(...)`. Because both new views funnel through `FlightLoadDetailView`, a new airline immediately becomes tap-functional in both. Document the wire details in `AIRLINE_INTEGRATION_GUIDE.md`.

### A new upstream endpoint

The upstream proxy allowlist is `/route, /route-batch, /flight, /departures, /schedule`. To call e.g. `/schedule`:

```swift
func searchSchedule(carrier: String, flightNumber: Int, start: Date, end: Date) async throws -> RouteSearchResult {
    let payload: [String: Any] = [
        "carrierCode": carrier,
        "flightNumber": flightNumber,
        "startDate": dateFormatter.string(from: start),
        "endDate": dateFormatter.string(from: end),
        "limit": 1000,
        "includeAppendix": true
    ]
    return try await callFlightSearch(endpoint: "/schedule", json: payload)
}
```

The decoder already handles the response shape (same `connections[]` envelope across all endpoints).

### A real-airport timezone display

Bundle a IATA→IANA map (e.g. from the `airports.json` already in the bundle if it has TZ data — check first). Update `RouteFlight.toFlightSchedule` and `DepartureLegRow.timeFormatter` to use a `TimeZone(identifier: ...)` keyed off the airport's IATA.

---

## Quick smoke test (manual)

1. Run app in simulator.
2. Home → "Find Connections" → DFW → KOA → date a few days out → 1 stop → Search. Expect: a few `DFW→SEA→KOA` (Alaska) and `DFW→LAX→KOA` (American) itineraries, with valid layovers visible between legs.
3. Tap any leg. Expect: load detail view loads. For AA / AS legs, you'll see real load data; for others you'll see schedule + the "Load data not available" state.
4. Back. Home → "Where can I go?" → DFW → 6h → Now → Search. Expect: dozens of departures sorted by time, with red/yellow/grey countdowns and capacity pills.
5. Open Xcode console. On any failure look for `[RouteExplorer] /api/token failed status=...` — that's the diagnostic line we added; the body usually explains what the proxy didn't like.

---

## Pointer to upstream documentation

`api_docs/route_explorer_api.md` — full endpoint reference including:
- The `{json:{...}}` SuperJSON envelope
- Required fields per endpoint (from server-side Zod validation errors)
- Real captured request/response samples in `api_docs/route_explorer_captures/`
- Notes on `/route-batch` (not used; not fully reverse-engineered)

The captures (`route_DFW_KOA_1stop.json` etc.) double as test fixtures whenever the test target gets added.