# trevorphix001/travelmate architecture

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

- Interactive diagram: https://gitdiagram.com/trevorphix001/travelmate
- Repository: https://github.com/trevorphix001/travelmate

## Overview

TravelMate AI converts a trip request into a cited, budget-checked, map-ready itinerary. The browser submits requests to the API, which uses a LangGraph workflow for extraction, location resolution, research, weather and transport enrichment, day scheduling, budget adjustment, and validation. Plans can also be edited and saved. The README documents the workflow and its major capabilities; the graph wiring is supported by the sampled graph builder, while some agent internals are unsampled, so those relationships are shown only where documented or indexed.

Main entry points: [`app/graph/build.py`](https://github.com/trevorphix001/travelmate/blob/main/app/graph/build.py) (Workflow graph), [`app/api/plans.py`](https://github.com/trevorphix001/travelmate/blob/main/app/api/plans.py) (Plans API), [`app/agents/itinerary.py`](https://github.com/trevorphix001/travelmate/blob/main/app/agents/itinerary.py) (Day scheduling), [`web/js/app.js`](https://github.com/trevorphix001/travelmate/blob/main/web/js/app.js) (Browser app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Browser app<br/>[app.js]"]
  node_plan_view["Plan view<br/>[plan.js]"]
end

subgraph group_service["API and workflow"]
  node_api["Plans API<br/>[plans.py]"]
  node_graph["Workflow graph<br/>[build.py]"]
  node_state["Workflow state<br/>[state.py]"]
end

subgraph group_planning["Trip planning"]
  node_supervisor["Request extraction<br/>[supervisor.py]"]
  node_geo["Place resolution<br/>[geo_node.py]"]
  node_research["Attraction research<br/>[research.py]"]
  node_weather_agent["Weather enrichment<br/>[weather_node.py]"]
  node_transport["Transport options<br/>[transport.py]"]
  node_itinerary["Day scheduling<br/>[itinerary.py]"]
  node_budget["Budget adjustment<br/>[budget.py]"]
  node_aggregator["Plan validation<br/>[aggregator.py]"]
  node_editor["Plan editor<br/>[editor.py]"]
  node_schemas["Plan data models<br/>[plan.py]"]
end

subgraph group_sources["Data sources"]
  node_places["Place discovery<br/>[attractions.py]"]
  node_routing["Road routing<br/>[routing.py]"]
  node_weather["Weather data<br/>[weather.py]"]
end

subgraph group_platform["Shared services"]
  node_llm["Structured LLM client<br/>[client.py]"]
  node_cache["External-call cache<br/>[cache.py]"]
  node_repo["Data repository<br/>[repo.py]"]
  node_database[("Postgres<br/>[pool.py]")]
end

node_traveler(("Traveler"))

node_traveler -->|"enters trip request"| node_web
node_web -->|"submits plan request"| node_api
node_api -.->|"runs planning workflow"| node_graph
node_graph -->|"dispatches"| node_supervisor
node_graph -->|"dispatches"| node_geo
node_graph -->|"dispatches"| node_research
node_graph -->|"dispatches"| node_weather_agent
node_graph -->|"dispatches"| node_transport
node_graph -->|"dispatches"| node_itinerary
node_graph -->|"dispatches"| node_budget
node_graph -->|"dispatches"| node_aggregator
node_graph -->|"uses state"| node_state
node_supervisor -->|"extracts request"| node_llm
node_research -->|"gathers candidates"| node_places
node_research -->|"ranks candidate IDs"| node_llm
node_itinerary -->|"assigns days"| node_llm
node_itinerary -->|"computes travel legs"| node_routing
node_budget -->|"requests replanning"| node_itinerary
node_aggregator -->|"validates plan"| node_schemas
node_itinerary -->|"builds day plans"| node_schemas
node_weather_agent -.->|"fetches forecasts"| node_weather
node_transport -.->|"gets route estimates"| node_routing
node_llm -->|"caches responses"| node_cache
node_cache -->|"reads and writes cache"| node_repo
node_repo -->|"executes SQL"| node_database
node_api -->|"edits saved plans"| node_editor
node_api -->|"saves and loads plans"| node_repo
node_web -->|"renders itinerary"| node_plan_view
node_api -.->|"returns plan data"| node_web

click node_web "https://github.com/trevorphix001/travelmate/blob/main/web/js/app.js"
click node_plan_view "https://github.com/trevorphix001/travelmate/blob/main/web/js/views/plan.js"
click node_api "https://github.com/trevorphix001/travelmate/blob/main/app/api/plans.py"
click node_graph "https://github.com/trevorphix001/travelmate/blob/main/app/graph/build.py"
click node_state "https://github.com/trevorphix001/travelmate/blob/main/app/graph/state.py"
click node_supervisor "https://github.com/trevorphix001/travelmate/blob/main/app/agents/supervisor.py"
click node_geo "https://github.com/trevorphix001/travelmate/blob/main/app/agents/geo_node.py"
click node_research "https://github.com/trevorphix001/travelmate/blob/main/app/agents/research.py"
click node_weather_agent "https://github.com/trevorphix001/travelmate/blob/main/app/agents/weather_node.py"
click node_transport "https://github.com/trevorphix001/travelmate/blob/main/app/agents/transport.py"
click node_itinerary "https://github.com/trevorphix001/travelmate/blob/main/app/agents/itinerary.py"
click node_budget "https://github.com/trevorphix001/travelmate/blob/main/app/agents/budget.py"
click node_aggregator "https://github.com/trevorphix001/travelmate/blob/main/app/agents/aggregator.py"
click node_editor "https://github.com/trevorphix001/travelmate/blob/main/app/agents/editor.py"
click node_schemas "https://github.com/trevorphix001/travelmate/blob/main/app/schemas/plan.py"
click node_places "https://github.com/trevorphix001/travelmate/blob/main/app/tools/attractions.py"
click node_routing "https://github.com/trevorphix001/travelmate/blob/main/app/tools/routing.py"
click node_weather "https://github.com/trevorphix001/travelmate/blob/main/app/tools/weather.py"
click node_llm "https://github.com/trevorphix001/travelmate/blob/main/app/llm/client.py"
click node_cache "https://github.com/trevorphix001/travelmate/blob/main/app/core/cache.py"
click node_repo "https://github.com/trevorphix001/travelmate/blob/main/app/db/repo.py"
click node_database "https://github.com/trevorphix001/travelmate/blob/main/app/db/pool.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_web,node_plan_view toneBlue
class node_api,node_graph,node_state toneAmber
class node_supervisor,node_geo,node_research,node_weather_agent,node_transport,node_itinerary,node_budget,node_aggregator,node_editor,node_schemas toneMint
class node_places,node_routing,node_weather toneRose
class node_llm,node_cache,node_repo,node_database,node_traveler toneIndigo
```

## Components

### Web client

- [Browser app](https://github.com/trevorphix001/travelmate/blob/main/web/js/app.js): `web/js/app.js`
- [Plan view](https://github.com/trevorphix001/travelmate/blob/main/web/js/views/plan.js): `web/js/views/plan.js`

### API and workflow

- [Plans API](https://github.com/trevorphix001/travelmate/blob/main/app/api/plans.py): `app/api/plans.py`
- [Workflow graph](https://github.com/trevorphix001/travelmate/blob/main/app/graph/build.py): `app/graph/build.py`
- [Workflow state](https://github.com/trevorphix001/travelmate/blob/main/app/graph/state.py): `app/graph/state.py`

### Trip planning

- [Request extraction](https://github.com/trevorphix001/travelmate/blob/main/app/agents/supervisor.py): `app/agents/supervisor.py`
- [Place resolution](https://github.com/trevorphix001/travelmate/blob/main/app/agents/geo_node.py): `app/agents/geo_node.py`
- [Attraction research](https://github.com/trevorphix001/travelmate/blob/main/app/agents/research.py): `app/agents/research.py`
- [Weather enrichment](https://github.com/trevorphix001/travelmate/blob/main/app/agents/weather_node.py): `app/agents/weather_node.py`
- [Transport options](https://github.com/trevorphix001/travelmate/blob/main/app/agents/transport.py): `app/agents/transport.py`
- [Day scheduling](https://github.com/trevorphix001/travelmate/blob/main/app/agents/itinerary.py): `app/agents/itinerary.py`
- [Budget adjustment](https://github.com/trevorphix001/travelmate/blob/main/app/agents/budget.py): `app/agents/budget.py`
- [Plan validation](https://github.com/trevorphix001/travelmate/blob/main/app/agents/aggregator.py): `app/agents/aggregator.py`
- [Plan editor](https://github.com/trevorphix001/travelmate/blob/main/app/agents/editor.py): `app/agents/editor.py`
- [Plan data models](https://github.com/trevorphix001/travelmate/blob/main/app/schemas/plan.py): `app/schemas/plan.py`

### Data sources

- [Place discovery](https://github.com/trevorphix001/travelmate/blob/main/app/tools/attractions.py): `app/tools/attractions.py`
- [Road routing](https://github.com/trevorphix001/travelmate/blob/main/app/tools/routing.py): `app/tools/routing.py`
- [Weather data](https://github.com/trevorphix001/travelmate/blob/main/app/tools/weather.py): `app/tools/weather.py`

### Shared services

- [Structured LLM client](https://github.com/trevorphix001/travelmate/blob/main/app/llm/client.py): `app/llm/client.py`
- [External-call cache](https://github.com/trevorphix001/travelmate/blob/main/app/core/cache.py): `app/core/cache.py`
- [Data repository](https://github.com/trevorphix001/travelmate/blob/main/app/db/repo.py): `app/db/repo.py`
- [Postgres](https://github.com/trevorphix001/travelmate/blob/main/app/db/pool.py): `app/db/pool.py`

### Other components

- **Traveler**

## Connections

- Traveler → Browser app: enters trip request (evidence: `README.md`)
- Browser app → Plans API: submits plan request (evidence: `README.md`)
- Plans API → Workflow graph: runs planning workflow
- Workflow graph → Request extraction: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Place resolution: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Attraction research: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Weather enrichment: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Transport options: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Day scheduling: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Budget adjustment: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Plan validation: dispatches (evidence: `app/graph/build.py`)
- Workflow graph → Workflow state: uses state (evidence: `app/graph/build.py`)
- Request extraction → Structured LLM client: extracts request (evidence: `app/agents/supervisor.py`)
- Attraction research → Place discovery: gathers candidates (evidence: `app/agents/research.py`)
- Attraction research → Structured LLM client: ranks candidate IDs (evidence: `app/agents/research.py`)
- Day scheduling → Structured LLM client: assigns days (evidence: `app/agents/itinerary.py`)
- Day scheduling → Road routing: computes travel legs (evidence: `app/agents/itinerary.py`)
- Budget adjustment → Day scheduling: requests replanning (evidence: `README.md`)
- Plan validation → Plan data models: validates plan (evidence: `app/agents/aggregator.py`)
- Day scheduling → Plan data models: builds day plans (evidence: `app/agents/itinerary.py`)
- Weather enrichment → Weather data: fetches forecasts
- Transport options → Road routing: gets route estimates
- Structured LLM client → External-call cache: caches responses (evidence: `app/llm/client.py`)
- External-call cache → Data repository: reads and writes cache (evidence: `app/core/cache.py`)
- Data repository → Postgres: executes SQL (evidence: `app/db/repo.py`)
- Plans API → Plan editor: edits saved plans (evidence: `app/api/plans.py`)
- Plans API → Data repository: saves and loads plans (evidence: `app/api/plans.py`)
- Browser app → Plan view: renders itinerary (evidence: `web/js/app.js`)
- Plans API → Browser app: returns plan data
