task.md

Task Breakdown

Three team members, four components. The split below keeps frontend work on one person and pairs the two API-integration backend components together, leaving the scraping-heavy wait-time component as its own track.

At a glance

Person	Owns	Components
Person A	Frontend + integration glue	Component 1
Person B	Location & flight APIs	Components 2 + 3
Person C	CBP wait-time scraper	Component 4

All three meet early to agree on the shared data contract (see bottom of this file) before writing real code. Once the contract is locked, each track can progress independently.

---

Person A — Frontend (Component 1)

Goal: Build the Web UI that collects user input, calls the backend, and displays the result.

Tasks

1. Scaffold the frontend project (React + Vite, or plain HTML/CSS/JS — team's choice).
2. Build the input form with fields for:
   • Current address (text input, ideally with autocomplete — Google Places or Mapbox Geocoding)
   • Destination airport (dropdown of major airports, or IATA code input)
   • Flight number or manual ETA (let the user choose)
3. Build the results view that displays:
   • A map showing the route from user's address to the airport (embedded map widget)
   • A time badge over the airport showing the expected passenger exit delay (from Component 4)
   • A prominent "Leave by HH:MM" recommendation
4. Wire up the backend calls. Hit Person B's and Person C's endpoints (or import their functions if running in one process) and combine the results using the formula in AGENTS.md.
5. Add loading + error states for each backend call so the demo doesn't hang on a flaky API.
6. Polish for the demo: basic styling, mobile-friendly layout, a sensible default city/airport so judges can see output immediately.

Stretch

• Live-refresh the recommendation every minute so it stays accurate while the user watches.
• Show a second suggestion: "if you leave now, you'll arrive X minutes before pickup."

---

Person B — Drive time & flight ETA (Components 2 + 3)

Goal: Provide two backend functions — one that returns driving time, one that returns a flight's landing ETA.

Tasks

1. Pick and sign up for APIs. Evaluate:
   • Drive time: Google Maps Distance Matrix, Mapbox Directions, or OpenRouteService
   • Flight data: AviationStack, FlightAware AeroAPI, or OpenSky Network Get free-tier keys and store them in a local .env file (do not commit).
2. Component 2 — drive-time module:
   • Input: origin address string, airport IATA code (or airport address)
   • Output: estimated drive time in minutes, accounting for current traffic if the API supports it
   • Return a small JSON object matching the shared contract below.
3. Component 3 — flight ETA module:
   • Input: flight number (e.g. AA123)
   • Output: scheduled landing time, actual/estimated landing time, arrival airport, status
   • Normalize all times to UTC internally.
4. Expose both as HTTP endpoints (Flask/FastAPI/Express) OR as importable Python/JS functions, depending on how the team wants to integrate with the frontend. Coordinate with Person A.
5. Write a tiny smoke-test script that calls both modules with a sample input and prints the result — Person A will use this to verify the contract.

Stretch

• Cache recent flight lookups so you don't burn quota during demo practice.
• Handle the "flight number not found" and "flight already landed" cases gracefully.

---

Person C — Passenger wait time (Component 4)

Goal: Given an airport and an arrival time, estimate how long it will take the passenger to go from wheels-down to curbside.

Tasks

1. Study the CBP data source at https://awt.cbp.gov/. Figure out:
   • How their HTML page is structured (what table holds the wait times?)
   • What airports are covered and what data is exposed (per-hour historical averages, terminal-level breakdowns, etc.)
   • Whether there's a hidden JSON endpoint behind the page (inspect Network tab — often easier than scraping HTML).
2. Build the scraper. Python + requests + BeautifulSoup, or Node + cheerio. Output: structured data (airport, terminal, hour of day, day of week, average wait minutes).
3. Cache the scraped data locally. Don't hit CBP on every frontend request — scrape once at startup (or on a schedule) and keep the data in memory or a JSON file.
4. Build the estimator function.
   • Input: airport IATA code, arrival timestamp (UTC)
   • Output: estimated minutes from landing to curb, based on historical averages for that airport + hour + weekday
   • Add a reasonable buffer for non-CBP delay (baggage claim, walking) — document the assumption.
5. Expose it the same way as Person B's components (endpoint or importable function) so the frontend can call it uniformly.

Stretch

• Distinguish domestic vs. international arrivals (CBP data mostly covers international).
• Add a confidence range (min/max wait), not just a point estimate.

---

Shared data contract — agree on this first

All three tracks should exchange JSON shapes like these. Lock these down in the first working session so nobody blocks on anyone else.

// Component 2: drive time
{
  "origin": "1234 Main St, Seattle, WA",
  "destination_airport": "SEA",
  "drive_minutes": 38,
  "drive_minutes_with_traffic": 47
}

// Component 3: flight ETA
{
  "flight_number": "AS123",
  "arrival_airport": "SEA",
  "scheduled_arrival_utc": "2026-04-24T23:45:00Z",
  "estimated_arrival_utc": "2026-04-24T23:52:00Z",
  "status": "en_route"
}

// Component 4: passenger wait time
{
  "airport": "SEA",
  "arrival_utc": "2026-04-24T23:52:00Z",
  "estimated_exit_minutes": 35
}

// Component 1 assembles the final recommendation
{
  "leave_by_local": "2026-04-24T15:40:00-07:00",
  "reasoning": "flight lands at 16:52 local, ~35 min to exit, ~47 min drive, 10 min buffer"
}

---

Timeline suggestion (adjust to hackathon length)

1. Hour 0–1: Team meets, picks stack, signs up for APIs, locks shared contract.
2. Hour 1–4: Each person builds their track in parallel against mock data.
3. Hour 4–6: Integration — Person A wires real backend calls into the UI.
4. Hour 6–end: Polish, handle errors, practice the demo.