# Concepts & Architecture

## Enquiry to Booking Journey

The following diagram illustrates the complete booking journey from enquiry creation through to confirmation, showing the interaction between all key parties in the Xenia Connect ecosystem.

The diagram includes the flows for webhook notifications to your system. If you do not plan on subscribing to webhooks, you can safely ignore any steps associated with the "Your Webhook Endpoints" participant.

**Visual Guide:**

- 🔵 **Blue highlighted sections**: API calls made by the Third Party to Xenia Connect
- Regular arrows: Internal Xenia operations and webhook notifications



```mermaid
sequenceDiagram
    participant TP as Third Party (You)
    participant XC as Xenia Connect
    participant WH as Your Webhook Endpoints (if subscribed)
    participant AS as Accommodation Specialist

    Note over TP,AS: ENQUIRY CREATION PHASE
    rect rgb(240, 248, 255)
        TP->>XC: POST /enquiries<br/>(Create new enquiry)
        XC->>XC: Validate & Store enquiry
        XC-->>TP: 201 Created<br/>(xeniaReference, externalId)
    end
    XC->>WH: Trigger ENQUIRY.CREATED
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    Note over TP,AS: SPECIALIST ASSIGNMENT
    AS->>XC: Assign specialist to enquiry
    XC->>WH: Trigger ENQUIRY.SPECIALIST_ASSIGNED
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    Note over TP,AS: SHORTLISTING PHASE
    AS->>XC: Begin property shortlisting
    XC->>XC: Update enquiry state
    XC->>WH: Trigger ENQUIRY.SHORTLISTING
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    AS->>AS: Research & select<br/>suitable properties
    AS->>XC: Add shortlisted properties

    Note over TP,AS: QUOTING PHASE
    AS->>XC: Create quote with<br/>selected properties
    XC->>XC: Generate quote

    AS->>XC: Send quote to client
    XC->>XC: Update enquiry state to QUOTED

    par Simultaneous webhook triggers
        XC->>WH: Trigger QUOTE.CREATED
        WH-->>TP: Webhook notification
        TP-->>WH: 204 No Content
    and
        XC->>WH: Trigger ENQUIRY.QUOTED
        WH-->>TP: Webhook notification
        TP-->>WH: 204 No Content
    end

    Note over TP,AS: CLIENT REVIEWS QUOTE
    rect rgb(240, 248, 255)
        TP->>XC: GET /quotes<br/>(Retrieve quote details)
        XC-->>TP: Quote with properties & pricing
    end

    Note over TP,AS: BOOKING CONFIRMATION PHASE
    AS->>AS: Client accepts quote<br/>(External process)
    AS->>XC: Create booking from quote
    XC->>XC: Generate booking
    XC->>WH: Trigger BOOKING.PENDING
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    Note over TP,AS: PARTNER CONFIRMATION
    AS->>AS: Confirm with<br/>accommodation partner
    XC->>XC: Send partner confirmation
    XC->>XC: Email confirmation to partner
    XC->>WH: Trigger BOOKING.PARTNER_CONFIRMATION_DETAILS_SENT
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    Note over TP,AS: CLIENT CONFIRMATION
    AS->>AS: Confirm with<br/>accommodation Client
    AS->>XC: Send client confirmation
    XC->>XC: Email confirmation to client
    XC->>WH: Trigger BOOKING.CLIENT_CONFIRMATION_DETAILS_SENT
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    Note over TP,AS: CHECK-IN DETAILS
    AS->>XC: Send check-in details
    XC->>XC: Email check-in info
    XC->>WH: Trigger BOOKING.CHECK_IN_DETAILS_SENT
    WH-->>TP: Webhook notification
    TP-->>WH: 204 No Content

    Note over TP,AS: Alternative Flow - CANCELLATION
    alt Booking Cancelled
        AS->>XC: Cancel booking
        XC->>WH: Trigger BOOKING.CANCELLED
        WH-->>TP: Webhook notification
        TP-->>WH: 204 No Content
    end

    Note over TP,AS: Alternative Flow - ENQUIRY CLOSED
    alt Enquiry Closed Without Booking
        AS->>XC: Close enquiry<br/>(with closure reason)
        XC->>WH: Trigger ENQUIRY.CLOSED
        WH-->>TP: Webhook notification
        TP-->>WH: 204 No Content
    end
```