MVP.2 - Multi-Channel Distribution

Timeline: Weeks 17-24 Status: In Design Business Value: Reach more guests across multiple OTAs, prevent double-bookings

Overview

MVP.2 extends the platform to support multi-channel distribution across Airbnb, VRBO, and Hostaway. Property managers can now distribute their villas to multiple OTAs from a single platform with unified availability management and conflict prevention. This builds on MVP.1's two-way sync capabilities to create a true multi-channel distribution system.

Core Capabilities

1. Airbnb Integration

Airbnb API authentication and connection
Listing creation and updates
Availability sync (TVL → Airbnb)
Booking ingestion (Airbnb → TVL)
Channel-specific field mappings
Photo and amenity transformation

2. VRBO Integration

VRBO API authentication and connection
Listing creation and updates
Availability sync (TVL → VRBO)
Booking ingestion (VRBO → TVL)
Channel-specific field mappings
Image format conversion (JPEG requirements)

3. Multi-Channel Conflict Detection

Cross-channel availability validation
Double-booking prevention
Conflict resolution workflows
Priority-based channel rules
Automated block creation

4. Unified Sync Dashboard

Single view of all channel listings
Per-channel sync status
Error tracking and diagnostics
Manual sync triggers per channel
Sync history and audit logs

5. Channel Field Mappings

Property type transformations
Bathroom format conversions
String length validations
Enum value mappings
Image requirement enforcement

Domains Implemented

Domain	Scope	Priority
Identity & Tenancy	Full (from MVP.0)	CRITICAL
Authorization & Access	RBAC (from MVP.0)	CRITICAL
Supply	Full CRUD (from MVP.0)	CRITICAL
Availability & Calendars	Multi-channel sync	CRITICAL
Bookings	Multi-channel ingestion	CRITICAL
Channels & Distribution	Multi-channel	CRITICAL
Analytics & Audit	Enhanced logging	HIGH

Database Schema (21 Tables)

Inherited from MVP.1 (19 tables)

All tables from MVP.0 (14) and MVP.1 (+5) remain unchanged.

New Tables for MVP.2 (+2 tables)

Channels Domain (2 new tables)

15. channel_field_mappings - Channel-specific transformation rules

CREATE TABLE channel_field_mappings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID NOT NULL REFERENCES organizations(id),
  channel_id UUID NOT NULL REFERENCES channel_targets(id),
  field_name VARCHAR(100) NOT NULL,
  tvl_field_path VARCHAR(255) NOT NULL,
  channel_field_path VARCHAR(255) NOT NULL,
  transform_function VARCHAR(100),
  validation_rules JSONB,
  is_required BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (channel_id, field_name)
);

16. channel_conflicts - Cross-channel booking conflicts

CREATE TABLE channel_conflicts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID NOT NULL REFERENCES organizations(id),
  account_id UUID NOT NULL REFERENCES accounts(id),
  space_id UUID NOT NULL REFERENCES spaces(id),
  conflict_type VARCHAR(50) NOT NULL,
  start_date DATE NOT NULL,
  end_date DATE NOT NULL,
  channel_listing_ids UUID[] NOT NULL,
  detected_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  resolution_status VARCHAR(50) DEFAULT 'pending',
  resolved_at TIMESTAMPTZ,
  resolution_action VARCHAR(100),
  metadata JSONB,
  INDEX idx_conflicts_space_status (space_id, resolution_status),
  INDEX idx_conflicts_detected (detected_at)
);

Functional Requirements

FR-1: Airbnb Channel Connection

Given: User with Owner role
When: Adds Airbnb channel target
Then: OAuth flow initiated for Airbnb
And: API token stored in Secrets Manager
And: Channel target record created with type='airbnb'
And: Health check scheduled
And: Field mappings auto-populated from Airbnb schema

FR-2: VRBO Channel Connection

Given: User with Owner role
When: Adds VRBO channel target
Then: API credentials configured
And: API token stored in Secrets Manager
And: Channel target record created with type='vrbo'
And: Health check scheduled
And: Field mappings auto-populated from VRBO schema

FR-3: Multi-Channel Listing Creation

Given: Unit linked to Hostaway, Airbnb, and VRBO
When: User publishes Unit to all channels
Then: Three channel_listing records created
And: Field transformations applied per channel
And: Sync jobs enqueued for each channel
And: Validation performed before API calls
And: Errors reported per channel individually

FR-4: Field Transformation - Bathrooms

Given: Unit has bathrooms = 2.5
When: Syncing to Airbnb
Then: Bathrooms field = 3 (rounded up)
When: Syncing to VRBO
Then: Bathrooms = {full: 2, half: 1} (split format)
When: Syncing to Hostaway
Then: Bathrooms = 2.5 (decimal preserved)

FR-5: Field Transformation - Property Type

Given: Unit has property_type = 'villa'
When: Syncing to Airbnb
Then: property_type_id = 2 (numeric enum)
When: Syncing to VRBO
Then: propertyType = 'VILLA' (uppercase string)
When: Syncing to Hostaway
Then: propertyTypeName = 'Villa' (title case)

