# ronnyml/ai-travel-agent architecture

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

## Overview

AI Travel Agent turns a destination search into a live, structured travel guide: the frontend starts a session, shows agent progress and streamed content, then presents the completed guide and supports follow-up questions. The README documents research, photo gathering, synthesis, persistence, and follow-up capabilities; unsampled implementation details are represented only where the documented architecture supports them.

Main entry points: [`frontend/src/lib/api.ts`](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/lib/api.ts) (API client), [`backend/app/api/travel.py`](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/api/travel.py) (Travel sessions), [`backend/app/agents/supervisor.py`](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/supervisor.py) (Pipeline supervisor), [`frontend/src/pages/Session.tsx`](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/pages/Session.tsx) (Live progress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_search_ui["Destination search<br/>[SearchBar.tsx]"]
  node_travel_hook["Session launcher<br/>[useTravel.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_session_store["Session state<br/>[session.ts]"]
  node_session_page["Live progress<br/>[Session.tsx]"]
  node_sse_hook["Event stream<br/>[useSSE.ts]"]
  node_guide_page["Guide page<br/>[Guide.tsx]"]
  node_guide_sections["Guide sections"]
  node_followup_ui["Follow-up chat<br/>[FollowUpChat.tsx]"]
end

subgraph group_api["Session and guide API"]
  node_api_app["API application<br/>[main.py]"]
  node_travel_api["Travel sessions<br/>[travel.py]"]
  node_guides_api["Guide and follow-up<br/>[guides.py]"]
  node_event_model["Travel events<br/>[events.py]"]
end

subgraph group_agents["Research and guide generation"]
  node_supervisor["Pipeline supervisor<br/>[supervisor.py]"]
  node_search_agent["Web research<br/>[search_agent.py]"]
  node_photo_stage["Photo gathering"]
  node_synthesis["Guide synthesis<br/>[synthesis_agent.py]"]
  node_photo_service["Photo service<br/>[photos.py]"]
end

subgraph group_knowledge["Retrieval and persistence"]
  node_retriever["Category retrieval<br/>[retriever.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_db_client["Supabase access<br/>[client.py]"]
end

subgraph group_integrations["External services"]
  node_supabase[("Supabase pgvector")]
  node_tavily["Tavily search"]
  node_voyage["Voyage AI"]
  node_claude["Claude"]
  node_unsplash["Unsplash photos"]
  node_picsum["Picsum fallback"]
end

node_traveler(("Traveler"))

node_traveler -->|"enters destination"| node_search_ui
node_search_ui -->|"submits search"| node_travel_hook
node_travel_hook -->|"starts session"| node_api_client
node_travel_hook -->|"sets session state"| node_session_store
node_api_client -->|"requests session"| node_travel_api
node_travel_api -->|"launches pipeline"| node_supervisor
node_api_app -->|"registers routes"| node_travel_api
node_api_app -->|"registers routes"| node_guides_api
node_supervisor -->|"dispatches research"| node_search_agent
node_supervisor -->|"dispatches photos"| node_photo_stage
node_supervisor -->|"dispatches synthesis"| node_synthesis
node_search_agent -->|"searches web"| node_tavily
node_photo_stage -->|"gets photos"| node_photo_service
node_synthesis -->|"generates guide"| node_claude
node_synthesis -.->|"retrieves context"| node_retriever
node_retriever -->|"embeds queries"| node_embeddings
node_embeddings -->|"requests vectors"| node_voyage
node_retriever -->|"matches chunks"| node_db_client
node_db_client -->|"queries and stores"| node_supabase
node_photo_service -->|"searches photos"| node_unsplash
node_photo_service -.->|"falls back to"| node_picsum
node_travel_api -->|"emits progress"| node_event_model
node_travel_api -->|"streams events"| node_sse_hook
node_session_page -->|"opens stream"| node_sse_hook
node_sse_hook -->|"adds events"| node_session_store
node_session_page -->|"checks session"| node_api_client
node_session_page -->|"navigates when ready"| node_guide_page
node_traveler -->|"asks follow-up"| node_followup_ui
node_followup_ui -->|"sends question"| node_api_client
node_api_client -->|"loads guide or asks"| node_guides_api
node_guides_api -->|"reads and writes guide"| node_db_client
node_guide_page -->|"loads guide"| node_api_client
node_guide_page -->|"renders guide"| node_guide_sections

click node_search_ui "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/components/SearchBar.tsx"
click node_travel_hook "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/hooks/useTravel.ts"
click node_api_client "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/lib/api.ts"
click node_session_store "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/store/session.ts"
click node_session_page "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/pages/Session.tsx"
click node_sse_hook "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/hooks/useSSE.ts"
click node_guide_page "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/pages/Guide.tsx"
click node_guide_sections "https://github.com/ronnyml/ai-travel-agent/tree/main/frontend/src/components"
click node_followup_ui "https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/components/FollowUpChat.tsx"
click node_api_app "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/main.py"
click node_travel_api "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/api/travel.py"
click node_guides_api "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/api/guides.py"
click node_event_model "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/core/events.py"
click node_supervisor "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/supervisor.py"
click node_search_agent "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/search_agent.py"
click node_photo_stage "https://github.com/ronnyml/ai-travel-agent/tree/main/backend/app/agents"
click node_synthesis "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/synthesis_agent.py"
click node_photo_service "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/services/photos.py"
click node_retriever "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/rag/retriever.py"
click node_embeddings "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/rag/embeddings.py"
click node_db_client "https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/db/client.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_search_ui,node_travel_hook,node_api_client,node_session_store,node_session_page,node_sse_hook,node_guide_page,node_guide_sections,node_followup_ui toneBlue
class node_api_app,node_travel_api,node_guides_api,node_event_model toneAmber
class node_supervisor,node_search_agent,node_photo_stage,node_synthesis,node_photo_service toneMint
class node_retriever,node_embeddings,node_db_client toneRose
class node_supabase,node_tavily,node_voyage,node_claude,node_unsplash,node_picsum,node_traveler toneIndigo
```

## Components

### Frontend experience

- [Destination search](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/components/SearchBar.tsx): `frontend/src/components/SearchBar.tsx`
- [Session launcher](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/hooks/useTravel.ts): `frontend/src/hooks/useTravel.ts`
- [API client](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Session state](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/store/session.ts): `frontend/src/store/session.ts`
- [Live progress](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/pages/Session.tsx): `frontend/src/pages/Session.tsx`
- [Event stream](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/hooks/useSSE.ts): `frontend/src/hooks/useSSE.ts`
- [Guide page](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/pages/Guide.tsx): `frontend/src/pages/Guide.tsx`
- [Guide sections](https://github.com/ronnyml/ai-travel-agent/tree/main/frontend/src/components): `frontend/src/components`
- [Follow-up chat](https://github.com/ronnyml/ai-travel-agent/blob/main/frontend/src/components/FollowUpChat.tsx): `frontend/src/components/FollowUpChat.tsx`

### Session and guide API

- [API application](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Travel sessions](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/api/travel.py): `backend/app/api/travel.py`
- [Guide and follow-up](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/api/guides.py): `backend/app/api/guides.py`
- [Travel events](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/core/events.py): `backend/app/core/events.py`

### Research and guide generation

- [Pipeline supervisor](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/supervisor.py): `backend/app/agents/supervisor.py`
- [Web research](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/search_agent.py): `backend/app/agents/search_agent.py`
- [Photo gathering](https://github.com/ronnyml/ai-travel-agent/tree/main/backend/app/agents): `backend/app/agents`
- [Guide synthesis](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/agents/synthesis_agent.py): `backend/app/agents/synthesis_agent.py`
- [Photo service](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/services/photos.py): `backend/app/services/photos.py`

### Retrieval and persistence

- [Category retrieval](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Text embeddings](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/rag/embeddings.py): `backend/app/rag/embeddings.py`
- [Supabase access](https://github.com/ronnyml/ai-travel-agent/blob/main/backend/app/db/client.py): `backend/app/db/client.py`

### External services

- **Supabase pgvector**
- **Tavily search**
- **Voyage AI**
- **Claude**
- **Unsplash photos**
- **Picsum fallback**

### Other components

- **Traveler**

## Connections

- Traveler → Destination search: enters destination
- Destination search → Session launcher: submits search
- Session launcher → API client: starts session
- Session launcher → Session state: sets session state
- API client → Travel sessions: requests session
- Travel sessions → Pipeline supervisor: launches pipeline
- API application → Travel sessions: registers routes
- API application → Guide and follow-up: registers routes
- Pipeline supervisor → Web research: dispatches research
- Pipeline supervisor → Photo gathering: dispatches photos
- Pipeline supervisor → Guide synthesis: dispatches synthesis
- Web research → Tavily search: searches web
- Photo gathering → Photo service: gets photos
- Guide synthesis → Claude: generates guide
- Guide synthesis → Category retrieval: retrieves context
- Category retrieval → Text embeddings: embeds queries
- Text embeddings → Voyage AI: requests vectors
- Category retrieval → Supabase access: matches chunks
- Supabase access → Supabase pgvector: queries and stores
- Photo service → Unsplash photos: searches photos
- Photo service → Picsum fallback: falls back to
- Travel sessions → Travel events: emits progress
- Travel sessions → Event stream: streams events
- Live progress → Event stream: opens stream
- Event stream → Session state: adds events
- Live progress → API client: checks session
- Live progress → Guide page: navigates when ready
- Traveler → Follow-up chat: asks follow-up
- Follow-up chat → API client: sends question
- API client → Guide and follow-up: loads guide or asks
- Guide and follow-up → Supabase access: reads and writes guide
- Guide page → API client: loads guide
- Guide page → Guide sections: renders guide