TravelOS - Your travel operating system

Existing alternatives

• OTAs/metasearch: Expedia, Booking, Kayak, Google Flights.
• Travel management: Concur, Navan, Egencia.
• Point solutions: airline apps, hotel apps, TripIt, Hopper, lounge/transfer/activity apps.
• Chat assistants: generic LLM chatbots that can suggest but cannot reliably book/manage.

Why they are insufficient

• Fragmentation: users juggle multiple apps for flights/hotels/activities/dining/insurance/ground transport.
• Manual reconciliation: users compare options across tabs; no unified constraint solver for budget + preferences + schedule.
• Weak post-booking support: disruptions require waiting on airline/hotel support; rebooking is stressful and time-sensitive.
• No persistent preference execution: preferences exist in silos (airline profile vs hotel profile) and aren’t applied holistically.
• Corporate friction: policy compliance and approvals add steps; employees bypass tools.

Pain points

• Planning overhead: searching, comparing, coordinating.
• Hidden constraints: connection times, baggage rules, cancellation policies, resort fees.
• Disruption anxiety: missed connections, delays, last-minute changes.
• Refund complexity: partial refunds, credits, fare rules.
• Corporate: policy violations, lack of auditability, expense leakage.

Market inefficiencies

• Travel is workflow-heavy and exception-driven (changes/disruptions). Most tools optimize initial booking, not lifecycle management.
• Supplier APIs are inconsistent; users pay the integration tax manually.
• High-value users (frequent travelers, corporate) have repeatable preferences that are not leveraged to reduce friction.

Primary persona: Frequent leisure traveler

• Travels 3–8 times/year; values convenience and time savings.
• Comfortable with chat/voice interfaces; expects mobile-first.
• Will pay for premium support and disruption handling.

Secondary persona: Corporate traveler + travel manager

• Employee: wants frictionless booking and changes.
• Travel manager: needs policy compliance, approvals, reporting, and audit trails.
• Buying behavior: B2B SaaS evaluation (security, SSO, reporting), then rollout.

Technical maturity

• End users: low-to-medium; must be simple.
• Corporate admins: medium; expects integrations (SSO, HRIS, expense).

Buying behavior

• B2C: subscription + per-trip service fee; conversion driven by “first trip success”.
• B2B: per-seat pricing + transaction fees; procurement requires SOC2 roadmap, SSO, data retention controls.

MVP scope (buildable in 8–12 weeks)

Focus on one reliable booking vertical first (flights + hotels) with strong itinerary + post-booking monitoring. Activities/dining can be “recommendation-only” initially.

1) Conversational trip intake

• Chat UI (web) with structured extraction into a TripSpec:
• origin, destination(s), date range, flexibility, budget, cabin class, hotel star range, travelers count.
• Preference capture:
• seat preference, meal preference, hotel amenities, loyalty programs.

2) Agent orchestration (parallel)

• Concierge agent creates tasks:
• SearchFlights, SearchHotels, BuildBudget, AssembleItinerary.
• Each agent returns structured results with confidence + citations (API response IDs).

3) Search + quote

• Flights: integrate one aggregator API (e.g., Amadeus Self-Service or Duffel).
• Hotels: integrate one provider (e.g., Booking.com affiliate API / Expedia Rapid / Hotelbeds depending on access).
• Present top 3–5 options per category with filters.

4) Itinerary builder

• Combine selected flight + hotel into a single itinerary timeline.
• Budget breakdown:
• base fare, taxes/fees, baggage, hotel nightly + taxes/fees.

5) Booking + payment (in-chat)

• Stripe PaymentIntent for card payments.
• Store booking references (PNR, ticket numbers, hotel confirmation).
• Email receipt + downloadable itinerary PDF.

6) Post-booking monitoring (basic)

• Flight status monitoring via provider (e.g., FlightAware/Aviationstack) or aggregator.
• Alert user in chat/email when:
• delay > X minutes
• connection risk threshold exceeded
• “Propose alternatives” can be MVP-lite: show rebooking suggestions without auto-hold.

