# saiphanindar2007/voyagegenie architecture

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

- Interactive diagram: https://gitdiagram.com/saiphanindar2007/voyagegenie
- Repository: https://github.com/saiphanindar2007/voyagegenie

## Overview

VoyageGenie is a conversational travel copilot that turns traveller preferences into a priced, multi-product itinerary, validates availability and price, and supports booking and post-booking actions. The frontend provides account access, a dashboard and trip conversation; the backend authenticates and persists trip state, then coordinates intent, itinerary, pricing and booking agents. Supplier adapters distinguish live Amadeus flight searches from simulated products and operations. The graph includes documented cancellation, modification and voucher capabilities; their detailed implementations were not all sampled, so some links are intentionally unverified.

Main entry points: [`backend/app/agents/orchestrator.py`](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/orchestrator.py) (Turn orchestrator), [`backend/app/services/supplier_adapter.py`](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/supplier_adapter.py) (Supplier adapter), [`backend/app/models.py`](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/models.py) (Trip and booking records), [`backend/app/main.py`](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Traveller experience"]
  node_auth_ui["Login and register<br/>[page.tsx]"]
  node_dashboard["Trip dashboard<br/>[page.tsx]"]
  node_chat_ui["Trip conversation<br/>[ChatWindow.tsx]"]
  node_itinerary_ui["Itinerary panel<br/>[ItineraryPanel.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_session["Session management<br/>[auth.ts]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth endpoints<br/>[auth.py]"]
  node_trip_routes["Trip endpoints<br/>[trips.py]"]
  node_chat_routes["Chat endpoint<br/>[chat.py]"]
  node_access_control["Trip ownership<br/>[dependencies.py]"]
end

subgraph group_agents["Travel workflow"]
  node_orchestrator["Turn orchestrator<br/>[orchestrator.py]"]
  node_intent["Intent extraction<br/>[llm_client.py]"]
  node_itinerary["Itinerary generation<br/>[itinerary_agent.py]"]
  node_pricing["Price validation<br/>[pricing_agent.py]"]
  node_booking["Booking<br/>[booking_agent.py]"]
  node_aftercare["Trip aftercare<br/>[support_agent.py]"]
  node_modification["Trip modification"]
end

subgraph group_integrations["Suppliers and records"]
  node_supplier_adapter["Supplier adapter"]
  node_mock_supplier["Mock travel supplier<br/>[mock_travel_api.py]"]
  node_voucher["PDF vouchers<br/>[voucher_service.py]"]
  node_domain["Trip and booking records<br/>[models.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

node_traveller(("Traveller"))
node_live_flights["Amadeus flights"]

node_traveller -->|"registers or logs in"| node_auth_ui
node_traveller -->|"manages trips"| node_dashboard
node_dashboard -->|"opens trip"| node_chat_ui
node_chat_ui -->|"sends requests"| node_api_client
node_dashboard -->|"loads trips"| node_api_client
node_api_client -->|"uses tokens"| node_session
node_api_client -.->|"calls API"| node_app
node_app -->|"registers routes"| node_auth_routes
node_app -->|"registers routes"| node_chat_routes
node_app -->|"registers routes"| node_trip_routes
node_auth_routes -->|"uses authentication"| node_access_control
node_chat_routes -->|"checks ownership"| node_access_control
node_trip_routes -->|"checks ownership"| node_access_control
node_chat_routes -->|"handles turns"| node_orchestrator
node_orchestrator -->|"extracts intent"| node_intent
node_orchestrator -->|"builds itinerary"| node_itinerary
node_orchestrator -->|"revalidates prices"| node_pricing
node_orchestrator -->|"confirms booking"| node_booking
node_orchestrator -->|"dispatches support"| node_aftercare
node_aftercare -->|"delegates changes"| node_modification
node_itinerary -->|"searches products"| node_supplier_adapter
node_pricing -->|"checks availability"| node_supplier_adapter
node_booking -->|"books products"| node_supplier_adapter
node_supplier_adapter -->|"delegates searches"| node_mock_supplier
node_supplier_adapter -.->|"searches flights"| node_live_flights
node_booking -->|"generates vouchers"| node_voucher
node_trip_routes -->|"serves downloads"| node_voucher
node_itinerary -->|"updates trip items"| node_domain
node_booking -->|"records bookings"| node_domain
node_chat_routes -->|"persists conversation"| node_domain
node_trip_routes -->|"updates trip state"| node_domain
node_domain -->|"stores records"| node_database
node_modification -.->|"modifies bookings"| node_supplier_adapter

click node_auth_ui "https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/login/page.tsx"
click node_dashboard "https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/dashboard/page.tsx"
click node_chat_ui "https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/components/ChatWindow.tsx"
click node_itinerary_ui "https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/components/ItineraryPanel.tsx"
click node_api_client "https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/lib/api.ts"
click node_session "https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/lib/auth.ts"
click node_app "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/routers/auth.py"
click node_trip_routes "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/routers/trips.py"
click node_chat_routes "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/routers/chat.py"
click node_access_control "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/dependencies.py"
click node_orchestrator "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/orchestrator.py"
click node_intent "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/llm_client.py"
click node_itinerary "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/itinerary_agent.py"
click node_pricing "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/pricing_agent.py"
click node_booking "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/booking_agent.py"
click node_aftercare "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/support_agent.py"
click node_modification "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/modification_agent.py"
click node_supplier_adapter "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/supplier_adapter.py"
click node_mock_supplier "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/mock_travel_api.py"
click node_voucher "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/voucher_service.py"
click node_domain "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/models.py"
click node_database "https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/database.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_auth_ui,node_dashboard,node_chat_ui,node_itinerary_ui,node_api_client,node_session toneBlue
class node_app,node_auth_routes,node_trip_routes,node_chat_routes,node_access_control toneAmber
class node_orchestrator,node_intent,node_itinerary,node_pricing,node_booking,node_aftercare,node_modification toneMint
class node_supplier_adapter,node_mock_supplier,node_voucher,node_domain,node_database toneRose
class node_traveller,node_live_flights toneIndigo
```

## Components

### Traveller experience

- [Login and register](https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Trip dashboard](https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Trip conversation](https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/components/ChatWindow.tsx): `frontend/app/components/ChatWindow.tsx`
- [Itinerary panel](https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/components/ItineraryPanel.tsx): `frontend/app/components/ItineraryPanel.tsx`
- [API client](https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/lib/api.ts): `frontend/app/lib/api.ts`
- [Session management](https://github.com/saiphanindar2007/voyagegenie/blob/main/frontend/app/lib/auth.ts): `frontend/app/lib/auth.ts`

### API and identity

- [FastAPI application](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth endpoints](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Trip endpoints](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/routers/trips.py): `backend/app/routers/trips.py`
- [Chat endpoint](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Trip ownership](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`

### Travel workflow

- [Turn orchestrator](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Intent extraction](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/llm_client.py): `backend/app/services/llm_client.py`
- [Itinerary generation](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/itinerary_agent.py): `backend/app/agents/itinerary_agent.py`
- [Price validation](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/pricing_agent.py): `backend/app/agents/pricing_agent.py`
- [Booking](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/booking_agent.py): `backend/app/agents/booking_agent.py`
- [Trip aftercare](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/support_agent.py): `backend/app/agents/support_agent.py`
- [Trip modification](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/agents/modification_agent.py): `backend/app/agents/modification_agent.py`

### Suppliers and records

- [Supplier adapter](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/supplier_adapter.py): `backend/app/services/supplier_adapter.py`
- [Mock travel supplier](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/mock_travel_api.py): `backend/app/services/mock_travel_api.py`
- [PDF vouchers](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/services/voucher_service.py): `backend/app/services/voucher_service.py`
- [Trip and booking records](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/models.py): `backend/app/models.py`
- [SQL database](https://github.com/saiphanindar2007/voyagegenie/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Traveller**
- **Amadeus flights**

## Connections

- Traveller → Login and register: registers or logs in
- Traveller → Trip dashboard: manages trips
- Trip dashboard → Trip conversation: opens trip
- Trip conversation → API client: sends requests (evidence: `frontend/app/components/ChatWindow.tsx`)
- Trip dashboard → API client: loads trips (evidence: `frontend/app/dashboard/page.tsx`)
- API client → Session management: uses tokens (evidence: `frontend/app/lib/api.ts`)
- API client → FastAPI application: calls API
- FastAPI application → Auth endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Chat endpoint: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Trip endpoints: registers routes (evidence: `backend/app/main.py`)
- Auth endpoints → Trip ownership: uses authentication (evidence: `backend/app/routers/auth.py`)
- Chat endpoint → Trip ownership: checks ownership (evidence: `backend/app/routers/chat.py`)
- Trip endpoints → Trip ownership: checks ownership (evidence: `backend/app/routers/trips.py`)
- Chat endpoint → Turn orchestrator: handles turns (evidence: `backend/app/routers/chat.py`)
- Turn orchestrator → Intent extraction: extracts intent (evidence: `backend/app/agents/orchestrator.py`)
- Turn orchestrator → Itinerary generation: builds itinerary (evidence: `backend/app/agents/orchestrator.py`)
- Turn orchestrator → Price validation: revalidates prices (evidence: `backend/app/agents/orchestrator.py`)
- Turn orchestrator → Booking: confirms booking (evidence: `backend/app/agents/orchestrator.py`)
- Turn orchestrator → Trip aftercare: dispatches support (evidence: `backend/app/agents/orchestrator.py`)
- Trip aftercare → Trip modification: delegates changes (evidence: `backend/app/agents/support_agent.py`)
- Itinerary generation → Supplier adapter: searches products (evidence: `backend/app/agents/itinerary_agent.py`)
- Price validation → Supplier adapter: checks availability (evidence: `backend/app/agents/pricing_agent.py`)
- Booking → Supplier adapter: books products (evidence: `backend/app/agents/booking_agent.py`)
- Supplier adapter → Mock travel supplier: delegates searches (evidence: `backend/app/services/supplier_adapter.py`)
- Supplier adapter → Amadeus flights: searches flights
- Booking → PDF vouchers: generates vouchers (evidence: `backend/app/agents/booking_agent.py`)
- Trip endpoints → PDF vouchers: serves downloads (evidence: `backend/app/routers/trips.py`)
- Itinerary generation → Trip and booking records: updates trip items (evidence: `backend/app/agents/itinerary_agent.py`)
- Booking → Trip and booking records: records bookings (evidence: `backend/app/agents/booking_agent.py`)
- Chat endpoint → Trip and booking records: persists conversation (evidence: `backend/app/routers/chat.py`)
- Trip endpoints → Trip and booking records: updates trip state (evidence: `backend/app/routers/trips.py`)
- Trip and booking records → SQL database: stores records (evidence: `backend/app/models.py`)
- Trip modification → Supplier adapter: modifies bookings
