# entbappy/tripmate-ai-using-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/entbappy/tripmate-ai-using-mcp
- Repository: https://github.com/entbappy/tripmate-ai-using-mcp

## Overview

#### Purpose and Entry Points
TripMate AI converts a natural-language travel request into flights, hotel research, weather, and a day-by-day itinerary. The FastAPI process starts at `app.py`; the main multi-agent travel workflow resides in `backend.py`. Browser delivery is served through `templates/index.html` with assets in `static/script.js` and `static/style.css`.

#### API and Request Boundary
`app.py` exposes the health endpoint and the travel-submission API. It accepts the user message from the browser or an API consumer, delegates planning to `backend.py`, and returns the generated response. This is the primary synchronous HTTP boundary; agent/tool work below it is asynchronous where MCP clients are invoked.

#### LangGraph Planning Workflow
`backend.py` is the orchestration layer and system’s core control plane. It defines the LangGraph-driven sequence of specialized stages:
1. interpret the trip request and destination,
2. research flights,
3. research hotels,
4. obtain current weather/forecast,
5. synthesize a practical itinerary,
6. produce the final user-facing response.

The workflow uses LangChain/Groq-backed LLM agents for reasoning and consolidation, while treating retrieved travel facts as upstream context rather than directly coupling agents to provider APIs.

#### MCP Tool-Integration Boundary
`mcp_client.py` centralizes MCP transport and exposes async helpers used by the workflow for Tavily, AviationStack, weather, forecasts, and destination extraction. This isolates provider-specific invocation from `backend.py` and supports three MCP deployment forms:
- remote Tavily MCP endpoint,
- local stdio `uvx aviationstack-mcp` command,
- local custom weather server.

Relevant paths: `mcp_client.py`, `custom_weather_mcp_server.py`, `backend.py`.

#### Travel Data Providers
Flight research is backed by AviationStack through MCP; hotel ideas come from Tavily web search; weather is supplied through the project-owned MCP server backed by OpenWeather credentials. Legacy/direct integration modules may also support the tool layer: `tools/flight_tool.py` and `tools/tavily_tool.py`. Provider credentials and default origin are environment-driven, keeping secrets and deployment-specific values outside application code.

#### Weather MCP Service
`custom_weather_mcp_server.py` is a separately launched local MCP server process, invoked by the client over stdio. It provides weather and forecast capabilities to the weather stage without exposing OpenWeather calls directly to the main API process. Its process lifecycle and Python executable path must be compatible with the command configured in `mcp_client.py`.

#### State, Runtime, and Infrastructure
The runtime is Python 3.10+ with FastAPI, LangGraph/LangChain, and Groq LLM access. PostgreSQL persists conversation/workflow state, forming the durable-state boundary for requests beyond a single HTTP interaction. Required external dependencies are PostgreSQL, Groq, Tavily MCP, AviationStack MCP/API, OpenWeather, and local `uvx` for the AviationStack MCP command. Container deployment is represented by `Dockerfile`.