7) Corporate-lite dashboard (optional MVP)

• Admin view:
• list of trips, spend, policy flags (simple rules: max hotel nightly, cabin class).
• Audit log of agent actions.

Explicitly out of MVP

• True multi-supplier negotiation, seat map rendering for all carriers, crypto settlement, loyalty redemption automation, automated refunds.

High-level components

• Web Client: chat UI + itinerary viewer.
• API Backend: auth, trip state, orchestration, integrations.
• Agent Orchestrator: task graph execution, parallelism, retries, tool calling.
• Integration Layer: adapters for flight/hotel/search, booking, status monitoring.
• Data Store: relational DB for core entities; object storage for artifacts.
• Event Bus/Queue: async tasks (search, monitoring, notifications).
• Notification Service: email + optional SMS.

Deployment approach

• Start with a single-region deployment on a managed platform.
• Use background workers for agent tasks and monitoring.
• Separate secrets management and per-environment configs.

Mermaid diagram

flowchart LR
  U[User Web Chat] -->|HTTPS| FE[Next.js App]
  FE -->|JWT/Session| API[Backend API]

  API --> DB[(Postgres)]
  API --> OBJ[(Object Storage)]

  API --> Q[Queue/Event Bus]
  Q --> W[Worker Pool]

  W --> ORCH[Agent Orchestrator]
  ORCH --> LLM[LLM Provider]
  ORCH --> FL[Flight API Adapter]
  ORCH --> HT[Hotel API Adapter]
  ORCH --> PAY[Stripe]
  ORCH --> STAT[Flight Status API]

  W --> NOTIF[Email/SMS]
  NOTIF --> U

  API --> ADM[Admin Dashboard]

Key design choices

• State machine per trip: DRAFT -> QUOTED -> SELECTED -> BOOKED -> MONITORING -> COMPLETED/CANCELLED.
• Idempotent booking: booking endpoints must accept an idempotency key to avoid double charges.
• Tool-call boundaries: agents never directly call external APIs; they call backend tools that enforce validation, logging, and rate limits.

Core schema (Postgres)

users

