Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (46 loc) · 3.36 KB

AGENTS.md

File metadata and controls

65 lines (46 loc) · 3.36 KB
Raw

AGENTS.md

Guidance for AI coding agents working in this repository.

Project overview

Goal: Help a traveler picking someone up from the airport figure out the optimal time to leave home. The app combines driving time, flight ETA, and airport exit/wait time into a single "leave by" recommendation.

Formula (conceptual):

leave_at = flight_landing_eta + passenger_exit_delay - drive_time_from_user_to_airport - buffer

Architecture

Four components, split across frontend and backend:

# Component Role Inputs Outputs
1 Web UI User-facing form + results view user address, airport, flight # or ETA renders map, delay badge, leave-by time
2 Map distance calculator Drive-time estimator origin address, airport minutes to drive
3 Flight landing calculator Flight ETA lookup flight number landing timestamp
4 Passenger wait time calculator Exit delay estimator airport code, arrival time minutes from landing to curb

Components 2, 3, and 4 run independently and feed their results into Component 1.

Suggested tech stack

Pick whichever the team is most comfortable with — these are defaults, not mandates:

  • Frontend: React + Vite, or plain HTML/CSS/JS. Map via Google Maps Embed API, Mapbox GL, or Leaflet + OpenStreetMap.
  • Backend: Python (Flask or FastAPI) or Node.js (Express). A single script file is fine for a hackathon.
  • APIs to evaluate:
    • Drive time: Google Maps Distance Matrix API, Mapbox Directions API, or OpenRouteService (free tier).
    • Flight data: AviationStack, FlightAware AeroAPI, or OpenSky Network (free).
    • Wait time: scrape https://awt.cbp.gov/ directly (HTML table); no official API.

Repository conventions

  • Keep the root clean. Put frontend code under frontend/, backend under backend/.
  • Secrets (API keys) go in a local .env file — never commit them. Add .env to .gitignore before committing any code that reads it.
  • Each backend component should be callable on its own (a function or small module) so the three team members can work in parallel without blocking each other.
  • Define a shared data contract early (see task.md) so frontend and backend agree on JSON shapes before either side is written.

Working agreements for agents

  • Small, focused PRs. One component per branch when possible.
  • Don't invent API keys or endpoints. If a service requires credentials, stop and ask the human to provide them rather than hardcoding placeholders that will silently fail.
  • Mock before integrating. If Component 3's flight API isn't wired up yet, Component 1 should accept a user-provided ETA so the UI can be built and demoed independently.
  • Handle failure visibly. Hackathon demos fall over on bad network calls — surface errors in the UI rather than hanging.
  • Timezones matter. Flight APIs return UTC; the user's drive time is local. Pick one internal representation (UTC recommended) and convert only at display boundaries.

Running the project

To be filled in once the stack is chosen. At minimum this section should document:

  • How to install dependencies
  • How to set API keys
  • How to start the frontend and backend locally
  • How to run any tests

Reference

  • US CBP airport wait times: https://awt.cbp.gov/
  • Original idea and component breakdown: README.md
  • Team task split: task.md