# abdelrahmanmostafa33/tourmate-ai architecture

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

- Interactive diagram: https://gitdiagram.com/abdelrahmanmostafa33/tourmate-ai
- Repository: https://github.com/abdelrahmanmostafa33/tourmate-ai

## Overview

TourMate AI is a conversational travel-planning product: a traveler describes a trip, receives a personalized itinerary, revises or approves it, then can select flights or hotels and pay. The README documents the six-stage itinerary pipeline, multimodal preference input, behavioral profiling, real-time chat, independent flight and hotel selection, and booking/payment flows. The graph preserves those capabilities; many service implementations were not excerpted, so only documented or source-index-supported relationships are drawn.

Main entry points: [`backend/ai_engine/graph/graph_builder.py`](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/graph_builder.py) (Pipeline graph), [`backend/ai_engine/conversation/orchestrator.py`](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/orchestrator.py) (Conversation engine), [`backend/app/api/v1/routes/chat.py`](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/api/v1/routes/chat.py) (Chat API), [`backend/app/services/booking_service.py`](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/booking_service.py) (Booking and payments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_chat["Chat API<br/>[chat.py]"]
  node_conversation_engine["Conversation engine<br/>[orchestrator.py]"]
  node_message_interpreter["Message interpreter"]
  node_conversation_state["Conversation state"]
  node_redis[("Redis sessions<br/>[redis_memory.py]")]
  node_vision["Image analysis"]
end

subgraph group_planning["Itinerary planning"]
  node_graph["Pipeline graph<br/>[graph_builder.py]"]
  node_graph_state["Pipeline state<br/>[state.py]"]
  node_profile_loader["Profile loader<br/>[nodes.py]"]
  node_place_retriever["Place retriever<br/>[place_retriever.py]"]
  node_candidate_scorer["Candidate scorer"]
  node_planner["Planning agent<br/>[planning_agent.py]"]
  node_route_optimizer["Route optimizer<br/>[route_optimizer.py]"]
  node_validator["Itinerary validator"]
  node_osrm["OSRM routing"]
end

subgraph group_discovery["Travel discovery"]
  node_places[("Place catalog<br/>[place_repo.py]")]
  node_flights["Flight search<br/>[flight_service.py]"]
  node_hotels["Hotel selection"]
  node_itinerary_editing["Itinerary editing"]
  node_amadeus["Amadeus"]
end

subgraph group_booking["Booking and payment"]
  node_booking_service["Booking and payments<br/>[booking_service.py]"]
  node_stripe["Stripe"]
  node_webhooks["Payment webhooks<br/>[webhooks.py]"]
end

subgraph group_platform["Backend platform"]
  node_api["API application<br/>[main.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_chat_persistence["Chat persistence<br/>[chat_service.py]"]
end

node_traveler(("Traveler"))

node_api -->|"mounts routes"| node_chat
node_traveler -->|"sends trip requests"| node_chat
node_chat -.->|"handles conversation"| node_conversation_engine
node_conversation_engine -->|"interprets messages"| node_message_interpreter
node_conversation_engine -->|"uses state"| node_conversation_state
node_conversation_engine -->|"persists sessions"| node_redis
node_conversation_engine -->|"invokes pipeline"| node_graph
node_conversation_engine -->|"analyzes images"| node_vision
node_graph -->|"uses state"| node_graph_state
node_graph -->|"runs stage"| node_profile_loader
node_graph -->|"runs stage"| node_place_retriever
node_graph -->|"runs stage"| node_candidate_scorer
node_graph -->|"runs stage"| node_planner
node_graph -->|"runs stage"| node_route_optimizer
node_graph -->|"runs stage"| node_validator
node_place_retriever -->|"retrieves places"| node_places
node_route_optimizer -->|"requests routes"| node_osrm
node_conversation_engine -->|"dispatches edits"| node_itinerary_editing
node_traveler -->|"searches flights"| node_flights
node_traveler -->|"selects hotels"| node_hotels
node_flights -->|"searches offers"| node_amadeus
node_traveler -->|"checks out"| node_booking_service
node_booking_service -->|"creates payment"| node_stripe
node_stripe -->|"sends events"| node_webhooks
node_webhooks -->|"dispatches events"| node_booking_service
node_api -->|"initializes tables"| node_database
node_chat_persistence -.->|"stores chat data"| node_database

click node_api "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/main.py"
click node_chat "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/api/v1/routes/chat.py"
click node_conversation_engine "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/orchestrator.py"
click node_message_interpreter "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/message_interpreter.py"
click node_conversation_state "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/conversation_state.py"
click node_redis "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/redis_memory.py"
click node_vision "https://github.com/abdelrahmanmostafa33/tourmate-ai/tree/main/backend/ai_engine/vision"
click node_graph "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/graph_builder.py"
click node_graph_state "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/state.py"
click node_profile_loader "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/nodes.py"
click node_place_retriever "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/place_retriever.py"
click node_candidate_scorer "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/candidate_scorer.py"
click node_planner "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/agents/planning_agent.py"
click node_route_optimizer "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/route_optimizer.py"
click node_validator "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/itinerary_validator.py"
click node_places "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/repositories/place_repo.py"
click node_flights "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/flight_service.py"
click node_hotels "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/agents/hotel_selection_agent.py"
click node_itinerary_editing "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/agents/itinerary_modifier_agent.py"
click node_booking_service "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/booking_service.py"
click node_webhooks "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/api/v1/routes/webhooks.py"
click node_database "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/core/database.py"
click node_chat_persistence "https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/chat_service.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,node_conversation_engine,node_message_interpreter,node_conversation_state,node_redis,node_vision toneBlue
class node_graph,node_graph_state,node_profile_loader,node_place_retriever,node_candidate_scorer,node_planner,node_route_optimizer,node_validator,node_osrm toneAmber
class node_places,node_flights,node_hotels,node_itinerary_editing,node_amadeus toneMint
class node_booking_service,node_stripe,node_webhooks toneRose
class node_api,node_database,node_chat_persistence,node_traveler toneIndigo
```

## Components

### Conversation

- [Chat API](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/api/v1/routes/chat.py): `backend/app/api/v1/routes/chat.py`
- [Conversation engine](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/orchestrator.py): `backend/ai_engine/conversation/orchestrator.py`
- [Message interpreter](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/message_interpreter.py): `backend/ai_engine/conversation/message_interpreter.py`
- [Conversation state](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/conversation_state.py): `backend/ai_engine/conversation/conversation_state.py`
- [Redis sessions](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/conversation/redis_memory.py): `backend/ai_engine/conversation/redis_memory.py`
- [Image analysis](https://github.com/abdelrahmanmostafa33/tourmate-ai/tree/main/backend/ai_engine/vision): `backend/ai_engine/vision`

### Itinerary planning

- [Pipeline graph](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/graph_builder.py): `backend/ai_engine/graph/graph_builder.py`
- [Pipeline state](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/state.py): `backend/ai_engine/graph/state.py`
- [Profile loader](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/graph/nodes.py): `backend/ai_engine/graph/nodes.py`
- [Place retriever](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/place_retriever.py): `backend/ai_engine/services/place_retriever.py`
- [Candidate scorer](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/candidate_scorer.py): `backend/ai_engine/services/candidate_scorer.py`
- [Planning agent](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/agents/planning_agent.py): `backend/ai_engine/agents/planning_agent.py`
- [Route optimizer](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/route_optimizer.py): `backend/ai_engine/services/route_optimizer.py`
- [Itinerary validator](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/services/itinerary_validator.py): `backend/ai_engine/services/itinerary_validator.py`
- **OSRM routing**

### Travel discovery

- [Place catalog](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/repositories/place_repo.py): `backend/app/repositories/place_repo.py`
- [Flight search](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/flight_service.py): `backend/app/services/flight_service.py`
- [Hotel selection](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/agents/hotel_selection_agent.py): `backend/ai_engine/agents/hotel_selection_agent.py`
- [Itinerary editing](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/ai_engine/agents/itinerary_modifier_agent.py): `backend/ai_engine/agents/itinerary_modifier_agent.py`
- **Amadeus**

### Booking and payment

- [Booking and payments](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/booking_service.py): `backend/app/services/booking_service.py`
- **Stripe**
- [Payment webhooks](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/api/v1/routes/webhooks.py): `backend/app/api/v1/routes/webhooks.py`

### Backend platform

- [API application](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [PostgreSQL](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Chat persistence](https://github.com/abdelrahmanmostafa33/tourmate-ai/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`

### Other components

- **Traveler**

## Connections

- API application → Chat API: mounts routes (evidence: `backend/app/main.py`)
- Traveler → Chat API: sends trip requests
- Chat API → Conversation engine: handles conversation
- Conversation engine → Message interpreter: interprets messages (evidence: `backend/ai_engine/conversation/orchestrator.py`)
- Conversation engine → Conversation state: uses state (evidence: `backend/ai_engine/conversation/orchestrator.py`)
- Conversation engine → Redis sessions: persists sessions (evidence: `backend/ai_engine/conversation/orchestrator.py`)
- Conversation engine → Pipeline graph: invokes pipeline (evidence: `backend/ai_engine/conversation/orchestrator.py`)
- Conversation engine → Image analysis: analyzes images (evidence: `backend/ai_engine/conversation/orchestrator.py`)
- Pipeline graph → Pipeline state: uses state (evidence: `backend/ai_engine/graph/graph_builder.py`)
- Pipeline graph → Profile loader: runs stage (evidence: `backend/ai_engine/graph/graph_builder.py`)
- Pipeline graph → Place retriever: runs stage
- Pipeline graph → Candidate scorer: runs stage
- Pipeline graph → Planning agent: runs stage
- Pipeline graph → Route optimizer: runs stage
- Pipeline graph → Itinerary validator: runs stage
- Place retriever → Place catalog: retrieves places (evidence: `backend/ai_engine/services/place_retriever.py`)
- Route optimizer → OSRM routing: requests routes
- Conversation engine → Itinerary editing: dispatches edits (evidence: `backend/ai_engine/conversation/orchestrator.py`)
- Traveler → Flight search: searches flights
- Traveler → Hotel selection: selects hotels
- Flight search → Amadeus: searches offers
- Traveler → Booking and payments: checks out
- Booking and payments → Stripe: creates payment (evidence: `backend/app/services/booking_service.py`)
- Stripe → Payment webhooks: sends events (evidence: `backend/app/api/v1/routes/webhooks.py`)
- Payment webhooks → Booking and payments: dispatches events (evidence: `backend/app/api/v1/routes/webhooks.py`)
- API application → PostgreSQL: initializes tables (evidence: `backend/app/main.py`)
- Chat persistence → PostgreSQL: stores chat data
