# dhruva-31/tripmate-ai architecture

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

- Interactive diagram: https://gitdiagram.com/dhruva-31/tripmate-ai
- Repository: https://github.com/dhruva-31/tripmate-ai

## Overview

TripMate AI turns a natural-language travel request into a reviewed travel plan. A browser submits the request to the FastAPI app, which invokes a LangGraph workflow: guardrail and supervisor routing, selected flight, hotel, weather, and budget research, itinerary drafting, human approval or revision, and final response formatting. PostgreSQL persists workflow state. The README documents the main travel-agent stages; sampled backend excerpts also show weather, budget, and approval behavior. The separate MCP client and direct-search tools are represented, but unsampled backend sections limit some call-level detail.

Main entry points: [`backend.py`](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py) (Guardrail and routing), [`mcp_client.py`](https://github.com/dhruva-31/tripmate-ai/blob/main/mcp_client.py) (MCP client), [`app.py`](https://github.com/dhruva-31/tripmate-ai/blob/main/app.py) (FastAPI endpoints), [`static/script.js`](https://github.com/dhruva-31/tripmate-ai/blob/main/static/script.js) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Web interface<br/>[script.js]"]
  node_api["FastAPI endpoints<br/>[app.py]"]
end

subgraph group_workflow["Travel workflow"]
  node_orchestrator["LangGraph workflow<br/>[backend.py]"]
  node_supervisor["Guardrail and routing<br/>[backend.py]"]
  node_flight["Flight research<br/>[backend.py]"]
  node_hotel["Hotel research<br/>[backend.py]"]
  node_weather["Weather research<br/>[backend.py]"]
  node_budget["Budget analysis<br/>[backend.py]"]
  node_itinerary["Itinerary planning<br/>[backend.py]"]
  node_approval["Plan approval<br/>[backend.py]"]
  node_response["Final response<br/>[backend.py]"]
end

subgraph group_integrations["Research integrations"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
  node_weather_server["Weather MCP server"]
  node_flight_tool["Flight search tool<br/>[flight_tool.py]"]
  node_tavily_tool["Tavily search tool<br/>[travily_tool.py]"]
end

subgraph group_state["Workflow state"]
  node_postgres[("PostgreSQL checkpoint<br/>[backend.py]")]
end

node_traveler(("Traveler"))
node_aviation["AviationStack"]
node_tavily["Tavily search"]
node_openweather["OpenWeather"]

node_traveler -->|"enters request"| node_browser
node_browser -->|"posts travel request"| node_api
node_api -->|"runs workflow"| node_orchestrator
node_api -->|"resumes approval"| node_orchestrator
node_orchestrator -->|"routes request"| node_supervisor
node_supervisor -->|"selects agent"| node_flight
node_supervisor -->|"selects agent"| node_hotel
node_supervisor -.->|"selects agent"| node_weather
node_supervisor -.->|"selects agent"| node_budget
node_supervisor -->|"selects agent"| node_itinerary
node_flight -->|"requests flight data"| node_mcp
node_hotel -->|"searches hotels"| node_mcp
node_weather -->|"requests conditions"| node_mcp
node_mcp -->|"calls aviation tools"| node_aviation
node_mcp -->|"searches web"| node_tavily
node_mcp -->|"launches server"| node_weather_server
node_weather_server -->|"fetches weather"| node_openweather
node_flight -->|"informs itinerary"| node_itinerary
node_hotel -->|"informs itinerary"| node_itinerary
node_itinerary -->|"requests review"| node_approval
node_approval -->|"revises draft"| node_itinerary
node_approval -->|"approves plan"| node_response
node_itinerary -->|"formats result"| node_response
node_orchestrator -->|"checkpoints state"| node_postgres
node_orchestrator -.->|"may use direct search"| node_flight_tool
node_orchestrator -.->|"may use direct search"| node_tavily_tool

click node_browser "https://github.com/dhruva-31/tripmate-ai/blob/main/static/script.js"
click node_api "https://github.com/dhruva-31/tripmate-ai/blob/main/app.py"
click node_orchestrator "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_supervisor "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_flight "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_hotel "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_weather "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_budget "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_itinerary "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_approval "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_response "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py"
click node_mcp "https://github.com/dhruva-31/tripmate-ai/blob/main/mcp_client.py"
click node_weather_server "https://github.com/dhruva-31/tripmate-ai/blob/main/custom_weather_mcp_server.py"
click node_flight_tool "https://github.com/dhruva-31/tripmate-ai/blob/main/tools/flight_tool.py"
click node_tavily_tool "https://github.com/dhruva-31/tripmate-ai/blob/main/tools/travily_tool.py"
click node_postgres "https://github.com/dhruva-31/tripmate-ai/blob/main/backend.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_browser,node_api toneBlue
class node_orchestrator,node_supervisor,node_flight,node_hotel,node_weather,node_budget,node_itinerary,node_approval,node_response toneAmber
class node_mcp,node_weather_server,node_flight_tool,node_tavily_tool toneMint
class node_postgres toneRose
class node_traveler,node_aviation,node_tavily,node_openweather toneIndigo
```

## Components

### Web experience

- [Web interface](https://github.com/dhruva-31/tripmate-ai/blob/main/static/script.js): `static/script.js`
- [FastAPI endpoints](https://github.com/dhruva-31/tripmate-ai/blob/main/app.py): `app.py`

### Travel workflow

- [LangGraph workflow](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Guardrail and routing](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Flight research](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Hotel research](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Weather research](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Budget analysis](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Itinerary planning](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Plan approval](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`
- [Final response](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`

### Research integrations

- [MCP client](https://github.com/dhruva-31/tripmate-ai/blob/main/mcp_client.py): `mcp_client.py`
- [Weather MCP server](https://github.com/dhruva-31/tripmate-ai/blob/main/custom_weather_mcp_server.py): `custom_weather_mcp_server.py`
- [Flight search tool](https://github.com/dhruva-31/tripmate-ai/blob/main/tools/flight_tool.py): `tools/flight_tool.py`
- [Tavily search tool](https://github.com/dhruva-31/tripmate-ai/blob/main/tools/travily_tool.py): `tools/travily_tool.py`

### Workflow state

- [PostgreSQL checkpoint](https://github.com/dhruva-31/tripmate-ai/blob/main/backend.py): `backend.py`

### Other components

- **Traveler**
- **AviationStack**
- **Tavily search**
- **OpenWeather**

## Connections

- Traveler → Web interface: enters request (evidence: `static/script.js`)
- Web interface → FastAPI endpoints: posts travel request (evidence: `static/script.js`)
- FastAPI endpoints → LangGraph workflow: runs workflow (evidence: `app.py`)
- FastAPI endpoints → LangGraph workflow: resumes approval (evidence: `app.py`)
- LangGraph workflow → Guardrail and routing: routes request (evidence: `README.md`)
- Guardrail and routing → Flight research: selects agent (evidence: `README.md`)
- Guardrail and routing → Hotel research: selects agent (evidence: `README.md`)
- Guardrail and routing → Weather research: selects agent (evidence: `backend.py`)
- Guardrail and routing → Budget analysis: selects agent (evidence: `backend.py`)
- Guardrail and routing → Itinerary planning: selects agent (evidence: `README.md`)
- Flight research → MCP client: requests flight data (evidence: `backend.py`)
- Hotel research → MCP client: searches hotels (evidence: `backend.py`)
- Weather research → MCP client: requests conditions (evidence: `backend.py`)
- MCP client → AviationStack: calls aviation tools (evidence: `mcp_client.py`)
- MCP client → Tavily search: searches web (evidence: `mcp_client.py`)
- MCP client → Weather MCP server: launches server (evidence: `mcp_client.py`)
- Weather MCP server → OpenWeather: fetches weather (evidence: `custom_weather_mcp_server.py`)
- Flight research → Itinerary planning: informs itinerary (evidence: `README.md`)
- Hotel research → Itinerary planning: informs itinerary (evidence: `README.md`)
- Itinerary planning → Plan approval: requests review (evidence: `backend.py`)
- Plan approval → Itinerary planning: revises draft (evidence: `backend.py`)
- Plan approval → Final response: approves plan (evidence: `backend.py`)
- Itinerary planning → Final response: formats result (evidence: `README.md`)
- LangGraph workflow → PostgreSQL checkpoint: checkpoints state (evidence: `backend.py`)
- LangGraph workflow → Flight search tool: may use direct search (evidence: `backend.py`)
- LangGraph workflow → Tavily search tool: may use direct search (evidence: `backend.py`)
