Skip to main content

Architecture

This document explains Bundleport's architecture and how requests flow through the system.

High-Level Architecture​

┌─────────────────────────────────────────────────────────────┐
│                    Your Application                          │
│  (OTA, TMC, Booking Engine, AI Assistant, etc.)              │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       │ REST / GraphQL / MCP
                       │
┌──────────────────────▼──────────────────────────────────────┐
│              Bundleport API Gateway                           │
│  • Authentication & Authorization                             │
│  • Rate Limiting                                              │
│  • Request Routing                                            │
│  • Response Aggregation                                        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       │
┌──────────────────────▼──────────────────────────────────────┐
│            Bundleport Core Services                           │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         Connect Hotels Service                        │   │
│  │  • Booking Flow (Search, Quote, Book, Cancel)        │   │
│  │  • Content Catalog (Hotels, Rooms, Destinations)     │   │
│  │  • Business Rules & Normalization                     │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         GraphQL Service                               │   │
│  │  • Hotel-X Compatible Schema                          │   │
│  │  • Query/Mutation Adapters                            │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         MCP Service                                   │   │
│  │  • Tool-based Interface                              │   │
│  │  • AI-Optimized Responses                            │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       │
┌──────────────────────▼──────────────────────────────────────┐
│         Provider Integrations Layer                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │Provider A│  │Provider B│  │Provider C│  │Provider D│    │
│  │ (Bedbank)│  │(Wholesaler)│ │ (Direct) │  │  (GDS)   │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└──────────────────────────────────────────────────────────────┘

Request Flow​

1. Search Request​

Your App
  ↓ POST /connect/hotels/v1/availability
  ↓ Authorization: ApiKey sk_xxx
API Gateway
  ↓ Transform ApiKey → Bearer token
  ↓ Authenticate, Rate Limit
Connect Hotels Service
  ↓ Parse & Validate Request
  ↓ Apply Business Rules
Provider Integrations
  ↓ Parallel Requests
  ├─→ Provider A (Search)
  ├─→ Provider B (Search)
  └─→ Provider C (Search)
  ↓ Collect Responses
Connect Hotels Service
  ↓ Normalize Data
  ↓ Deduplicate Hotels
  ↓ Apply Ranking Rules
  ↓ Aggregate Results
API Gateway
  ↓ Format Response
Your App
  ← JSON Response with Options

2. Booking Request​

Your App
  ↓ POST /connect/hotels/v1/booking
  ↓ Authorization: ApiKey sk_xxx
API Gateway
  ↓ Transform ApiKey → Bearer token
  ↓ Authenticate, Rate Limit
Connect Hotels Service
  ↓ Validate OptionRefId
  ↓ Extract Provider Info
Provider Integration
  ↓ POST Booking to Provider
  ↓ Wait for Confirmation
Connect Hotels Service
  ↓ Normalize Response
  ↓ Store Booking References
  ↓ Trigger Webhooks
API Gateway
  ↓ Format Response
Your App
  ← Booking Confirmation

Key Components​

API Gateway​

Responsibilities:

  • Authentication (API key validation and automatic token transformation)
  • Rate limiting (per service account, per endpoint)
  • Request routing
  • Response formatting
  • Logging and monitoring

The API Gateway acts as the entry point for all API requests, handling security, rate limiting, and routing before requests reach backend services.

Authentication Flow:

The gateway accepts API keys directly and automatically transforms them to Bearer tokens:

  1. Client sends request with Authorization: ApiKey sk_xxx
  2. Gateway detects ApiKey and checks local cache (L1: memory, 5 min TTL)
  3. If cache miss, gateway calls Core API which manages distributed cache (Redis)
  4. Gateway replaces header with Authorization: Bearer <token>
  5. JWT plugin validates the Bearer token
  6. Request continues to the backend service

This automatic transformation means clients can use API keys directly without managing token lifecycle. The gateway handles token caching and refresh transparently for optimal performance.

Connect Hotels Service​

Responsibilities:

  • Request validation
  • Business rule application
  • Data normalization
  • Provider orchestration
  • Response aggregation
  • Deduplication and ranking

Key Features:

  • Multi-provider aggregation
  • Parallel request execution
  • Fault tolerance (partial failures)
  • Caching strategies

Provider Integrations​

Responsibilities:

  • Protocol translation (REST, SOAP, etc.)
  • Data mapping (provider format → Bundleport format)
  • Error handling
  • Retry logic
  • Connection pooling

Supported Protocols:

  • REST APIs
  • SOAP/XML
  • Binary protocols
  • Custom integrations

Content Service​

Responsibilities:

  • Hotel catalog management
  • Content synchronization
  • Data quality assurance
  • Multi-language support
  • Media management

Data Flow​

Normalization Process​

Provider Response (Format A)
  ↓
Parse & Extract
  ↓
Map to Bundleport Schema
  ↓
Apply Business Rules
  ↓
Normalized Response

Example:

  • Provider A: hotel_id, room_type, meal_plan
  • Provider B: propertyCode, accommodationType, boardBasis
  • Normalized: hotel.code, room.code, boardCode

Deduplication​

When the same hotel appears from multiple providers:

  1. Identify - Match hotels by location, name, or provider mapping
  2. Consolidate - Merge options from all providers
  3. Rank - Apply business rules to select best option
  4. Present - Return single result with provider metadata

Multi-Provider Aggregation​

Parallel Execution​

All providers are queried in parallel for faster responses:

Search Request
  ├─→ Provider A (500ms)
  ├─→ Provider B (800ms)
  └─→ Provider C (1200ms)
  
Total Time: ~1200ms (not 2500ms)

Partial Failures​

If one provider fails, others continue:

Search Request
  ├─→ Provider A ✅ (45 hotels)
  ├─→ Provider B ✅ (32 hotels)
  └─→ Provider C ❌ (Timeout)

Result: 77 hotels from A & B
Status: PARTIAL
Warning: Provider C timeout

Caching Strategy​

Content API​

  • Cache Duration: Hours to days
  • Cache Key: Connection code + content type
  • Invalidation: On content updates

Booking API​

  • Cache Duration: None (always real-time)
  • Reason: Availability and pricing change frequently

Scalability​

Horizontal Scaling​

  • API Gateway: Stateless, scales horizontally
  • Services: Stateless, scales horizontally
  • Database: Read replicas for content queries

Performance Optimizations​

  • Connection pooling to providers
  • Parallel request execution
  • Response caching (where appropriate)
  • Database query optimization

Security​

Authentication​

  • API key validation at gateway
  • Automatic ApiKey → Bearer token transformation (transparent to clients)
  • Token caching for performance (local memory + distributed Redis)
  • Service account scopes
  • IP allowlisting (optional)

Data Protection​

  • HTTPS/TLS for all communications
  • PCI compliance for payment data
  • Secure credential storage

Monitoring & Observability​

Metrics​

  • Request rates
  • Response times
  • Error rates
  • Provider performance

Tracing​

  • Request IDs for end-to-end tracking
  • Per-provider response times
  • Error tracking

Logging​

  • Request/response logging
  • Error logging
  • Audit trails

Next Steps​