# thushi404/agentic-ai-travel-guide architecture

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

- Interactive diagram: https://gitdiagram.com/thushi404/agentic-ai-travel-guide
- Repository: https://github.com/thushi404/agentic-ai-travel-guide

## Overview

This is a command-line AI travel assistant. A user enters a travel request; the app sends it through a stateful LangGraph agent, which can dispatch MCP tools and returns a response to the terminal. Its domain capabilities include weather forecasts, nearby-place searches, walking estimates, and itinerary generation. Itinerary generation combines weather and place-search results. The excerpts show the MCP server and tool implementations, but not the adapter’s runtime dispatch internals; that connection is documented by the app’s MCP configuration and tool-loading code.

Main entry points: [`travel-agent/mcp/server.py`](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/mcp/server.py) (MCP tool server), [`travel-agent/graph/graph.py`](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/graph.py) (Graph workflow), [`travel-agent/graph/nodes.py`](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/nodes.py) (Agent and tools), [`travel-agent/tools/maps.py`](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/maps.py) (Places and walking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Conversation"]
  node_cli["Chat CLI<br/>[app.py]"]
  node_mcp_server["MCP tool server<br/>[server.py]"]
end

subgraph group_agent["Agent workflow"]
  node_workflow["Graph workflow<br/>[graph.py]"]
  node_agent_node["Agent and tools<br/>[nodes.py]"]
  node_state["Conversation state<br/>[state.py]"]
  node_prompt["Travel prompt<br/>[prompts.py]"]
end

subgraph group_travel["Travel capabilities"]
  node_weather["Weather lookup<br/>[weather.py]"]
  node_maps["Places and walking<br/>[maps.py]"]
  node_itinerary["Itinerary builder<br/>[itinerary.py]"]
end

subgraph group_integrations["External services"]
  node_config["API configuration<br/>[config.py]"]
  node_llm{{"OpenAI model"}}
  node_geoapify{{"Geoapify APIs"}}
  node_open_meteo{{"Open-Meteo APIs"}}
end

node_traveler(("Traveler"))

node_traveler -->|"enters request"| node_cli
node_cli -->|"starts server"| node_mcp_server
node_cli -->|"builds and invokes"| node_workflow
node_workflow -->|"creates nodes"| node_agent_node
node_workflow -->|"tracks messages"| node_state
node_agent_node -->|"uses prompt"| node_prompt
node_agent_node -->|"loads model settings"| node_config
node_agent_node -.->|"sends messages"| node_llm
node_mcp_server -->|"calls"| node_weather
node_mcp_server -->|"calls"| node_maps
node_mcp_server -->|"calls"| node_itinerary
node_workflow -.->|"loads registered tools"| node_mcp_server
node_itinerary -->|"gets forecast"| node_weather
node_itinerary -->|"searches places"| node_maps
node_weather -->|"geocodes and forecasts"| node_open_meteo
node_maps -->|"loads API key"| node_config
node_maps -->|"geocodes and searches"| node_geoapify

click node_cli "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/app.py"
click node_workflow "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/graph.py"
click node_agent_node "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/nodes.py"
click node_state "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/state.py"
click node_prompt "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/prompts.py"
click node_mcp_server "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/mcp/server.py"
click node_weather "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/weather.py"
click node_maps "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/maps.py"
click node_itinerary "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/itinerary.py"
click node_config "https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/config.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_cli,node_mcp_server toneBlue
class node_workflow,node_agent_node,node_state,node_prompt toneAmber
class node_weather,node_maps,node_itinerary toneMint
class node_config,node_llm,node_geoapify,node_open_meteo toneRose
class node_traveler toneIndigo
```

## Components

### Conversation

- [Chat CLI](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/app.py): `travel-agent/app.py`
- [MCP tool server](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/mcp/server.py): `travel-agent/mcp/server.py`

### Agent workflow

- [Graph workflow](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/graph.py): `travel-agent/graph/graph.py`
- [Agent and tools](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/nodes.py): `travel-agent/graph/nodes.py`
- [Conversation state](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/graph/state.py): `travel-agent/graph/state.py`
- [Travel prompt](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/prompts.py): `travel-agent/prompts.py`

### Travel capabilities

- [Weather lookup](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/weather.py): `travel-agent/tools/weather.py`
- [Places and walking](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/maps.py): `travel-agent/tools/maps.py`
- [Itinerary builder](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/tools/itinerary.py): `travel-agent/tools/itinerary.py`

### External services

- [API configuration](https://github.com/thushi404/agentic-ai-travel-guide/blob/main/travel-agent/config.py): `travel-agent/config.py`
- **OpenAI model**
- **Geoapify APIs**
- **Open-Meteo APIs**

### Other components

- **Traveler**

## Connections

- Traveler → Chat CLI: enters request (evidence: `travel-agent/app.py`)
- Chat CLI → MCP tool server: starts server (evidence: `travel-agent/app.py`)
- Chat CLI → Graph workflow: builds and invokes (evidence: `travel-agent/app.py`)
- Graph workflow → Agent and tools: creates nodes (evidence: `travel-agent/graph/graph.py`)
- Graph workflow → Conversation state: tracks messages (evidence: `travel-agent/graph/graph.py`)
- Agent and tools → Travel prompt: uses prompt (evidence: `travel-agent/graph/nodes.py`)
- Agent and tools → API configuration: loads model settings (evidence: `travel-agent/graph/nodes.py`)
- Agent and tools → OpenAI model: sends messages (evidence: `travel-agent/graph/nodes.py`)
- MCP tool server → Weather lookup: calls (evidence: `travel-agent/mcp/server.py`)
- MCP tool server → Places and walking: calls (evidence: `travel-agent/mcp/server.py`)
- MCP tool server → Itinerary builder: calls (evidence: `travel-agent/mcp/server.py`)
- Graph workflow → MCP tool server: loads registered tools
- Itinerary builder → Weather lookup: gets forecast (evidence: `travel-agent/tools/itinerary.py`)
- Itinerary builder → Places and walking: searches places (evidence: `travel-agent/tools/itinerary.py`)
- Weather lookup → Open-Meteo APIs: geocodes and forecasts (evidence: `travel-agent/tools/weather.py`)
- Places and walking → API configuration: loads API key (evidence: `travel-agent/tools/maps.py`)
- Places and walking → Geoapify APIs: geocodes and searches (evidence: `travel-agent/tools/maps.py`)
