# sufyansidd19/ai-travel-planner-agentic-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sufyansidd19/ai-travel-planner-agentic-ai
- Repository: https://github.com/sufyansidd19/ai-travel-planner-agentic-ai

## Overview

This repository contains two travel-planning workflows: a newer LangGraph supervisor flow with specialist research, itinerary drafting, human approval and persistent state, and a simpler sequential flight/hotel workflow in the root-level app. The MCP configuration exposes Tavily, AviationStack and weather tools; the legacy flow directly uses flight and web-search helpers. README capabilities are included where documented, but the excerpts do not show every integration call or the full guardrail and approval implementation.

Main entry points: [`Travel Agent MCP & HILP/graph.py`](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/graph.py) (Supervisor graph), [`main.py`](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/main.py) (Sequential travel graph), [`Travel Agent MCP & HILP/agent.py`](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py) (Research specialists), [`Travel Agent MCP & HILP/frontend.py`](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/frontend.py) (Planner UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_mcp_ui["Planner UI<br/>[frontend.py]"]
  node_legacy_ui["Legacy UI<br/>[frontend.py]"]
  node_legacy_alt_ui["Alternate UI<br/>[UI.py]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_mcp_graph["Supervisor graph<br/>[graph.py]"]
  node_supervisor["Guardrails and routing<br/>[agent.py]"]
  node_legacy_app["Sequential travel graph<br/>[main.py]"]
end

subgraph group_planning["Travel planning"]
  node_specialists["Research specialists<br/>[agent.py]"]
  node_itinerary["Itinerary drafting<br/>[agent.py]"]
  node_approval["Human approval<br/>[agent.py]"]
  node_final_plan["Final plan<br/>[agent.py]"]
end

subgraph group_integrations["Data integrations"]
  node_mcp_client["MCP tool client<br/>[mcp_client.py]"]
  node_mcp_services{{"MCP data services"}}
  node_legacy_flight["Flight search<br/>[flight_tool.py]"]
  node_legacy_search["Web search<br/>[tavily_tool.py]"]
  node_groq{{"Groq LLM"}}
end

subgraph group_persistence["State and memory"]
  node_state_schema["Travel state<br/>[state.py]"]
  node_postgres[("PostgreSQL checkpoints")]
  node_legacy_postgres[("Legacy checkpoints")]
end

node_traveler(("Traveler"))

node_traveler -->|"enters trip request"| node_mcp_ui
node_mcp_ui -->|"invokes graph"| node_mcp_graph
node_mcp_graph -->|"routes request"| node_supervisor
node_mcp_graph -->|"dispatches specialists"| node_specialists
node_mcp_graph -->|"dispatches itinerary"| node_itinerary
node_mcp_graph -->|"routes for approval"| node_approval
node_mcp_graph -->|"routes finalization"| node_final_plan
node_supervisor -->|"selects agents"| node_specialists
node_specialists -->|"requests MCP tools"| node_mcp_client
node_mcp_client -->|"invokes tools"| node_mcp_services
node_itinerary -.->|"generates draft"| node_groq
node_final_plan -.->|"polishes plan"| node_groq
node_traveler -->|"provides feedback"| node_approval
node_mcp_graph -->|"uses state"| node_state_schema
node_mcp_graph -->|"checkpoints state"| node_postgres
node_traveler -->|"enters trip request"| node_legacy_ui
node_legacy_ui -->|"invokes app"| node_legacy_app
node_traveler -->|"enters trip request"| node_legacy_alt_ui
node_legacy_alt_ui -->|"invokes app"| node_legacy_app
node_legacy_app -->|"searches flights"| node_legacy_flight
node_legacy_app -->|"searches hotels"| node_legacy_search
node_legacy_app -->|"generates itinerary"| node_groq
node_legacy_app -->|"checkpoints graph"| node_legacy_postgres

click node_mcp_ui "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/frontend.py"
click node_legacy_ui "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/frontend.py"
click node_legacy_alt_ui "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/UI.py"
click node_mcp_graph "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/graph.py"
click node_supervisor "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py"
click node_specialists "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py"
click node_itinerary "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py"
click node_approval "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py"
click node_final_plan "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py"
click node_mcp_client "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/mcp_client.py"
click node_legacy_app "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/main.py"
click node_legacy_flight "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/tools/flight_tool.py"
click node_legacy_search "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/tools/tavily_tool.py"
click node_state_schema "https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/state.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_mcp_ui,node_legacy_ui,node_legacy_alt_ui toneBlue
class node_mcp_graph,node_supervisor,node_legacy_app toneAmber
class node_specialists,node_itinerary,node_approval,node_final_plan toneMint
class node_mcp_client,node_mcp_services,node_legacy_flight,node_legacy_search,node_groq toneRose
class node_state_schema,node_postgres,node_legacy_postgres,node_traveler toneIndigo
```

## Components

### User interfaces

- [Planner UI](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/frontend.py): `Travel Agent MCP & HILP/frontend.py`
- [Legacy UI](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/frontend.py): `frontend.py`
- [Alternate UI](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/UI.py): `UI.py`

### Agent orchestration

- [Supervisor graph](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/graph.py): `Travel Agent MCP & HILP/graph.py`
- [Guardrails and routing](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py): `Travel Agent MCP & HILP/agent.py`
- [Sequential travel graph](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/main.py): `main.py`

### Travel planning

- [Research specialists](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py): `Travel Agent MCP & HILP/agent.py`
- [Itinerary drafting](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py): `Travel Agent MCP & HILP/agent.py`
- [Human approval](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py): `Travel Agent MCP & HILP/agent.py`
- [Final plan](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/agent.py): `Travel Agent MCP & HILP/agent.py`

### Data integrations

- [MCP tool client](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/mcp_client.py): `Travel Agent MCP & HILP/mcp_client.py`
- **MCP data services**
- [Flight search](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/tools/flight_tool.py): `tools/flight_tool.py`
- [Web search](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/tools/tavily_tool.py): `tools/tavily_tool.py`
- **Groq LLM**

### State and memory

- [Travel state](https://github.com/sufyansidd19/ai-travel-planner-agentic-ai/blob/main/Travel%20Agent%20MCP%20%26%20HILP/state.py): `Travel Agent MCP & HILP/state.py`
- **PostgreSQL checkpoints**
- **Legacy checkpoints**

### Other components

- **Traveler**

## Connections

- Traveler → Planner UI: enters trip request (evidence: `Travel Agent MCP & HILP/frontend.py`)
- Planner UI → Supervisor graph: invokes graph (evidence: `Travel Agent MCP & HILP/frontend.py`)
- Supervisor graph → Guardrails and routing: routes request (evidence: `Travel Agent MCP & HILP/graph.py`)
- Supervisor graph → Research specialists: dispatches specialists (evidence: `Travel Agent MCP & HILP/graph.py`)
- Supervisor graph → Itinerary drafting: dispatches itinerary (evidence: `Travel Agent MCP & HILP/graph.py`)
- Supervisor graph → Human approval: routes for approval (evidence: `Travel Agent MCP & HILP/graph.py`)
- Supervisor graph → Final plan: routes finalization (evidence: `Travel Agent MCP & HILP/graph.py`)
- Guardrails and routing → Research specialists: selects agents (evidence: `Travel Agent MCP & HILP/graph.py`)
- Research specialists → MCP tool client: requests MCP tools (evidence: `Travel Agent MCP & HILP/agent.py`)
- MCP tool client → MCP data services: invokes tools (evidence: `Travel Agent MCP & HILP/mcp_client.py`)
- Itinerary drafting → Groq LLM: generates draft
- Final plan → Groq LLM: polishes plan
- Traveler → Human approval: provides feedback (evidence: `Travel Agent MCP & HILP/agent.py`)
- Supervisor graph → Travel state: uses state (evidence: `Travel Agent MCP & HILP/graph.py`)
- Supervisor graph → PostgreSQL checkpoints: checkpoints state (evidence: `Travel Agent MCP & HILP/graph.py`)
- Traveler → Legacy UI: enters trip request (evidence: `frontend.py`)
- Legacy UI → Sequential travel graph: invokes app (evidence: `frontend.py`)
- Traveler → Alternate UI: enters trip request (evidence: `UI.py`)
- Alternate UI → Sequential travel graph: invokes app (evidence: `UI.py`)
- Sequential travel graph → Flight search: searches flights (evidence: `main.py`)
- Sequential travel graph → Web search: searches hotels (evidence: `main.py`)
- Sequential travel graph → Groq LLM: generates itinerary (evidence: `main.py`)
- Sequential travel graph → Legacy checkpoints: checkpoints graph (evidence: `main.py`)