CREATE TABLE users (
  id UUID PRIMARY KEY,
  email CITEXT UNIQUE NOT NULL,
  password_hash TEXT, -- if not using pure OAuth
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

user_profiles (preferences + identity)

CREATE TABLE user_profiles (
  user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
  full_name TEXT,
  phone TEXT,
  seat_pref TEXT, -- e.g., window/aisle
  meal_pref TEXT, -- vegetarian/vegan/etc
  hotel_amenities JSONB NOT NULL DEFAULT '{}',
  loyalty_programs JSONB NOT NULL DEFAULT '[]',
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_user_profiles_amenities ON user_profiles USING GIN (hotel_amenities);

trips

CREATE TABLE trips (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  title TEXT,
  status TEXT NOT NULL, -- DRAFT/QUOTED/BOOKED/...
  trip_spec JSONB NOT NULL, -- normalized constraints
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_trips_user_status ON trips(user_id, status);
CREATE INDEX idx_trips_spec_gin ON trips USING GIN (trip_spec);

conversations + messages (chat history)

CREATE TABLE conversations (
  id UUID PRIMARY KEY,
  trip_id UUID REFERENCES trips(id) ON DELETE CASCADE,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE messages (
  id UUID PRIMARY KEY,
  conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
  role TEXT NOT NULL, -- user/assistant/system/agent
  agent_name TEXT, -- concierge/flight/hotel/etc
  content TEXT NOT NULL,
  content_json JSONB, -- structured cards
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_messages_conv_time ON messages(conversation_id, created_at);

agent_tasks (orchestration)

CREATE TABLE agent_tasks (
  id UUID PRIMARY KEY,
  trip_id UUID NOT NULL REFERENCES trips(id) ON DELETE CASCADE,
  type TEXT NOT NULL, -- SearchFlights/SearchHotels/...
  status TEXT NOT NULL, -- PENDING/RUNNING/SUCCEEDED/FAILED
  input JSONB NOT NULL,
  output JSONB,
  error TEXT,
  started_at TIMESTAMPTZ,
  finished_at TIMESTAMPTZ
);
CREATE INDEX idx_agent_tasks_trip_type ON agent_tasks(trip_id, type);
CREATE INDEX idx_agent_tasks_status ON agent_tasks(status);

offers (flight/hotel quotes)

CREATE TABLE offers (
  id UUID PRIMARY KEY,
  trip_id UUID NOT NULL REFERENCES trips(id) ON DELETE CASCADE,
  provider TEXT NOT NULL, -- duffel/amadeus/expedia
  category TEXT NOT NULL, -- flight/hotel
  external_offer_id TEXT NOT NULL,
  price_total_cents INT NOT NULL,
  currency TEXT NOT NULL,
  details JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE(provider, external_offer_id)
);
CREATE INDEX idx_offers_trip_cat_price ON offers(trip_id, category, price_total_cents);
CREATE INDEX idx_offers_details_gin ON offers USING GIN (details);

bookings + payments

CREATE TABLE bookings (
  id UUID PRIMARY KEY,
  trip_id UUID NOT NULL REFERENCES trips(id) ON DELETE CASCADE,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  category TEXT NOT NULL, -- flight/hotel
  provider TEXT NOT NULL,
  external_booking_id TEXT,
  status TEXT NOT NULL, -- PENDING/CONFIRMED/CANCELLED
  pnr TEXT,
  confirmation_code TEXT,
  details JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_bookings_trip ON bookings(trip_id);

CREATE TABLE payments (
  id UUID PRIMARY KEY,
  booking_id UUID REFERENCES bookings(id) ON DELETE SET NULL,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  provider TEXT NOT NULL, -- stripe
  provider_payment_id TEXT NOT NULL,
  amount_cents INT NOT NULL,
  currency TEXT NOT NULL,
  status TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_payments_user_time ON payments(user_id, created_at);

monitoring_events

CREATE TABLE monitoring_events (
  id UUID PRIMARY KEY,
  trip_id UUID NOT NULL REFERENCES trips(id) ON DELETE CASCADE,
  booking_id UUID REFERENCES bookings(id) ON DELETE CASCADE,
  type TEXT NOT NULL, -- DELAY/MISCONNECT_RISK
  payload JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_monitoring_trip_time ON monitoring_events(trip_id, created_at);

Auth

• MVP: email magic link or OAuth (Google) + session cookies.
• API uses Authorization: Bearer <token> for programmatic calls; browser uses HttpOnly session cookie.

Core endpoints (REST)

Create trip

POST /v1/trips

{
  "title": "Beach vacation May",
  "trip_spec": {
    "origin": "NYC",
    "destination": "CUN",
    "date_start": "2026-05-10",
    "date_end": "2026-05-17",
    "budget_usd": 3000,
    "travelers": 2,
    "preferences": {"seat": "window", "meal": "vegetarian"}
  }
}

Response:

{ "id": "trip_uuid", "status": "DRAFT" }

Send chat message (streams assistant)

POST /v1/conversations/{conversationId}/messages

• Request:

{ "content": "I want a relaxing beach vacation in May, flying from NYC, budget around $3k" }

• Response: Server-Sent Events (SSE) stream with tokens + structured cards.

Trigger quote (agent orchestration)

POST /v1/trips/{tripId}/quote

• Starts parallel tasks; returns task IDs. Response:

{ "tasks": ["task1", "task2"], "status": "QUOTING" }

List offers

GET /v1/trips/{tripId}/offers?category=flight Response:

{ "offers": [{"id":"offer_uuid","price_total_cents":51234,"currency":"USD","details":{}}] }

Select offer(s)

POST /v1/trips/{tripId}/selection

{ "flight_offer_id": "...", "hotel_offer_id": "..." }

Create payment intent

POST /v1/payments/intent

{ "trip_id": "...", "amount_cents": 123456, "currency": "USD" }

Response:

{ "client_secret": "pi_..._secret_..." }

Book

POST /v1/trips/{tripId}/book Headers: Idempotency-Key: <uuid> Response:

{ "status": "BOOKED", "bookings": [{"id":"...","pnr":"ABC123"}] }

Monitoring webhook (internal)

POST /v1/webhooks/flight-status

• Validates signature; creates monitoring_events; notifies user.

Notes

• Prefer SSE for streaming agent output; WebSockets optional.
• All tool calls from agents should map to internal endpoints (not exposed publicly) or service methods with strict schemas.

Recommended stack (MVP)

Frontend

• Next.js (App Router) + TypeScript: fast iteration, SSR for itinerary pages, good auth ecosystem.
• UI: Tailwind + shadcn/ui for consistent components.
• Streaming: SSE client for chat token streaming.

Backend

• Node.js (NestJS or Fastify) + TypeScript:
• Strong typing for tool schemas.
• Easy integration with Stripe and travel APIs.
• Agent orchestration: lightweight in-house orchestrator + queue workers.

Database

• Postgres (managed): relational integrity for bookings/payments + JSONB for flexible provider payloads.
• Redis (optional): caching offers, rate limiting, session store.

Queue / async

• BullMQ (Redis) for MVP simplicity, or Cloud Tasks/SQS if on GCP/AWS.

LLM

• Use a provider with function/tool calling and good latency (OpenAI/Anthropic).
• Enforce JSON schema outputs for trip specs and agent results.

Hosting

• Vercel for Next.js + API separately on Fly.io/Render/AWS ECS.
• Or single platform: AWS (ALB + ECS Fargate + RDS + ElastiCache).

Optional alternatives

• Python backend (FastAPI) if team prefers; good for orchestration.
• Temporal for workflows if you expect complex long-running sagas early; otherwise add later.

Why these choices

• Travel integrations are messy; TypeScript + schema validation reduces runtime errors.
• Postgres JSONB allows storing raw provider payloads while keeping core normalized.
• Queue-based workers are required for parallel searches and monitoring.

Authentication

• MVP: OAuth (Google) + optional email magic link.
• Store sessions in HttpOnly cookies; rotate session IDs.
• For B2B: SSO (SAML/OIDC) in Phase 2.

Authorization

• RBAC:
• user: own trips only
• admin: org-wide visibility
• Enforce row-level checks in service layer; consider Postgres RLS later.

Data protection

• Encrypt at rest (managed Postgres + storage).
• Encrypt sensitive fields at application level if storing:
• passport numbers, DOB (ideally avoid in MVP)
• Never store raw card data; use Stripe.

Rate limiting + abuse

• Per-IP and per-user rate limits on chat endpoints.
• Tool-call quotas per trip to prevent runaway agent loops.

Threat considerations

• Prompt injection: treat external content (hotel descriptions, emails) as untrusted; isolate tool permissions.
• Booking fraud: velocity checks, 3DS where applicable, risk scoring.
• Webhook security: signature verification + replay protection.
• Audit logs: immutable append-only log for agent actions and booking/payment events.

Pricing model

B2C

• Free: planning + recommendations (limited quotes/day).
• Pro: $15–$30/month
• unlimited trip planning
• disruption alerts
• priority support
• Per-booking service fee: 1–3% or flat $10–$25 depending on vertical.

B2B

• $10–$25/user/month + transaction fee (or negotiated).
• Add-ons:
• SSO + SCIM
• policy engine
• reporting exports

Revenue streams

• Booking commissions/affiliate revenue (hotels often higher than flights).
• Subscription for premium automation.
• Corporate SaaS fees.

Expansion pricing

• 24/7 human concierge escalation (per-trip fee).
• Crypto settlement fee (bps) if offered.

Unit economics assumptions (rough)

• LLM cost per trip plan: target <$0.50 by caching + constrained tool calls.
• Support cost reduced via post-booking automation.
• Hotels commission can subsidize flight low-margin bookings.

Distribution strategy

• Start B2C with a narrow wedge: “book and manage a beach trip in under 10 minutes via chat”.
• Focus on one corridor (e.g., NYC -> Caribbean/Mexico) to reduce edge cases.

Channels

• SEO landing pages for destination templates (generated from structured data, not LLM spam).
• Partnerships: travel influencers, newsletters.
• App marketplaces later (mobile app) after retention.

Launch plan

1. Private beta (50–200 users): manual oversight of bookings.
2. Public waitlist with concierge-assisted first trip.
3. Expand destinations/providers after operational stability.

Growth loops

• Shareable itinerary link (read-only) that invites collaborators.
• Post-trip summary + “rebook similar trip” button.
• Corporate: employee invites team; admin converts to org plan.

Validate before full build

• Prototype chat intake + itinerary generation without booking.
• Wizard-of-Oz: humans execute bookings behind the scenes to validate demand and workflows.

MVP testing approach

• Measure:
• time-to-itinerary
• quote-to-book conversion
• post-booking issue rate
• user satisfaction after disruption events
• Run controlled cohorts:
• chat-only planning vs chat+booking

Metrics to track

• Activation: % users who create a trip spec.
• Engagement: messages per trip, time to selection.
• Conversion: % trips booked.
• Retention: repeat trip creation within 60 days.
• Reliability: booking success rate, provider error rate.
• Cost: LLM/tool calls per trip.

Phase 1 (MVP) — 8–12 weeks

• Web chat + trip spec extraction
• Flight + hotel search via single provider each
• Offer selection + Stripe payment + booking
• Itinerary page + email receipt
• Basic flight monitoring + alerts

Phase 2 — 3–5 months

• Add second provider per vertical for redundancy
• Better disruption handling: precomputed alternatives, one-tap rebook
• Preference learning + editable profile UI
• Corporate-lite: orgs, policy rules, approvals
• Mobile app wrapper (React Native/Expo) if needed

Phase 3 — 6–12 months

• Full lifecycle automation: cancellations/refunds where APIs allow
• Activities booking + dining reservations
• Loyalty points integration (where feasible)
• Seat map selection for supported carriers
• SSO/SCIM, SOC2 program, data retention controls
• Workflow engine (Temporal) for complex sagas

Technical risks

• Provider API limitations: booking, changes, refunds often restricted.
• Inconsistent fare rules and hotel policies; hard to normalize.
• Agent reliability: tool-call loops, hallucinated constraints; must enforce schemas.
• Monitoring accuracy: false positives/negatives on misconnect risk.

Market risks

• Users may not trust chat for expensive bookings.
• OTAs can replicate conversational UI; differentiation must be lifecycle automation.

Legal risks

• Seller of travel regulations vary by jurisdiction.
• PCI scope if mishandled (avoid by using Stripe).
• Data privacy (GDPR/CCPA) for profile and travel documents.

Competitive risks

• Google/Apple platform-level travel features.
• Corporate incumbents with deep integrations.

Mitigations

• Start with limited scope and clear disclaimers.
• Keep human escalation path.
• Strong audit logs and deterministic tool outputs.

Product expansion

• Multi-city and complex itineraries with constraint solving.
• Group travel: shared preferences, split payments.
• Automated visa/entry requirement checks.
• Ground transport (rail, rideshare, car rental) integrations.
• Travel insurance quoting and claims assistance.

Platform expansion

• Plugin/tool marketplace for new agents (e.g., ski trips, cruises).
• Provider abstraction layer with contract tests.
• Event-driven workflow engine for long-running processes.

Scalability direction

• Move from BullMQ to managed queues + Temporal.
• Introduce read models for itinerary rendering.
• Cache offers aggressively; dedupe identical searches.

You are a senior full-stack engineer building the MVP of TravelOS: a conversational travel planner + flight/hotel booking system with multi-agent orchestration.

TECH STACK
- Frontend: Next.js (TypeScript), Tailwind, shadcn/ui
- Backend: Node.js TypeScript (Fastify or NestJS)
- DB: Postgres (Prisma ORM)
- Queue: BullMQ + Redis
- Payments: Stripe
- LLM: tool/function calling (OpenAI or Anthropic)
- Hosting: Docker Compose for local; deploy backend to Fly.io/Render and frontend to Vercel

DELIVERABLES
1) Monorepo with /apps/web and /apps/api and /packages/shared
2) Working web chat UI with SSE streaming responses
3) Trip creation, trip spec extraction, offer search (flight + hotel), selection, Stripe payment, booking record creation
4) Background workers for parallel agent tasks
5) Basic flight monitoring job that creates alerts
6) Admin-lite page listing trips and audit logs
7) Seed scripts + migrations

PROJECT STRUCTURE
- apps/web: Next.js app
  - /app/chat/[tripId]
  - /app/trips
  - /app/admin (protected)
- apps/api: Fastify/NestJS
  - /src/routes (auth, trips, conversations, offers, payments, bookings)
  - /src/services (orchestrator, providers, stripe, monitoring)
  - /src/workers (bullmq processors)
- packages/shared:
  - zod schemas for TripSpec, Offer, Booking, ToolInputs/Outputs

DATABASE SCHEMA (Prisma models)
Implement models equivalent to:
- User, UserProfile
- Trip (status, tripSpec JSON)
- Conversation, Message
- AgentTask
- Offer
- Booking
- Payment
- MonitoringEvent
Add indexes: Trip(userId,status), Message(conversationId,createdAt), Offer(tripId,category,price), AgentTask(status)

AGENT ORCHESTRATION
- Implement a ConciergeOrchestrator service that:
  1) Takes user message + current TripSpec
  2) Calls LLM to produce either:
     - updated TripSpec (JSON)
     - list of tasks to run (SearchFlights, SearchHotels, BuildBudget, AssembleItinerary)
  3) Enqueues tasks to BullMQ with tripId and normalized inputs
