# jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner architecture

> Architecture diagram of the GitHub repository jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner, 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/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner
- Repository: https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner

## Overview

TripMate AI is a web-based, multi-agent travel planner. A user submits a natural-language request in the browser; the FastAPI endpoint invokes the LangGraph workflow, which validates and selects travel specialists, gathers research, builds an itinerary, and returns a polished answer. The browser displays the answer and supports copying or PDF export. The workflow also documents budget and human-approval state, though their execution paths are not visible in the excerpts. Relationships below use shown calls or README workflow descriptions; unsampled routing is omitted.

Main entry points: [`backend.py`](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py) (Guardrail and supervisor), [`mcp_client.py`](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/mcp_client.py) (MCP tool client), [`app.py`](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/app.py) (FastAPI endpoint), [`static/script.js`](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/static/script.js) (Travel interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webui["Travel interface<br/>[script.js]"]
  node_page["Planner page"]
  node_api["FastAPI endpoint<br/>[app.py]"]
end

subgraph group_workflow["Travel workflow"]
  node_orchestrator["Workflow runner<br/>[backend.py]"]
  node_supervisor["Guardrail and supervisor<br/>[backend.py]"]
  node_flightagent["Flight agent<br/>[backend.py]"]
  node_hotelagent["Hotel agent<br/>[backend.py]"]
  node_weatheragent["Weather agent<br/>[backend.py]"]
  node_budget["Budget and approval<br/>[backend.py]"]
  node_itinerary["Itinerary agent<br/>[backend.py]"]
  node_final["Final response agent<br/>[backend.py]"]
end

subgraph group_research["Travel research"]
  node_mcp["MCP tool client<br/>[mcp_client.py]"]
  node_flighttool["Flight lookup<br/>[flight_tool.py]"]
  node_tavilytool["Hotel web search<br/>[tavily_tool.py]"]
  node_weather["Weather MCP server"]
end

subgraph group_state["Conversation state"]
  node_postgres[("PostgreSQL checkpoint store")]
end

node_traveler(("Traveler"))
node_travelapis["Travel tool services"]
node_groq["Groq LLM"]

node_traveler -->|"submits request"| node_webui
node_webui -->|"POSTs request"| node_api
node_api -->|"renders page"| node_page
node_api -->|"invokes runner"| node_orchestrator
node_orchestrator -.->|"starts workflow"| node_supervisor
node_supervisor -.->|"selects agents"| node_flightagent
node_supervisor -.->|"selects agents"| node_hotelagent
node_supervisor -.->|"selects agents"| node_weatheragent
node_supervisor -.->|"may select"| node_budget
node_supervisor -.->|"selects agents"| node_itinerary
node_flightagent -->|"calls tools"| node_mcp
node_hotelagent -->|"searches hotels"| node_mcp
node_weatheragent -->|"requests weather"| node_mcp
node_mcp -->|"queries services"| node_travelapis
node_mcp -->|"starts server"| node_weather
node_weather -->|"requests forecasts"| node_travelapis
node_itinerary -.->|"provides itinerary"| node_final
node_final -.->|"generates response"| node_groq
node_orchestrator -->|"checkpoints state"| node_postgres
node_api -->|"returns results"| node_webui

click node_webui "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/static/script.js"
click node_page "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/tree/main/templates"
click node_api "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/app.py"
click node_orchestrator "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_supervisor "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_flightagent "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_hotelagent "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_weatheragent "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_budget "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_itinerary "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_final "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py"
click node_mcp "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/mcp_client.py"
click node_flighttool "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/tools/flight_tool.py"
click node_tavilytool "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/tools/tavily_tool.py"
click node_weather "https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/custom_weather_mcp_server.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_webui,node_page,node_api toneBlue
class node_orchestrator,node_supervisor,node_flightagent,node_hotelagent,node_weatheragent,node_budget,node_itinerary,node_final toneAmber
class node_mcp,node_flighttool,node_tavilytool,node_weather toneMint
class node_postgres toneRose
class node_traveler,node_travelapis,node_groq toneIndigo
```

## Components

### Web experience

- [Travel interface](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/static/script.js): `static/script.js`
- [Planner page](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/tree/main/templates): `templates`
- [FastAPI endpoint](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/app.py): `app.py`

### Travel workflow

- [Workflow runner](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Guardrail and supervisor](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Flight agent](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Hotel agent](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Weather agent](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Budget and approval](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Itinerary agent](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`
- [Final response agent](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/backend.py): `backend.py`

### Travel research

- [MCP tool client](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/mcp_client.py): `mcp_client.py`
- [Flight lookup](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/tools/flight_tool.py): `tools/flight_tool.py`
- [Hotel web search](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/tools/tavily_tool.py): `tools/tavily_tool.py`
- [Weather MCP server](https://github.com/jeyaseelan6/tripmate-ai---a-multi-agent-travel-planner/blob/main/custom_weather_mcp_server.py): `custom_weather_mcp_server.py`

### Conversation state

- **PostgreSQL checkpoint store**

### Other components

- **Traveler**
- **Travel tool services**
- **Groq LLM**

## Connections

- Traveler → Travel interface: submits request (evidence: `static/script.js`)
- Travel interface → FastAPI endpoint: POSTs request (evidence: `static/script.js`)
- FastAPI endpoint → Planner page: renders page (evidence: `app.py`)
- FastAPI endpoint → Workflow runner: invokes runner (evidence: `app.py`)
- Workflow runner → Guardrail and supervisor: starts workflow (evidence: `backend.py`)
- Guardrail and supervisor → Flight agent: selects agents (evidence: `backend.py`)
- Guardrail and supervisor → Hotel agent: selects agents (evidence: `backend.py`)
- Guardrail and supervisor → Weather agent: selects agents (evidence: `backend.py`)
- Guardrail and supervisor → Budget and approval: may select (evidence: `backend.py`)
- Guardrail and supervisor → Itinerary agent: selects agents (evidence: `backend.py`)
- Flight agent → MCP tool client: calls tools (evidence: `backend.py`)
- Hotel agent → MCP tool client: searches hotels (evidence: `backend.py`)
- Weather agent → MCP tool client: requests weather (evidence: `backend.py`)
- MCP tool client → Travel tool services: queries services (evidence: `mcp_client.py`)
- MCP tool client → Weather MCP server: starts server (evidence: `mcp_client.py`)
- Weather MCP server → Travel tool services: requests forecasts (evidence: `custom_weather_mcp_server.py`)
- Itinerary agent → Final response agent: provides itinerary (evidence: `backend.py`)
- Final response agent → Groq LLM: generates response
- Workflow runner → PostgreSQL checkpoint store: checkpoints state (evidence: `backend.py`)
- FastAPI endpoint → Travel interface: returns results (evidence: `app.py`)
