# andreaspr/ai-travel-agent architecture

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

- Interactive diagram: https://gitdiagram.com/andreaspr/ai-travel-agent
- Repository: https://github.com/andreaspr/ai-travel-agent

## Overview

AI Travel Agent is a web-based, grounded trip-planning product. Users authenticate and submit conversational requests; the backend runs a bounded planning loop, invokes tools and retrieval, and returns itinerary responses for display. Its principal domain stages are planning, destination retrieval, inventory/tool queries, and itinerary persistence/versioning. The repository also includes model routing, authentication, safety, and observability layers. Some frontend and API wiring is unsampled, so those links are omitted or marked unverified rather than inferred.

Main entry points: [`backend/agent/loop.py`](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/loop.py) (Planning loop), [`backend/main.py`](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/main.py) (FastAPI app), [`backend/db/models.py`](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/db/models.py) (PostgreSQL models), [`backend/tools/runtime.py`](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/runtime.py) (Tool runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webchat["Chat interface<br/>[ChatApp.jsx]"]
  node_tripview["Trip displays<br/>[ItineraryCard.jsx]"]
  node_authui["Auth forms<br/>[AuthForm.jsx]"]
end

subgraph group_api["API and identity"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_authapi["Auth endpoints<br/>[api.py]"]
  node_authsvc["Auth service<br/>[service.py]"]
  node_agentapi["Chat endpoints<br/>[api.py]"]
end

subgraph group_planning["Trip planning"]
  node_agentloop["Planning loop<br/>[loop.py]"]
  node_agentcontext["Context builder<br/>[context.py]"]
  node_agentpolicy["Planning policy<br/>[policy.py]"]
  node_agentmodels["Trip contracts<br/>[models.py]"]
  node_agentstore["Itinerary versions<br/>[store.py]"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_toolruntime["Tool runtime<br/>[runtime.py]"]
  node_toolhandlers["Tool handlers<br/>[handlers.py]"]
  node_toolcontracts["Tool contracts<br/>[models.py]"]
  node_ragsearch["Grounded search<br/>[search.py]"]
  node_ragingest["Knowledge ingestion<br/>[ingest.py]"]
end

subgraph group_platform["Runtime services"]
  node_llmrouter["Model router<br/>[router.py]"]
  node_database[("PostgreSQL models<br/>[models.py]")]
  node_dbconnect["DB connection<br/>[connect.py]"]
  node_safety["Content safety<br/>[content.py]"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
end

node_traveler(("Traveler"))

node_traveler -->|"requests a trip"| node_webchat
node_traveler -->|"authenticates"| node_authui
node_webchat -.->|"submits chat"| node_agentapi
node_agentapi -.->|"runs planning"| node_agentloop
node_agentloop -->|"builds context"| node_agentcontext
node_agentloop -->|"checks policy"| node_agentpolicy
node_agentloop -->|"uses contracts"| node_agentmodels
node_agentloop -->|"requests generation"| node_llmrouter
node_agentloop -->|"dispatches tools"| node_toolruntime
node_agentloop -->|"persists versions"| node_agentstore
node_agentloop -->|"cleans content"| node_safety
node_toolruntime -->|"dispatches calls"| node_toolhandlers
node_toolruntime -->|"validates results"| node_toolcontracts
node_toolhandlers -->|"uses contracts"| node_toolcontracts
node_toolhandlers -->|"searches destinations"| node_ragsearch
node_ragsearch -->|"queries chunks"| node_database
node_ragingest -->|"stores documents"| node_database
node_agentstore -->|"reads and writes"| node_database
node_toolruntime -->|"uses persistence"| node_database
node_authapi -->|"calls service"| node_authsvc
node_authsvc -->|"reads and writes"| node_database
node_backend -->|"registers router"| node_agentapi
node_backend -->|"registers router"| node_authapi
node_backend -->|"serves search"| node_ragsearch
node_backend -->|"uses sessions"| node_dbconnect
node_dbconnect -->|"connects models"| node_database
node_llmrouter -->|"records model events"| node_telemetry
node_backend -->|"instruments app"| node_telemetry
node_authui -.->|"provides login state"| node_webchat
node_webchat -.->|"renders itinerary"| node_tripview

click node_webchat "https://github.com/andreaspr/ai-travel-agent/blob/master/src/components/ChatApp.jsx"
click node_tripview "https://github.com/andreaspr/ai-travel-agent/blob/master/src/components/ItineraryCard.jsx"
click node_authui "https://github.com/andreaspr/ai-travel-agent/blob/master/src/components/AuthForm.jsx"
click node_backend "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/main.py"
click node_authapi "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/auth/api.py"
click node_authsvc "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/auth/service.py"
click node_agentapi "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/api.py"
click node_agentloop "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/loop.py"
click node_agentcontext "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/context.py"
click node_agentpolicy "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/policy.py"
click node_agentmodels "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/models.py"
click node_agentstore "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/store.py"
click node_llmrouter "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/llm/router.py"
click node_toolruntime "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/runtime.py"
click node_toolhandlers "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/handlers.py"
click node_toolcontracts "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/models.py"
click node_ragsearch "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/rag/search.py"
click node_ragingest "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/rag/ingest.py"
click node_database "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/db/models.py"
click node_dbconnect "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/db/connect.py"
click node_safety "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/security/content.py"
click node_telemetry "https://github.com/andreaspr/ai-travel-agent/blob/master/backend/observability/telemetry.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_webchat,node_tripview,node_authui toneBlue
class node_backend,node_authapi,node_authsvc,node_agentapi toneAmber
class node_agentloop,node_agentcontext,node_agentpolicy,node_agentmodels,node_agentstore toneMint
class node_toolruntime,node_toolhandlers,node_toolcontracts,node_ragsearch,node_ragingest toneRose
class node_llmrouter,node_database,node_dbconnect,node_safety,node_telemetry,node_traveler toneIndigo
```

## Components

### Web experience

- [Chat interface](https://github.com/andreaspr/ai-travel-agent/blob/master/src/components/ChatApp.jsx): `src/components/ChatApp.jsx`
- [Trip displays](https://github.com/andreaspr/ai-travel-agent/blob/master/src/components/ItineraryCard.jsx): `src/components/ItineraryCard.jsx`
- [Auth forms](https://github.com/andreaspr/ai-travel-agent/blob/master/src/components/AuthForm.jsx): `src/components/AuthForm.jsx`

### API and identity

- [FastAPI app](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/main.py): `backend/main.py`
- [Auth endpoints](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/auth/api.py): `backend/auth/api.py`
- [Auth service](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/auth/service.py): `backend/auth/service.py`
- [Chat endpoints](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/api.py): `backend/agent/api.py`

### Trip planning

- [Planning loop](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/loop.py): `backend/agent/loop.py`
- [Context builder](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/context.py): `backend/agent/context.py`
- [Planning policy](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/policy.py): `backend/agent/policy.py`
- [Trip contracts](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/models.py): `backend/agent/models.py`
- [Itinerary versions](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/agent/store.py): `backend/agent/store.py`

### Knowledge and tools

- [Tool runtime](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/runtime.py): `backend/tools/runtime.py`
- [Tool handlers](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/handlers.py): `backend/tools/handlers.py`
- [Tool contracts](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/tools/models.py): `backend/tools/models.py`
- [Grounded search](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/rag/search.py): `backend/rag/search.py`
- [Knowledge ingestion](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/rag/ingest.py): `backend/rag/ingest.py`

### Runtime services

- [Model router](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/llm/router.py): `backend/llm/router.py`
- [PostgreSQL models](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/db/models.py): `backend/db/models.py`
- [DB connection](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/db/connect.py): `backend/db/connect.py`
- [Content safety](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/security/content.py): `backend/security/content.py`
- [Telemetry](https://github.com/andreaspr/ai-travel-agent/blob/master/backend/observability/telemetry.py): `backend/observability/telemetry.py`

### Other components

- **Traveler**

## Connections

- Traveler → Chat interface: requests a trip (evidence: `README.md`)
- Traveler → Auth forms: authenticates (evidence: `README.md`)
- Chat interface → Chat endpoints: submits chat
- Chat endpoints → Planning loop: runs planning
- Planning loop → Context builder: builds context (evidence: `backend/agent/loop.py`)
- Planning loop → Planning policy: checks policy (evidence: `backend/agent/loop.py`)
- Planning loop → Trip contracts: uses contracts (evidence: `backend/agent/loop.py`)
- Planning loop → Model router: requests generation (evidence: `backend/agent/loop.py`)
- Planning loop → Tool runtime: dispatches tools (evidence: `backend/agent/loop.py`)
- Planning loop → Itinerary versions: persists versions (evidence: `backend/agent/loop.py`)
- Planning loop → Content safety: cleans content (evidence: `backend/agent/loop.py`)
- Tool runtime → Tool handlers: dispatches calls (evidence: `backend/tools/runtime.py`)
- Tool runtime → Tool contracts: validates results (evidence: `backend/tools/runtime.py`)
- Tool handlers → Tool contracts: uses contracts (evidence: `backend/tools/handlers.py`)
- Tool handlers → Grounded search: searches destinations (evidence: `backend/tools/handlers.py`)
- Grounded search → PostgreSQL models: queries chunks (evidence: `backend/rag/search.py`)
- Knowledge ingestion → PostgreSQL models: stores documents (evidence: `backend/rag/ingest.py`)
- Itinerary versions → PostgreSQL models: reads and writes (evidence: `backend/agent/store.py`)
- Tool runtime → PostgreSQL models: uses persistence (evidence: `backend/tools/runtime.py`)
- Auth endpoints → Auth service: calls service (evidence: `backend/auth/api.py`)
- Auth service → PostgreSQL models: reads and writes (evidence: `backend/auth/service.py`)
- FastAPI app → Chat endpoints: registers router (evidence: `backend/main.py`)
- FastAPI app → Auth endpoints: registers router (evidence: `backend/main.py`)
- FastAPI app → Grounded search: serves search (evidence: `backend/main.py`)
- FastAPI app → DB connection: uses sessions (evidence: `backend/main.py`)
- DB connection → PostgreSQL models: connects models (evidence: `backend/db/connect.py`)
- Model router → Telemetry: records model events (evidence: `backend/llm/router.py`)
- FastAPI app → Telemetry: instruments app (evidence: `backend/main.py`)
- Auth forms → Chat interface: provides login state
- Chat interface → Trip displays: renders itinerary