- Each task processor calls provider adapters (FlightProvider, HotelProvider) and stores Offer rows.
- AssembleItinerary task writes a structured itinerary JSON to Trip or emits a chat message with content_json cards.

PROVIDER ADAPTERS
- FlightProvider:
  - searchFlights(tripSpec) -> normalized offers
  - (MVP) no seat selection; store fare rules in details JSON
- HotelProvider:
  - searchHotels(tripSpec) -> normalized offers
- Use environment variables for API keys.

API ENDPOINTS
- POST /v1/auth/login (magic link) or /v1/auth/oauth/google
- POST /v1/trips
- GET /v1/trips/:tripId
- POST /v1/trips/:tripId/quote
- GET /v1/trips/:tripId/offers?category=flight|hotel
- POST /v1/trips/:tripId/selection
- POST /v1/payments/intent
- POST /v1/trips/:tripId/book (Idempotency-Key required)
- POST /v1/conversations/:conversationId/messages (SSE streaming)
- GET /v1/admin/trips

REQUEST/RESPONSE SCHEMAS
- Use Zod for validation on all endpoints.
- TripSpec schema must include: origin, destination, date_start, date_end, budget, travelers, preferences.

SECURITY REQUIREMENTS
- Protect all endpoints with auth middleware.
- Ensure users can only access their own trips.
- Verify Stripe webhooks.
- Add rate limiting on message endpoint.

DEPLOYMENT
- Provide Docker Compose for local dev:
  - postgres, redis, api, worker
- Provide scripts:
  - pnpm install
  - pnpm db:migrate
  - pnpm dev
- Provide minimal CI (GitHub Actions): typecheck, lint, test, prisma migrate diff.

IMPLEMENTATION NOTES
- Keep LLM outputs strictly JSON with schemas; reject and retry on invalid JSON.
- Store raw provider payloads in Offer.details JSONB.
- Use SSE for chat streaming; send both text tokens and structured cards.
- Ensure booking endpoint is idempotent and cannot double-charge.

Build the MVP end-to-end with working flows:
1) User starts chat -> TripSpec extracted
2) Quote -> flight/hotel offers appear
3) User selects -> pays -> booking record created
4) Monitoring job runs and can create an alert event

Return code with clear README and environment variable templates.