# mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance architecture

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

- Interactive diagram: https://gitdiagram.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance
- Repository: https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance

## Overview

Travel & Itinerary Concierge is an ADK-based conversational agent that turns traveler requests into personalized recommendations, itinerary information, and rich media/UI responses. The principal web flow runs from the browser through a FastAPI A2A proxy to the agent, which invokes domain tools and returns structured parts for display. The agent also has a local FastAPI serving surface, shared session/artifact services, and integrations for destination data, weather, currency, maps, cultural information, media generation, and persistent traveler memories. Tool-level source excerpts are partial; the README documents capabilities whose exact internal wiring is not shown.

Main entry points: [`app/tools.py`](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py) (Travel tools), [`app/agent.py`](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/agent.py) (Concierge agent), [`app/fast_api_app.py`](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/fast_api_app.py) (Local FastAPI app), [`frontend/main.py`](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/frontend/main.py) (A2A web proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interaction"]
  node_chat_ui["Chat UI<br/>[index.html]"]
  node_web_proxy["A2A web proxy<br/>[main.py]"]
end

subgraph group_serving["Agent serving"]
  node_fastapi["Local FastAPI app<br/>[fast_api_app.py]"]
  node_a2a_routes["A2A routes<br/>[a2a.py]"]
  node_reasoning_adapter["Reasoning adapter"]
  node_agent["Concierge agent<br/>[agent.py]"]
  node_a2ui["A2UI rendering<br/>[a2ui_utils.py]"]
end

subgraph group_travel["Travel capabilities"]
  node_toolset["Travel tools<br/>[tools.py]"]
  node_destination_ops["Destination search and details<br/>[tools.py]"]
  node_weather["Weather forecasts<br/>[tools.py]"]
  node_currency["Currency conversion<br/>[tools.py]"]
  node_place_tools["Geocoding and nearby places<br/>[tools.py]"]
  node_culture_tools["Cultural and artwork lookup<br/>[tools.py]"]
  node_poster["Poster generation<br/>[tools.py]"]
  node_video["Destination video<br/>[tools.py]"]
end

subgraph group_state["Memory and artifacts"]
  node_memory["Traveler memory<br/>[agent.py]"]
  node_shared_services["Shared session and artifact services<br/>[services.py]"]
end

node_traveler(("Traveler"))
node_web_agent["Deployed agent"]
node_gemini["Gemini model"]
node_firestore[("Destinations store")]
node_open_meteo["Open-Meteo"]
node_exchange_api["ExchangeRate API"]
node_place_services["OpenStreetMap and places API"]
node_culture_apis["Wikipedia and museum APIs"]
node_imagen["Imagen"]
node_omni["Gemini Omni"]
node_memory_bank[("Vertex AI Memory Bank")]
node_session_store[("Session service")]
node_artifact_store[("Artifact service")]
node_gcs[("Cloud Storage")]
node_sandbox["Python execution sandbox"]

node_traveler -->|"sends request"| node_chat_ui
node_chat_ui -->|"posts chat"| node_web_proxy
node_web_proxy -->|"sends A2A message"| node_web_agent
node_web_agent -->|"returns parts"| node_web_proxy
node_web_proxy -->|"renders reply"| node_chat_ui
node_traveler -.->|"submits request"| node_fastapi
node_fastapi -->|"serves agent"| node_agent
node_fastapi -->|"registers routes"| node_a2a_routes
node_fastapi -->|"registers routes"| node_reasoning_adapter
node_a2a_routes -->|"dispatches requests"| node_agent
node_reasoning_adapter -->|"dispatches methods"| node_agent
node_agent -->|"interprets request"| node_gemini
node_agent -->|"invokes tools"| node_toolset
node_agent -->|"formats response"| node_a2ui
node_a2ui -.->|"emits UI data"| node_web_proxy
node_toolset -->|"includes"| node_destination_ops
node_destination_ops -->|"reads and writes"| node_firestore
node_toolset -->|"includes"| node_weather
node_weather -->|"requests forecasts"| node_open_meteo
node_toolset -->|"includes"| node_currency
node_currency -->|"converts amounts"| node_exchange_api
node_toolset -->|"includes"| node_place_tools
node_place_tools -->|"queries locations"| node_place_services
node_toolset -->|"includes"| node_culture_tools
node_culture_tools -->|"fetches information"| node_culture_apis
node_toolset -->|"includes"| node_poster
node_poster -->|"generates artwork"| node_imagen
node_toolset -->|"includes"| node_video
node_video -->|"generates preview"| node_omni
node_agent -->|"records preferences"| node_memory
node_memory -->|"stores memories"| node_memory_bank
node_fastapi -->|"gets services"| node_shared_services
node_reasoning_adapter -->|"gets services"| node_shared_services
node_shared_services -->|"provides sessions"| node_session_store
node_shared_services -->|"provides artifacts"| node_artifact_store
node_artifact_store -.->|"stores artifacts"| node_gcs
node_agent -.->|"executes Python"| node_sandbox

click node_chat_ui "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/frontend/static/index.html"
click node_web_proxy "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/frontend/main.py"
click node_fastapi "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/fast_api_app.py"
click node_a2a_routes "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/app_utils/a2a.py"
click node_reasoning_adapter "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/app_utils/reasoning_engine_adapter.py"
click node_agent "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/agent.py"
click node_a2ui "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/a2ui_utils.py"
click node_toolset "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_destination_ops "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_weather "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_currency "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_place_tools "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_culture_tools "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_poster "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_video "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py"
click node_memory "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/agent.py"
click node_shared_services "https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/app_utils/services.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_chat_ui,node_web_proxy toneBlue
class node_fastapi,node_a2a_routes,node_reasoning_adapter,node_agent,node_a2ui,node_firestore,node_memory_bank,node_session_store,node_artifact_store,node_gcs toneAmber
class node_toolset,node_destination_ops,node_weather,node_currency,node_place_tools,node_culture_tools,node_poster,node_video,node_exchange_api,node_place_services,node_culture_apis toneMint
class node_memory,node_shared_services toneRose
class node_traveler,node_web_agent,node_gemini,node_open_meteo,node_imagen,node_omni,node_sandbox toneIndigo
```

## Components

### Web interaction

- [Chat UI](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/frontend/static/index.html): `frontend/static/index.html`
- [A2A web proxy](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/frontend/main.py): `frontend/main.py`

### Agent serving

- [Local FastAPI app](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/fast_api_app.py): `app/fast_api_app.py`
- [A2A routes](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/app_utils/a2a.py): `app/app_utils/a2a.py`
- [Reasoning adapter](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/app_utils/reasoning_engine_adapter.py): `app/app_utils/reasoning_engine_adapter.py`
- [Concierge agent](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/agent.py): `app/agent.py`
- [A2UI rendering](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/a2ui_utils.py): `app/a2ui_utils.py`

### Travel capabilities

- [Travel tools](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Destination search and details](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Weather forecasts](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Currency conversion](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Geocoding and nearby places](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Cultural and artwork lookup](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Poster generation](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`
- [Destination video](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/tools.py): `app/tools.py`

### Memory and artifacts

- [Traveler memory](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/agent.py): `app/agent.py`
- [Shared session and artifact services](https://github.com/mayurbhapkarcts/buildwithgemini-personal-travel-ai-assistance/blob/main/app/app_utils/services.py): `app/app_utils/services.py`

### Other components

- **Traveler**
- **Deployed agent**
- **Gemini model**
- **Destinations store**
- **Open-Meteo**
- **ExchangeRate API**
- **OpenStreetMap and places API**
- **Wikipedia and museum APIs**
- **Imagen**
- **Gemini Omni**
- **Vertex AI Memory Bank**
- **Session service**
- **Artifact service**
- **Cloud Storage**
- **Python execution sandbox**

## Connections

- Traveler → Chat UI: sends request
- Chat UI → A2A web proxy: posts chat
- A2A web proxy → Deployed agent: sends A2A message
- Deployed agent → A2A web proxy: returns parts
- A2A web proxy → Chat UI: renders reply
- Traveler → Local FastAPI app: submits request
- Local FastAPI app → Concierge agent: serves agent
- Local FastAPI app → A2A routes: registers routes
- Local FastAPI app → Reasoning adapter: registers routes
- A2A routes → Concierge agent: dispatches requests
- Reasoning adapter → Concierge agent: dispatches methods
- Concierge agent → Gemini model: interprets request
- Concierge agent → Travel tools: invokes tools
- Concierge agent → A2UI rendering: formats response
- A2UI rendering → A2A web proxy: emits UI data
- Travel tools → Destination search and details: includes
- Destination search and details → Destinations store: reads and writes
- Travel tools → Weather forecasts: includes
- Weather forecasts → Open-Meteo: requests forecasts
- Travel tools → Currency conversion: includes
- Currency conversion → ExchangeRate API: converts amounts
- Travel tools → Geocoding and nearby places: includes
- Geocoding and nearby places → OpenStreetMap and places API: queries locations
- Travel tools → Cultural and artwork lookup: includes
- Cultural and artwork lookup → Wikipedia and museum APIs: fetches information
- Travel tools → Poster generation: includes
- Poster generation → Imagen: generates artwork
- Travel tools → Destination video: includes
- Destination video → Gemini Omni: generates preview
- Concierge agent → Traveler memory: records preferences
- Traveler memory → Vertex AI Memory Bank: stores memories
- Local FastAPI app → Shared session and artifact services: gets services
- Reasoning adapter → Shared session and artifact services: gets services
- Shared session and artifact services → Session service: provides sessions
- Shared session and artifact services → Artifact service: provides artifacts
- Artifact service → Cloud Storage: stores artifacts
- Concierge agent → Python execution sandbox: executes Python