README.md

---
title: Tripplanner Backend
emoji: ✈️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# Tripplanner

A travel-benefits stacking app that finds dates where your credit card perks align — so you can book trips that squeeze maximum value out of every benefit you already have.

## What It Does

Tripplanner searches for windows where three high-value perks overlap:

- **Delta companion certificate** (Delta Reserve Amex) — a second ticket at taxes only
- **IHG 4th-night-free** (IHG Premier Mastercard) — book 4 nights on points, pay for 3
- **Resy dining credits** (Delta Reserve Amex) — up to $20/month at Resy restaurants

When all three line up on the same trip — same destination, same travel dates — you get flights, hotel, and dinner at a fraction of the normal cost. Tripplanner does the calendar math and site-checking so you don't have to do it manually.

## Architecture

```
Browser (React + Vite)
        |
        v
FastAPI backend  ←→  Orchestrator agent (claude-sonnet-4-6)
                              |
              ┌───────────────┼───────────────┐
              v               v               v
     Delta subagent    IHG subagent    Resy subagent
   (claude-haiku-4-5) (claude-haiku-4-5) (claude-haiku-4-5)
     + Playwright        + Playwright      + Playwright
```

The orchestrator fans out to three browser subagents that run in parallel. Each subagent gets a fresh AI context and its own Playwright browser instance. They navigate their assigned site, extract availability and pricing data, then return structured results to the orchestrator, which finds overlapping date windows and ranks them.

## Cards Supported

| Card | Benefit Used |
|------|-------------|
| Delta Reserve Amex | Companion certificate (domestic main cabin or first) |
| Delta Reserve Amex | Resy dining credit ($20/month) |
| Delta Reserve Amex | Delta Stays credit |
| IHG Premier Mastercard | 4th night free on points redemptions |

## Prerequisites

- Python 3.11+
- Node 18+
- An [Anthropic API key](https://console.anthropic.com/)

## Setup

### 1. Clone the repo

```bash
git clone <repo-url>
cd "Trip finder with claude"
```

### 2. Install Python dependencies

```bash
cd backend
pip install -r requirements.txt
```

### 3. Install Playwright browser

```bash
playwright install chromium
```

### 4. Configure environment variables

```bash
cp .env.example .env
```

Open `.env` and fill in your Anthropic API key:

```
ANTHROPIC_API_KEY=sk-ant-...
```

### 5. Start the backend

```bash
python -m uvicorn backend.main:app --reload
```

### 6. Start the frontend

In a second terminal:

```bash
cd frontend
npm install
npm run dev
```

### 7. Open the app

Navigate to [http://localhost:5173](http://localhost:5173).

### 8. First run: set up browser sessions

**You only need to do this once.**

On first launch, click **"Setup Browser Sessions"**. A Chromium window will open. Log in to each of the three sites in that window:

1. [delta.com](https://www.delta.com) — sign in to your SkyMiles account
2. [ihg.com](https://www.ihg.com) — sign in to your IHG One Rewards account
3. [resy.com](https://resy.com) — sign in to your Resy account

Once you're logged in to all three, close the setup window and return to the app. Sessions are saved to disk in `browser_data/` and reused on every subsequent run. You won't be prompted again unless the sessions expire.

## How It Works

1. You enter a destination, travel window, and trip length in the UI.
2. The FastAPI backend spins up an orchestrator agent.
3. The orchestrator launches three subagents in parallel — one per site.
4. Each subagent opens a Playwright browser using your saved session, navigates to the relevant search page, and extracts available dates, award availability, and pricing.
5. The orchestrator collects results, finds date ranges where Delta companion availability, IHG 4th-night-free award space, and Resy restaurant options all overlap in the destination city.
6. Ranked results appear in the UI, showing estimated cash value of the stacked benefits for each date window.

## Privacy

No credentials are stored by the app. Playwright authenticates using your browser's own saved session cookies (written to `browser_data/`, which is git-ignored). Your username and password never pass through the app.

## Troubleshooting

- **Session expired**: if a subagent reports it can't access your account, click "Setup Browser Sessions" again and re-log in to the affected site.
- **Port conflict**: the backend defaults to `8000` and the frontend to `5173`. Set `PORT` in `.env` to override the backend port.
- **Slow first search**: the three Playwright browsers launch cold on the first query. Subsequent searches reuse warm sessions and are faster.