FR-6: Cross-Channel Conflict Detection

Given: Booking ingested from Airbnb for Space A, dates 2025-07-01 to 2025-07-05
When: New booking attempted on VRBO for same Space A, overlapping dates
Then: Conflict detected before booking creation
And: channel_conflict record created
And: Availability blocked on all other channels
And: Alert sent to property manager
And: VRBO booking request rejected or flagged

FR-7: Multi-Channel Availability Sync

Given: Booking confirmed on Airbnb
When: Availability calendar updated
Then: Block created for booking dates
And: Sync triggered to Hostaway (if linked)
And: Sync triggered to VRBO (if linked)
And: All syncs complete within 5 minutes
And: Conflict check runs after all syncs

FR-9: Unified Sync Dashboard

Given: Unit linked to 3 channels
When: User views sync dashboard
Then: Three status cards displayed (one per channel)
And: Each shows: last_synced_at, status, error_message
And: Channel-specific icons and colors
And: Sync history accessible per channel
And: Manual retry available per channel
And: Conflict warnings highlighted

FR-10: Conflict Resolution Workflow

Given: Conflict detected between Airbnb and VRBO bookings
When: Operator views conflict dashboard
Then: Conflict details shown (dates, channels, booking IDs)
And: Resolution options presented:
- Keep Airbnb booking (cancel VRBO)
- Keep VRBO booking (cancel Airbnb)
- Keep both (multi-unit space)
- Manual investigation
When: Resolution selected
Then: Appropriate booking canceled on channel
And: Availability updated on all channels
And: Conflict marked as resolved
And: Audit log created

Non-Functional Requirements

NFR-1: Performance

Cross-channel sync latency: <5 minutes
Conflict detection: <10 seconds after booking ingestion
Dashboard load time: <1 second for 100+ listings
API response time: <500ms (p95)

NFR-2: Reliability

Multi-channel sync success rate: 99%+
Zero double-bookings across channels
Idempotent sync operations
Graceful degradation if one channel offline

NFR-3: Data Integrity

Field transformations validated before sync
Rollback on partial sync failures
Audit trail for all channel operations
Immutable conflict records

NFR-4: Scalability

Support 100+ properties per org
Support 3+ channels per property
Handle 1000+ bookings per month
Queue up to 10,000 sync jobs

Technical Architecture

Stack (Inherited from MVP.0/MVP.1)

Backend: Node.js 20+ with TypeScript
Framework: Express.js
Database: PostgreSQL 15+
Queue: BullMQ + Redis
Auth: Google OIDC (Passport.js)
Secrets: AWS Secrets Manager or GCP Secret Manager
Deployment: Docker + Kubernetes

New Components for MVP.2

Channel Adapters:

AirbnbAdapter - Airbnb API v2024 client
VRBOAdapter - VRBO API v2 client
HostawayAdapter - (existing from MVP.0)

Field Transformation Engine:

FieldMapper - Central transformation logic
PropertyTypeMap - Channel-specific enum mappings
BathroomConverter - Format conversions
ImageValidator - Channel-specific validation

Conflict Detection Service:

ConflictDetector - Cross-channel overlap detection
AvailabilityMerger - Unified calendar view
ConflictResolver - Resolution workflow engine

Key Design Decisions

Decision	Choice	Rationale
Field Mappings	Database-driven	Configurable without code deploys
Conflict Detection	Pre-booking validation	Prevent issues vs. fix after
Sync Priority	Sequential by channel	Avoid race conditions
Image Conversion	On-demand during sync	No pre-processing storage needed
Error Isolation	Per-channel failures	One channel down doesn't block others
Retry Strategy	Exponential backoff	Avoid API rate limits

Success Metrics

Metric	Target	Measurement
Properties on 3+ channels	100+	Count channel_listings per space
Zero double-bookings	100%	No conflicting confirmed bookings
Cross-channel sync latency	<5 min	Time from update to all channels synced
Sync success rate (all channels)	99%+	Successful syncs / total attempts
Conflict detection accuracy	100%	No missed overlaps
User adoption (multi-channel)	80% of orgs	Orgs with 2+ active channels

Out of Scope (Deferred)

Deferred to V1.0

Direct booking engine on TVL
Payment processing
Dynamic pricing across channels
Guest messaging integration
Channel performance analytics

Deferred to V1.1

Additional channels (Booking.com, Expedia)
Automated conflict resolution (AI-driven)
Channel-specific pricing rules
Advanced rate synchronization
Multi-unit bookings

Deferred to V2.0

White-label marketplace distribution
Channel API webhooks (real-time)
Predictive conflict prevention
Cross-channel review aggregation

Dependencies

External Dependencies

Google OIDC (from MVP.0)
Hostaway API (from MVP.0)
Airbnb Partner API - https://airbnb.com/partner/docs
VRBO API - https://developers.vrbo.com
Secrets Manager (AWS or GCP)

Internal Dependencies