Main entry points: [`mcp_client.py`](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/mcp_client.py) (MCP client), [`backend.py`](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py) (LangGraph workflow), [`app.py`](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/app.py) (FastAPI entrypoint), [`templates/index.html`](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/templates/index.html) (Trip request page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser UI"]
  node_web_page["Trip request page<br/>HTML UI<br/>[index.html]"]
  node_browser_logic["Browser client<br/>JavaScript<br/>[script.js]"]
  node_browser_styles["Browser styles<br/>CSS<br/>[style.css]"]
end

subgraph group_api["Application API"]
  node_api_server["FastAPI entrypoint<br/>HTTP API<br/>[app.py]"]
  node_deployment["Container deployment<br/>Docker image"]
end

subgraph group_planning["Travel Planning"]
  node_workflow["LangGraph workflow<br/>orchestrator<br/>[backend.py]"]
  node_request_interpretation["Trip interpretation<br/>agent stage<br/>[backend.py]"]
  node_flight_research["Flight research<br/>agent stage<br/>[backend.py]"]
  node_hotel_research["Hotel research<br/>agent stage<br/>[backend.py]"]
  node_weather_research["Weather research<br/>agent stage<br/>[backend.py]"]
  node_itinerary_synthesis["Itinerary and response<br/>agent stage<br/>[backend.py]"]
end

subgraph group_mcp["MCP Integration"]
  node_mcp_client{{"MCP client<br/>async tool gateway<br/>[mcp_client.py]"}}
  node_weather_mcp["Weather MCP server<br/>local stdio service"]
  node_legacy_tools["Direct tool modules<br/>integration modules<br/>[flight_tool.py]"]
end

subgraph group_external["External Services"]
  node_llm["Groq LLM<br/>LLM service"]
  node_state_db[("PostgreSQL state<br/>durable state")]
  node_travel_providers["Travel data providers<br/>provider APIs"]
end

node_web_page -->|"loads"| node_browser_logic
node_browser_styles -->|"styles"| node_web_page
node_browser_logic -->|"submits travel request"| node_api_server
node_api_server -->|"delegates planning"| node_workflow
node_workflow -->|"starts with"| node_request_interpretation
node_request_interpretation -->|"destination context"| node_flight_research
node_flight_research -->|"research sequence"| node_hotel_research
node_hotel_research -->|"research sequence"| node_weather_research
node_weather_research -->|"facts and forecast"| node_itinerary_synthesis
node_itinerary_synthesis -->|"final response"| node_api_server
node_workflow -->|"reasoning"| node_llm
node_workflow -->|"persists state"| node_state_db
node_flight_research -->|"async flight lookup"| node_mcp_client
node_hotel_research -->|"async web search"| node_mcp_client
node_weather_research -->|"async weather lookup"| node_mcp_client
node_mcp_client -->|"stdio invocation"| node_weather_mcp
node_mcp_client -->|"MCP provider access"| node_travel_providers
node_weather_mcp -->|"OpenWeather credentials"| node_travel_providers
node_legacy_tools -.->|"direct integration support"| node_travel_providers
node_deployment -->|"packages"| node_api_server

click node_web_page "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/templates/index.html"
click node_browser_logic "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/static/script.js"
click node_browser_styles "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/static/style.css"
click node_api_server "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/app.py"
click node_workflow "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py"
click node_request_interpretation "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py"
click node_flight_research "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py"
click node_hotel_research "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py"
click node_weather_research "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py"
click node_itinerary_synthesis "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py"
click node_mcp_client "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/mcp_client.py"
click node_weather_mcp "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/custom_weather_mcp_server.py"
click node_legacy_tools "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/tools/flight_tool.py"
click node_deployment "https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/Dockerfile"

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_page,node_browser_logic,node_browser_styles toneBlue
class node_api_server,node_deployment toneAmber
class node_workflow,node_request_interpretation,node_flight_research,node_hotel_research,node_weather_research,node_itinerary_synthesis toneMint
class node_mcp_client,node_weather_mcp,node_legacy_tools toneRose
class node_llm,node_state_db,node_travel_providers toneIndigo
```

## Components

### Browser UI

- [Trip request page](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/templates/index.html): HTML UI · `templates/index.html`
- [Browser client](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/static/script.js): JavaScript · `static/script.js`
- [Browser styles](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/static/style.css): CSS · `static/style.css`

### Application API

- [FastAPI entrypoint](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/app.py): HTTP API · Serves health and travel-submission endpoints. · `app.py`
- [Container deployment](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/Dockerfile): Docker image · `Dockerfile`

### Travel Planning

- [LangGraph workflow](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py): orchestrator · Coordinates request interpretation, research, itinerary synthesis, and response. · `backend.py`
- [Trip interpretation](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py): agent stage · `backend.py`
- [Flight research](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py): agent stage · `backend.py`
- [Hotel research](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py): agent stage · `backend.py`
- [Weather research](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py): agent stage · `backend.py`
- [Itinerary and response](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/backend.py): agent stage · `backend.py`

### MCP Integration

- [MCP client](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/mcp_client.py): async tool gateway · Centralizes remote and local MCP transport. · `mcp_client.py`
- [Weather MCP server](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/custom_weather_mcp_server.py): local stdio service · Separately launched server for weather and forecasts. · `custom_weather_mcp_server.py`
- [Direct tool modules](https://github.com/entbappy/tripmate-ai-using-mcp/blob/main/tools/flight_tool.py): integration modules · Legacy support for flight and Tavily integrations. · `tools/flight_tool.py`

### External Services

- **Groq LLM**: LLM service · LangChain-backed reasoning and consolidation.
- **PostgreSQL state**: durable state · Persists conversation and workflow state.
- **Travel data providers**: provider APIs · Tavily, AviationStack, and OpenWeather supply travel facts.

## Connections

- Trip request page → Browser client: loads
- Browser styles → Trip request page: styles
- Browser client → FastAPI entrypoint: submits travel request
- FastAPI entrypoint → LangGraph workflow: delegates planning
- LangGraph workflow → Trip interpretation: starts with
- Trip interpretation → Flight research: destination context
- Flight research → Hotel research: research sequence
- Hotel research → Weather research: research sequence
- Weather research → Itinerary and response: facts and forecast
- Itinerary and response → FastAPI entrypoint: final response
- LangGraph workflow → Groq LLM: reasoning
- LangGraph workflow → PostgreSQL state: persists state
- Flight research → MCP client: async flight lookup
- Hotel research → MCP client: async web search
- Weather research → MCP client: async weather lookup
- MCP client → Weather MCP server: stdio invocation
- MCP client → Travel data providers: MCP provider access
- Weather MCP server → Travel data providers: OpenWeather credentials
- Direct tool modules → Travel data providers: direct integration support
- Container deployment → FastAPI entrypoint: packages