# ryancjc/altas_hackathon architecture

> Architecture diagram of the GitHub repository ryancjc/altas_hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryancjc/altas_hackathon
- Repository: https://github.com/ryancjc/altas_hackathon

## Overview

This repository contains travel-planning components rather than one clearly integrated application: an LLM itinerary agent, a separate detailed itinerary planner, flight and place search tools, and several lodging/travel API clients. The clearest user-to-result flow is the agent: it receives a travel request, invokes flight and place tools, then parses the response into a typed itinerary. The detailed planner documents its own multi-stage itinerary workflow. The README is empty, and the excerpts do not establish how the standalone clients are wired together, so those integrations are left unconnected.

Main entry points: [`itineraryPlanner.py`](https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py) (Detailed planner), [`agent.py`](https://github.com/ryancjc/altas_hackathon/blob/master/agent.py) (Itinerary agent), [`tools.py`](https://github.com/ryancjc/altas_hackathon/blob/master/tools.py) (Agent tools), [`nearbySearch.py`](https://github.com/ryancjc/altas_hackathon/blob/master/nearbySearch.py) (Nearby places)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent and output"]
  node_agent["Itinerary agent<br/>[agent.py]"]
  node_schema["Itinerary schema<br/>[schemas.py]"]
end

subgraph group_itinerary["Itinerary planning"]
  node_itinerary_planner["Detailed planner"]
  node_day_classification["Day classification"]
  node_candidate_discovery["Candidate discovery"]
  node_selection["Place selection"]
  node_daily_schedule["Daily schedule"]
  node_route_matrix["Route matrix"]
end

subgraph group_discovery["Flight and place discovery"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_nearby_search["Nearby places<br/>[nearbySearch.py]"]
  node_text_search["Text places<br/>[textSearch.py]"]
  node_flight_api["Atlas flights"]
  node_route_api["Optimized routes"]
  node_place_types["Place type logic<br/>[placeTypeLogic.py]"]
  node_place_pricing["Place pricing<br/>[getPlacePrice.py]"]
end

subgraph group_lodging["Lodging and travel data"]
  node_duffel["Duffel stays<br/>[duffel_hotel.py]"]
  node_stayapi["StayAPI hotels<br/>[stayapi_hotel.py]"]
  node_hotel_api_a["Hotel search API<br/>[stayAPI.py]"]
  node_hotel_api_b["Hotel search API<br/>[stayAPI2.py]"]
end

node_traveler(("Traveler"))
node_google_places{{"Google Places"}}
node_atlas_service{{"Atlas flight service"}}
node_google_routes{{"Google Routes"}}
node_tripadvisor{{"Tripadvisor"}}
node_duffel_service{{"Duffel service"}}
node_stay_service{{"StayAPI service"}}

node_traveler -->|"requests plan"| node_agent
node_agent -->|"invokes tools"| node_tools
node_agent -->|"structures output"| node_schema
node_itinerary_planner -->|"classifies days"| node_day_classification
node_itinerary_planner -->|"discovers candidates"| node_candidate_discovery
node_itinerary_planner -->|"selects places"| node_selection
node_itinerary_planner -->|"builds schedule"| node_daily_schedule
node_itinerary_planner -->|"computes routes"| node_route_matrix
node_tools -->|"searches places"| node_google_places
node_tools -->|"searches flights"| node_atlas_service
node_nearby_search -->|"nearby query"| node_google_places
node_text_search -->|"text query"| node_google_places
node_flight_api -->|"requests flights"| node_atlas_service
node_route_api -->|"optimizes route"| node_google_routes
node_place_pricing -->|"fetches place data"| node_tripadvisor
node_duffel -->|"searches and books"| node_duffel_service
node_stayapi -->|"requests hotel data"| node_stay_service

click node_agent "https://github.com/ryancjc/altas_hackathon/blob/master/agent.py"
click node_tools "https://github.com/ryancjc/altas_hackathon/blob/master/tools.py"
click node_schema "https://github.com/ryancjc/altas_hackathon/blob/master/schemas.py"
click node_itinerary_planner "https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py"
click node_day_classification "https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py"
click node_candidate_discovery "https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py"
click node_selection "https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py"
click node_daily_schedule "https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py"
click node_route_matrix "https://github.com/ryancjc/altas_hackathon/blob/master/computeRouteMatrix.py"
click node_nearby_search "https://github.com/ryancjc/altas_hackathon/blob/master/nearbySearch.py"
click node_text_search "https://github.com/ryancjc/altas_hackathon/blob/master/textSearch.py"
click node_flight_api "https://github.com/ryancjc/altas_hackathon/blob/master/atlas_flight_api.py"
click node_route_api "https://github.com/ryancjc/altas_hackathon/blob/master/routeAPI_opt_multiple.py"
click node_place_types "https://github.com/ryancjc/altas_hackathon/blob/master/placeTypeLogic.py"
click node_place_pricing "https://github.com/ryancjc/altas_hackathon/blob/master/getPlacePrice.py"
click node_duffel "https://github.com/ryancjc/altas_hackathon/blob/master/duffel_hotel.py"
click node_stayapi "https://github.com/ryancjc/altas_hackathon/blob/master/stayapi_hotel.py"
click node_hotel_api_a "https://github.com/ryancjc/altas_hackathon/blob/master/stayAPI.py"
click node_hotel_api_b "https://github.com/ryancjc/altas_hackathon/blob/master/stayAPI2.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_schema toneBlue
class node_itinerary_planner,node_day_classification,node_candidate_discovery,node_selection,node_daily_schedule,node_route_matrix toneAmber
class node_tools,node_nearby_search,node_text_search,node_flight_api,node_route_api,node_place_types,node_place_pricing,node_google_routes,node_stay_service toneMint
class node_duffel,node_stayapi,node_hotel_api_a,node_hotel_api_b toneRose
class node_traveler,node_google_places,node_atlas_service,node_tripadvisor,node_duffel_service toneIndigo
```

## Components

### Agent and output

- [Itinerary agent](https://github.com/ryancjc/altas_hackathon/blob/master/agent.py): `agent.py`
- [Itinerary schema](https://github.com/ryancjc/altas_hackathon/blob/master/schemas.py): `schemas.py`

### Itinerary planning

- [Detailed planner](https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py): `itineraryPlanner.py`
- [Day classification](https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py): `itineraryPlanner.py`
- [Candidate discovery](https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py): `itineraryPlanner.py`
- [Place selection](https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py): `itineraryPlanner.py`
- [Daily schedule](https://github.com/ryancjc/altas_hackathon/blob/master/itineraryPlanner.py): `itineraryPlanner.py`
- [Route matrix](https://github.com/ryancjc/altas_hackathon/blob/master/computeRouteMatrix.py): `computeRouteMatrix.py`

### Flight and place discovery

- [Agent tools](https://github.com/ryancjc/altas_hackathon/blob/master/tools.py): `tools.py`
- [Nearby places](https://github.com/ryancjc/altas_hackathon/blob/master/nearbySearch.py): `nearbySearch.py`
- [Text places](https://github.com/ryancjc/altas_hackathon/blob/master/textSearch.py): `textSearch.py`
- [Atlas flights](https://github.com/ryancjc/altas_hackathon/blob/master/atlas_flight_api.py): `atlas_flight_api.py`
- [Optimized routes](https://github.com/ryancjc/altas_hackathon/blob/master/routeAPI_opt_multiple.py): `routeAPI_opt_multiple.py`
- [Place type logic](https://github.com/ryancjc/altas_hackathon/blob/master/placeTypeLogic.py): `placeTypeLogic.py`
- [Place pricing](https://github.com/ryancjc/altas_hackathon/blob/master/getPlacePrice.py): `getPlacePrice.py`

### Lodging and travel data

- [Duffel stays](https://github.com/ryancjc/altas_hackathon/blob/master/duffel_hotel.py): `duffel_hotel.py`
- [StayAPI hotels](https://github.com/ryancjc/altas_hackathon/blob/master/stayapi_hotel.py): `stayapi_hotel.py`
- [Hotel search API](https://github.com/ryancjc/altas_hackathon/blob/master/stayAPI.py): `stayAPI.py`
- [Hotel search API](https://github.com/ryancjc/altas_hackathon/blob/master/stayAPI2.py): `stayAPI2.py`

### Other components

- **Traveler**
- **Google Places**
- **Atlas flight service**
- **Google Routes**
- **Tripadvisor**
- **Duffel service**
- **StayAPI service**

## Connections

- Traveler → Itinerary agent: requests plan (evidence: `agent.py`)
- Itinerary agent → Agent tools: invokes tools (evidence: `agent.py`)
- Itinerary agent → Itinerary schema: structures output (evidence: `agent.py`)
- Detailed planner → Day classification: classifies days (evidence: `itineraryPlanner.py`)
- Detailed planner → Candidate discovery: discovers candidates (evidence: `itineraryPlanner.py`)
- Detailed planner → Place selection: selects places (evidence: `itineraryPlanner.py`)
- Detailed planner → Daily schedule: builds schedule (evidence: `itineraryPlanner.py`)
- Detailed planner → Route matrix: computes routes (evidence: `itineraryPlanner.py`)
- Agent tools → Google Places: searches places (evidence: `tools.py`)
- Agent tools → Atlas flight service: searches flights (evidence: `tools.py`)
- Nearby places → Google Places: nearby query (evidence: `nearbySearch.py`)
- Text places → Google Places: text query (evidence: `textSearch.py`)
- Atlas flights → Atlas flight service: requests flights (evidence: `atlas_flight_api.py`)
- Optimized routes → Google Routes: optimizes route (evidence: `routeAPI_opt_multiple.py`)
- Place pricing → Tripadvisor: fetches place data (evidence: `getPlacePrice.py`)
- Duffel stays → Duffel service: searches and books (evidence: `duffel_hotel.py`)
- StayAPI hotels → StayAPI service: requests hotel data (evidence: `stayapi_hotel.py`)