MVP.0 foundation (auth, supply, one-way sync)
MVP.1 two-way sync (booking ingestion, availability)

Risks & Mitigation

Risk	Impact	Probability	Mitigation
Airbnb API rate limits	HIGH	MEDIUM	Per-channel rate limiters, queue prioritization
VRBO API breaking changes	MEDIUM	MEDIUM	Version pinning, adapter abstraction
Double-booking during sync	HIGH	LOW	Optimistic locking, conflict detection pre-commit
Field mapping errors	MEDIUM	MEDIUM	Pre-sync validation, rollback on failure
Image conversion failures	LOW	MEDIUM	Graceful skip, warning logs
Channel downtime	MEDIUM	LOW	Error isolation, retry with backoff

Acceptance Criteria

Multi-Channel Setup

User can connect Airbnb channel via OAuth
User can connect VRBO channel with API credentials
User can link Unit to Airbnb, VRBO, and Hostaway simultaneously
Field mappings auto-populated for new channels

Sync Operations

Unit updates sync to all linked channels
Field transformations apply correctly per channel
Images validated and converted per channel requirements
Availability syncs to all channels within 5 minutes
Booking ingestion from Airbnb creates TVL booking
Booking ingestion from VRBO creates TVL booking

Conflict Detection

Overlapping bookings from different channels detected
Conflict record created with all details
Availability blocked on non-booked channels
Alert sent to property manager
Conflict resolution workflow functional

Dashboard

Unified view shows all channel statuses
Per-channel sync history accessible
Manual retry works for each channel
Errors displayed with actionable messages
Conflict dashboard shows pending conflicts

Testing

100+ properties distributed to 3 channels
Zero double-bookings in production
99%+ sync success rate
<5 minute cross-channel sync latency
All field transformations tested and validated

Delivery Plan

Week 17: Airbnb Integration

Airbnb adapter implementation
OAuth flow for Airbnb
Field mapping configuration
Listing creation API

Week 18: VRBO Integration

VRBO adapter implementation
API credential management
Field mapping configuration
Listing creation API

Week 19: Field Transformation Engine

Central FieldMapper implementation
Property type conversions
Bathroom format conversions
Image validation and conversion
String length validations

Week 20: Multi-Channel Sync

Enhanced sync job queue
Per-channel sync workers
Parallel sync orchestration
Error isolation and retry
Unified sync status

Week 21: Conflict Detection

Availability overlap detection
Conflict record creation
Cross-channel block creation
Alert system implementation

Week 22: Conflict Resolution

Conflict dashboard UI
Resolution workflow engine
Channel cancellation triggers
Audit logging

Week 23: Testing & Hardening

Integration tests (all channels)
Load testing (100+ properties)
Double-booking prevention tests
Field transformation validation
Security review

Week 24: Launch Prep

Documentation (field mappings)
Runbooks (conflict resolution)
Staging validation (all channels)
Production deployment
User training materials

MVP Overview
MVP.0 Specification - Foundation + Hostaway
MVP.1 Specification - Two-way sync
MVP Data Model
Channel Field Mappings Guide
Roadmap
Domain Specifications:

Overview​

Core Capabilities​

1. Airbnb Integration​

2. VRBO Integration​

3. Multi-Channel Conflict Detection​

4. Unified Sync Dashboard​

5. Channel Field Mappings​

Domains Implemented​

Database Schema (21 Tables)​

Inherited from MVP.1 (19 tables)​

New Tables for MVP.2 (+2 tables)​

Channels Domain (2 new tables)​

Functional Requirements​

FR-1: Airbnb Channel Connection​

FR-2: VRBO Channel Connection​

FR-3: Multi-Channel Listing Creation​

FR-4: Field Transformation - Bathrooms​

FR-5: Field Transformation - Property Type​

FR-6: Cross-Channel Conflict Detection​

FR-7: Multi-Channel Availability Sync​

FR-8: Channel-Specific Image Validation​

FR-9: Unified Sync Dashboard​

FR-10: Conflict Resolution Workflow​

Non-Functional Requirements​

NFR-1: Performance​

NFR-2: Reliability​

NFR-3: Data Integrity​

NFR-4: Scalability​

Technical Architecture​

Stack (Inherited from MVP.0/MVP.1)​

New Components for MVP.2​

Key Design Decisions​

Success Metrics​

Out of Scope (Deferred)​

Deferred to V1.0​

Deferred to V1.1​

Deferred to V2.0​

Dependencies​

External Dependencies​

Internal Dependencies​

Risks & Mitigation​

Acceptance Criteria​

Multi-Channel Setup​

Sync Operations​

Conflict Detection​

Dashboard​

Testing​

Delivery Plan​

Week 17: Airbnb Integration​

Week 18: VRBO Integration​

Week 19: Field Transformation Engine​

Week 20: Multi-Channel Sync​

Week 21: Conflict Detection​

Week 22: Conflict Resolution​

Week 23: Testing & Hardening​

Week 24: Launch Prep​

Related Documents​