V1.0 Delta from MVP - Villas Complete

Version: V1.0 (Month 7-12) Base Version: MVP.2 (Multi-Channel Distribution) Status: Specification Last Updated: 2025-10-25

Overview

This document details the changes and additions from MVP.2 to V1.0 "Villas Complete". V1.0 represents the transition from a read-only channel distribution platform to a full-featured booking and property management system with direct booking capabilities, payment processing, and financial management.

Key Transformation:

MVP.2: Property managers distribute to channels (Hostaway, Airbnb, VRBO) and view bookings
V1.0: Complete platform where guests book directly, payments are processed, dynamic pricing applies, and owners receive automated payouts

What V1.0 Adds (High-Level Summary)

Business Capabilities Added

Direct Booking Engine - Guests can book directly on TVL platform (not just through OTAs)
Payment Processing - Stripe integration for payments, refunds, and payouts
Dynamic Pricing - Automated pricing rules (seasonal, length-of-stay, lead-time)
Owner Portal - Financial reports, payout tracking, performance analytics
Guest Portal - Booking management, payment history, communication
Advanced Calendar Management - Full availability control with booking creation
Revenue Management - Automated splits, payouts, fee calculations

Technical Transformation

MVP.2: 21 tables, read-only bookings, no payments
V1.0: 35+ tables, full booking engine, payment processing, financial ledger

New Capabilities (vs. MVP.2)

1. Direct Booking Engine (NEW)

What Was NOT Possible in MVP.2:

Guests could NOT book directly on TVL
No quote generation
No hold/reservation workflow
Bookings only ingested from external channels (read-only)

What V1.0 Enables:

✅ Public property search and browse
✅ Real-time availability checking
✅ Quote generation with pricing breakdown
✅ Hold workflow (15-minute checkout timer)
✅ Booking confirmation with payment
✅ Guest checkout flow
✅ Booking confirmation emails
✅ Guest profile and booking history

User Flow:

Guest searches → Views property → Checks dates → Gets quote →
Holds dates (15 min) → Enters payment → Booking confirmed →
Availability blocked across all channels

Impact: Eliminates OTA commissions (15-20%), creates direct customer relationship

2. Payment Processing (NEW)

What Was NOT Possible in MVP.2:

No payment collection
No refund processing
No financial transactions
No payout to owners

What V1.0 Enables:

✅ Stripe Connect integration
✅ Credit card payment processing
✅ Payment authorization and capture
✅ Automatic refund processing (based on cancellation policy)
✅ Revenue splits (platform fee, service fee, owner payout)
✅ Automated payouts to owners
✅ Payment method storage (tokenized)
✅ 3D Secure authentication
✅ PCI compliance (via Stripe)

Payment Flow:

Guest confirms booking → Stripe authorization → Payment captured →
Platform fee deducted → Owner balance credited →
Payout scheduled (after check-in)

New Tables:

payments - Payment transactions
payment_methods - Stored payment methods
refunds - Refund records
payouts - Payouts to owners
payout_accounts - Owner bank accounts
transactions - Double-entry ledger

Impact: Complete financial management, automated revenue collection

3. Dynamic Pricing Engine (NEW)

What Was NOT Possible in MVP.2:

Static pricing only
No seasonal adjustments
No length-of-stay discounts
No last-minute deals
Manual price updates required

What V1.0 Enables:

✅ Seasonal pricing rules (high/low season)
✅ Length-of-stay discounts (7+ nights = 10% off)
✅ Lead-time pricing (book 60+ days ahead = discount)
✅ Last-minute deals (book <7 days out = discount)
✅ Channel-specific pricing
✅ Tax calculation (Avalara integration)
✅ Fee management (cleaning, pet, extra guest)
✅ Minimum stay requirements (dynamic)

Pricing Example:

Base rate: $200/night
Season: High (December) → +25% = $250/night
Length-of-stay: 7 nights → -10% = $225/night
Lead-time: 90 days → -5% = $213.75/night
Cleaning fee: $150 (one-time)
Service fee: $100 (one-time)
Tax (12%): Calculated on subtotal
Total: $1,646.25 for 7 nights

New Tables:

rate_plans - Base pricing rules
seasonal_rates - Seasonal adjustments
pricing_rules - Discount rules
fee_rules - Fee configurations

Impact: Revenue optimization, competitive pricing automation

4. Financial Management & Reporting (NEW)

What Was NOT Possible in MVP.2:

No financial tracking
No revenue reports
No owner statements
No payout scheduling

What V1.0 Enables:

✅ Revenue reports (per property, per owner, per month)
✅ Expense tracking
✅ Tax summaries (for compliance)
✅ Owner financial statements
✅ Payout scheduling (daily/weekly/monthly)
✅ Financial reconciliation
✅ Double-entry accounting ledger
✅ Transaction audit trail

Owner Portal Features:

View all bookings and revenue
Download financial reports (CSV, PDF)
Update banking details
Configure payout schedule
View property performance analytics
Tax reporting (1099 generation for US)

New Tables:

transactions - Complete ledger
fee_configurations - Fee rules
revenue_splits - Split configurations

Impact: Financial transparency, automated accounting, compliance readiness

5. Guest Communication & Portal (NEW)

What Was NOT Possible in MVP.2:

No guest profiles
No communication tools
No booking management for guests

What V1.0 Enables:

✅ Guest user accounts
✅ Booking history view
✅ Payment history
✅ Booking modifications (date changes)
✅ Cancellation requests
✅ Unified inbox (guest ↔ property manager)
✅ Automated message templates
✅ Pre-arrival instructions
✅ Post-checkout review requests

Guest Portal Features:

View upcoming and past bookings
Download booking confirmations
Request cancellations (automatic refund calculation)
Update payment methods
Message property manager
Leave reviews

New Tables:

messages - Communication records
message_threads - Conversation threads
reviews - Guest reviews

Impact: Improved guest experience, reduced support burden

6. Advanced Calendar & Availability Management (ENHANCED)

What Changed from MVP.2:

MVP.2 Capabilities:

✅ Read-only booking display
✅ iCal import from channels
✅ Conflict detection
✅ Manual blocks (owner blocks, maintenance)

V1.0 Enhancements:

✅ Booking creation (not just ingestion)
✅ Hold management with TTL (15-minute checkout timer)
✅ Real-time availability checks (pre-booking validation)
✅ Automated blocking (booking confirmed → all channels blocked)
✅ Unit-level calendars (not just space-level)
✅ Minimum stay rules (dynamic by season)
✅ Availability export (public iCal feeds)

New State Machine:

Available → Hold (15 min) → Booking Confirmed → Blocked
         ↓ (timeout)
    Available (released)

Enhanced Tables:

holds - Now creates blocks, TTL enforced
blocks - Linked to bookings (booking_id foreign key)
availability_calendars - Unit-level support added

Impact: Full booking lifecycle management, double-booking prevention

7. Operational Tools (NEW)

What Was NOT Possible in MVP.2:

No task automation
No staff assignments
No inventory tracking

What V1.0 Enables:

✅ Task automation (cleaning, maintenance)
✅ Calendar sync across team
✅ Staff role assignments
✅ Inventory management (linens, supplies)
✅ Maintenance request tracking
✅ Automated workflows (check-in/check-out)

New Tables:

tasks - Task records
task_templates - Automated task generation
staff_assignments - Team assignments
inventory_items - Property inventory

Impact: Operational efficiency, reduced manual work

Domain Changes (Domain by Domain)

Domain 1: Identity & Tenancy (UNCHANGED)

Status: No changes from MVP.2

Organizations, Accounts, Users, Memberships remain identical
Multi-tenant foundation already complete

Tables: 4 tables (unchanged)

Domain 2: Authorization & Access (MINOR ENHANCEMENTS)

Status: New roles added

New Roles:

guest - Guest user (booking owner)
finance_manager - Financial reports and payouts
operations_manager - Task management, staff assignments

New Permissions:

payment.manage - Process payments and refunds
payout.view - View payout information
pricing.edit - Edit pricing rules
guest.view - View guest information

Tables: 4 tables (unchanged), permissions expanded

Domain 3: Supply (Spaces & Units) (UNCHANGED)

Status: No schema changes from MVP.2

Spaces, Units, Amenities remain identical
Unit snapshots continue for versioning

Tables: 5 tables (unchanged)

Domain 4: Availability & Calendars (MAJOR ENHANCEMENTS)

Status: From read-only to full booking creation

Schema Changes:

holds - Enhanced with lock_type, confirmed_at columns
blocks - Enhanced with booking_id foreign key (links to confirmed bookings)
availability_calendars - Enhanced with unit-level support

New Workflows:

Hold creation → Booking confirmation → Block creation → Channel sync

New Validations:

Pre-booking availability check (GIST exclusion constraints)
Hold expiration (background job)
Cross-channel conflict prevention

Tables: 3 tables (enhanced)

Breaking Changes: None (additive only)

Domain 5: Bookings (COMPLETE IMPLEMENTATION)

Status: From read-only (MVP.2) to full booking engine (V1.0)

MVP.2 State:

Read-only booking records from external channels
Minimal schema (10 columns)
No quote, hold, or confirmation workflow
Display-only

V1.0 State:

Complete booking lifecycle (quote → hold → booking → cancellation)
Full state machine (pending_payment → confirmed → completed → cancelled)
Line items (fees, taxes, discounts)
Cancellation policies and refunds

New Tables (MVP.2 → V1.0):

quotes - Price quotes for date ranges
quote_line_items - Breakdown of quote (nights, fees, taxes)
booking_line_items - Breakdown of confirmed booking
cancellations - Cancellation records with refund tracking
cancellation_policies - Refund rules

Enhanced Tables:

bookings - Now includes:
- quote_id (link to original quote)
- hold_id (link to hold)
- payment_id (link to payment)
- state (full state machine: pending_payment → confirmed → completed)
- cancellation_policy_id
- total_amount_cents, paid_amount_cents, refund_amount_cents
- confirmed_at, cancelled_at, completed_at

State Machine:

[Quote Created] → [Hold Active] → [Pending Payment] →
[Payment Authorized] → [Confirmed] → [Completed]
                    ↓ (cancel)
                [Cancelled] → [Refund Processed]

Tables: 4 new + 1 enhanced = 5 tables total

Breaking Changes:

bookings table schema expanded (additive columns, nullable)
Backfill required for existing read-only bookings

Domain 6: Pricing & Revenue Rules (NEW DOMAIN)

Status: Complete new domain (did not exist in MVP.2)

Purpose: Dynamic pricing, fee management, revenue splits

New Tables:

rate_plans - Base pricing configurations
seasonal_rates - Seasonal pricing adjustments
pricing_rules - Length-of-stay, lead-time, last-minute discounts
fee_rules - Cleaning, pet, extra guest fees
tax_rules - Tax calculation rules (Avalara integration)
revenue_rules - Platform fee, channel commission configurations

Capabilities:

Dynamic nightly rate calculation
Fee application logic
Tax calculation (integration with Avalara)
Revenue split calculations (owner vs. platform)

Tables: 6 new tables

Impact: Automated pricing, revenue optimization

Domain 7: Payments & Financials (NEW DOMAIN)

Status: Complete new domain (did not exist in MVP.2)

Purpose: Payment processing, refunds, payouts, financial reporting

New Tables:

payments - Payment transactions
payment_methods - Stored payment methods (tokenized)
refunds - Refund records
payouts - Payouts to owners
payout_accounts - Owner bank accounts
transactions - Double-entry accounting ledger
fees - Fee configurations

Integration:

Stripe Connect for payment processing
Stripe webhooks for status updates
Bank transfer for payouts

Capabilities:

Payment authorization and capture
Automatic refund processing
Scheduled payouts (daily/weekly/monthly)
Financial reconciliation
Revenue reporting

Tables: 7 new tables

Impact: Complete financial management, PCI compliance via Stripe

Domain 8: Channels & Distribution (UNCHANGED)

Status: No changes from MVP.2

Multi-channel distribution remains identical (Hostaway, Airbnb, VRBO)
Field mappings, conflict detection, sync audit unchanged

Tables: 5 tables (unchanged)

Note: V1.0 adds direct booking channel (TVL), but existing channel logic reused

Domain 9: Content & Metadata (MINOR ENHANCEMENTS)

Status: Enhanced for guest-facing content

New Requirements:

Public property descriptions (SEO-optimized)
Guest-facing photo galleries
Property highlights and features
Location descriptions

Enhanced Tables:

property_content - Guest-facing vs. internal descriptions
media_assets - Public/private visibility flags

Tables: 2 tables (enhanced)

Domain 10: Analytics & Audit (ENHANCED)

Status: Enhanced for financial reporting

New Capabilities:

Revenue reports (per property, per owner, per date range)
Booking analytics (conversion rates, average booking value)
Financial reconciliation reports
Tax summaries

New Tables:

analytics_snapshots - Pre-computed metrics (daily/monthly)
reports - Saved report configurations

Enhanced Tables:

audit_events - Now includes financial events (payment, refund, payout)

Tables: 2 new + 1 enhanced = 3 tables

New Domains Added (V1.0)

1. Pricing & Revenue Rules (NEW)

Purpose: Dynamic pricing engine Tables: 6 new tables Key Concepts: Rate plans, seasonal rates, pricing rules, fee rules, tax rules, revenue rules

2. Payments & Financials (NEW)

Purpose: Payment processing and financial management Tables: 7 new tables Key Concepts: Payments, refunds, payouts, transactions (ledger), fees

3. Guest Portal & Communication (NEW)

Purpose: Guest experience and communication Tables: 3 new tables Key Concepts: Messages, message threads, reviews

4. Operational Tools (NEW)

Purpose: Property operations and task automation Tables: 4 new tables Key Concepts: Tasks, task templates, staff assignments, inventory

Breaking Changes

1. `bookings` Table Schema Expansion (BREAKING)

Change: Added 15+ columns to bookings table

Migration Strategy:

-- Add new columns (nullable)
ALTER TABLE bookings ADD COLUMN quote_id UUID REFERENCES quotes(id);
ALTER TABLE bookings ADD COLUMN hold_id UUID REFERENCES holds(id);
ALTER TABLE bookings ADD COLUMN payment_id UUID REFERENCES payments(id);
ALTER TABLE bookings ADD COLUMN state VARCHAR(50) DEFAULT 'confirmed';
ALTER TABLE bookings ADD COLUMN total_amount_cents BIGINT;
ALTER TABLE bookings ADD COLUMN paid_amount_cents BIGINT;
-- ... (additional columns)

-- Backfill existing read-only bookings
UPDATE bookings SET state = 'completed' WHERE checkout < NOW();
UPDATE bookings SET state = 'confirmed' WHERE checkout >= NOW();

Impact: Existing read-only bookings require backfill Rollback: Drop new columns (data loss acceptable for MVP.2 → V1.0 migration)

2. `holds` Table Enhanced (NON-BREAKING)

Change: Added confirmed_at, lock_type columns (nullable)

Migration Strategy:

-- Additive change, no backfill required
ALTER TABLE holds ADD COLUMN confirmed_at TIMESTAMPTZ;
ALTER TABLE holds ADD COLUMN lock_type VARCHAR(50) DEFAULT 'application';

Impact: None (existing holds work without changes)

3. `availability_calendars` Unit-Level Support (NON-BREAKING)

Change: Allow unit_id (previously space_id only)

Migration Strategy:

-- XOR constraint already allows either space_id OR unit_id
-- No schema change required, just business logic update

Impact: None (space-level calendars continue to work)

Migration Path (MVP.2 → V1.0)

Phase 1: Database Schema Migration (Week 1)

Goal: Add new tables, enhance existing tables

Steps:

Create new tables (Payments, Pricing, Financials)
Add new columns to bookings (nullable)
Add new columns to holds, blocks (nullable)
Create indexes for new tables
Create foreign key constraints
Enable Row-Level Security (RLS) policies

Zero Downtime Strategy:

Blue/green deployment with read replica cutover
Nullable columns allow gradual backfill
No breaking changes to existing APIs

Rollback Plan:

Drop new tables (no data loss, V1.0 not yet live)
Drop new columns from existing tables

Duration: 2-3 days

Phase 2: Data Backfill (Week 1-2)

Goal: Populate new columns for existing data

Backfill Tasks:

Backfill bookings.state based on dates
- If checkout < now() → state = 'completed'
- If checkin <= now() < checkout → state = 'active'
- Else → state = 'confirmed'
Backfill bookings.total_amount_cents from external channel data
Create cancellation_policies for existing spaces

Background Jobs:

Run backfill as async job (1000 records/batch)
Monitor progress via admin dashboard
Validate data integrity after completion

Duration: 1 week

Phase 3: API Deployment (Week 2-3)

Goal: Deploy V1.0 APIs

New APIs:

POST /quotes - Generate price quote
POST /holds - Create hold
POST /bookings - Create booking
POST /payments - Process payment
POST /refunds - Process refund
GET /reports/revenue - Revenue reports

Deployment Strategy:

Deploy new API endpoints (additive, no breaking changes)
Existing MVP.2 APIs continue to work
Feature flags control V1.0 features

Duration: 1 week

Phase 4: Integration Testing (Week 3)

Goal: Test end-to-end booking flow

Test Scenarios:

Guest searches properties
Guest gets quote
Guest creates hold
Guest confirms booking with payment
Payment processed via Stripe
Booking confirmed
Availability blocked across channels
Guest cancels booking
Refund processed
Owner receives payout

Duration: 1 week

Phase 5: Beta Launch (Week 4)

Goal: Limited rollout to select properties

Criteria:

10 properties onboarded
Stripe Connect configured
Pricing rules configured
Payout accounts verified

Monitoring:

Payment success rate (target: 99%+)
Booking completion rate (target: 80%+)
Refund processing time (target: <1 hour)

Duration: 2 weeks

Phase 6: General Availability (Week 6)

Goal: Full V1.0 launch

Rollout:

Enable V1.0 features for all organizations
Marketing launch (direct booking engine)
Owner training (financial reports, payout configuration)

Success Metrics:

500+ properties on platform
1,000+ direct bookings per month
$5M+ in booking value per month

Duration: Ongoing

Deprecations

1. Read-Only Booking Ingestion (DEPRECATED in V1.0)

What's Deprecated:

Read-only booking records from iCal feeds
Manual booking entry (replaced by booking engine)

Replacement:

Full booking engine (quote → hold → booking)
Automated booking creation from channels

Sunset Timeline:

V1.0: Both supported (legacy + new)
V1.5: Legacy mode removed

Migration Path:

Convert read-only bookings to full bookings (backfill payment data)
Update integrations to use booking engine

2. Manual Price Updates (DEPRECATED in V1.0)

What's Deprecated:

Manual nightly rate entry
Static pricing

Replacement:

Dynamic pricing engine
Automated rate calculations

Sunset Timeline:

V1.0: Both supported (manual override available)
V2.0: Manual mode removed (pricing rules required)

Migration Path:

Create default rate plan for each property
Configure seasonal rates
Enable dynamic pricing

API Changes

New Endpoints (V1.0)

Quotes

POST /quotes - Generate price quote
GET /quotes/{quoteId} - Get quote details

Bookings

POST /bookings - Create booking (from hold)
PATCH /bookings/{bookingId} - Modify booking
DELETE /bookings/{bookingId} - Cancel booking

Payments

POST /payment-intents - Create payment intent
POST /payments/{paymentId}/capture - Capture payment
GET /payments - List payments

Refunds

POST /refunds - Process refund
GET /refunds - List refunds

Payouts

POST /payouts - Create payout
GET /payouts - List payouts
GET /payouts/{payoutId} - Get payout details

Pricing

GET /pricing/calculate - Calculate price for date range
POST /rate-plans - Create rate plan
GET /rate-plans - List rate plans

Reports

GET /reports/revenue - Revenue report
GET /reports/payouts - Payout report
GET /reports/bookings - Booking report

Enhanced Endpoints (V1.0)

Bookings

GET /bookings - Now returns full booking details (not just external)
GET /bookings/{bookingId} - Includes payment, refund, line items

Availability

GET /availability - Now includes hold information
POST /availability/check - Real-time availability check (new)

Removed Endpoints

None - V1.0 is fully additive, no breaking API changes

Configuration Changes

New Environment Variables (V1.0)

# Stripe Configuration
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_CONNECT_CLIENT_ID=ca_xxx

# Payment Configuration
PAYMENT_AUTHORIZATION_TTL_DAYS=7
PAYMENT_CAPTURE_DELAY_SECONDS=30
REFUND_PROCESSING_DELAY_SECONDS=0

# Payout Configuration
PAYOUT_SCHEDULE=daily  # daily | weekly | monthly
PAYOUT_HOLD_DAYS=1  # Payout after check-in + N days
PAYOUT_RETRY_ATTEMPTS=3

# Pricing Configuration
DYNAMIC_PRICING_ENABLED=true
TAX_CALCULATION_PROVIDER=avalara  # avalara | manual
PLATFORM_FEE_PERCENTAGE=0.15  # 15%

# Financial Configuration
ACCOUNTING_MODE=double_entry  # double_entry | simple
FINANCIAL_RECONCILIATION_ENABLED=true

New Secrets (AWS Secrets Manager / GCP Secret Manager)

{
  "stripe": {
    "secret_key": "sk_live_...",
    "publishable_key": "pk_live_...",
    "webhook_secret": "whsec_...",
    "connect_client_id": "ca_..."
  },
  "avalara": {
    "account_id": "...",
    "license_key": "...",
    "company_code": "..."
  },
  "database": {
    "encryption_key": "..."  # For encrypting bank account details
  }
}

Performance Impact

Database Growth (MVP.2 → V1.0)

Metric	MVP.2	V1.0	Growth
Tables	21	35+	+67%
Indexes	60+	100+	+67%
Expected Row Count (1 year)	~10M	~50M	+400%
Database Size (estimated)	~50GB	~200GB	+300%

Scaling Recommendations:

Partition transactions table by month (already implemented)
Add read replicas for reporting queries
Archive old transactions to cold storage after 2 years

API Latency Targets

Endpoint	MVP.2	V1.0 Target	Notes
GET /bookings	<200ms	<200ms	Unchanged
POST /bookings	N/A	<500ms	New endpoint
POST /payment-intents	N/A	<1s	Includes Stripe API call
GET /reports/revenue	N/A	<2s	Complex aggregation
GET /availability	<100ms	<200ms	More complex query (holds)

Background Job Load

New Jobs (V1.0):

capture-payment-job - 1000+ jobs/day (one per booking)
process-payout-job - 100+ jobs/day (batched by org)
expire-hold-job - 5000+ jobs/day (15-minute TTL)
reconciliation-job - 1 job/day (nightly)
tax-calculation-job - 1000+ jobs/day (per booking)

Queue Capacity:

MVP.2: 10,000 jobs/day
V1.0: 50,000 jobs/day (5x increase)

Recommendation: Upgrade Redis instance, add job queue monitoring

Security Enhancements

PCI Compliance (V1.0)

Requirement: Payment Card Industry Data Security Standard (PCI-DSS)

Compliance Strategy:

Use Stripe for card storage (no card data in TVL database)
Tokenized payment methods only
Hosted payment forms (Stripe.js)
No card data in logs or error messages

Certification: TVL is PCI-DSS Level 4 compliant (via Stripe)

Data Encryption (V1.0)

New Encrypted Fields:

payout_accounts.routing_number - Bank routing number (AES-256)
payout_accounts.account_number - Bank account number (AES-256)

Encryption Key Management:

AWS KMS or GCP KMS for key storage
Automatic key rotation every 90 days
Encryption at rest and in transit

Access Control (V1.0)

New Permissions:

payment.manage - Process payments (Finance role only)
payout.view - View payout details (Owner, Finance)
payout.manage - Process payouts (Finance role only)
pricing.edit - Edit pricing rules (Owner, Revenue Manager)
refund.process - Process refunds (Owner, Finance, Support)

Row-Level Security (RLS):

Enabled for payments, payouts, transactions tables
Users only see data for their organization
Guest users only see their own bookings/payments

Testing Requirements

New Test Suites (V1.0)

Booking Engine Tests
- Quote generation accuracy
- Hold expiration (TTL)
- Booking confirmation flow
- Cancellation and refund workflow
Payment Processing Tests
- Payment authorization (success and failure scenarios)
- Payment capture
- Refund processing
- Stripe webhook handling
Pricing Engine Tests
- Dynamic pricing calculations
- Seasonal rate application
- Length-of-stay discounts
- Tax calculation
Financial Reconciliation Tests
- Double-entry ledger validation
- Balance reconciliation
- Payout calculation accuracy
Integration Tests
- End-to-end booking flow (guest → payment → confirmation)
- Cancellation flow (booking → refund → availability release)
- Payout flow (booking complete → payout → bank transfer)
Load Tests
- 100 concurrent bookings
- 1000 payment intents/minute
- 10,000 hold creations/hour

Documentation Updates

New Documentation Required (V1.0)

API Documentation
- Payment API reference
- Pricing API reference
- Payout API reference
- Booking API reference (enhanced)
User Guides
- Guest booking guide
- Owner payout configuration guide
- Pricing configuration guide
- Financial reporting guide
Developer Guides
- Stripe integration guide
- Payment webhook handling
- Financial reconciliation implementation
- Pricing engine architecture
Operational Runbooks
- Payment failure troubleshooting
- Refund processing
- Payout reconciliation
- Financial month-end close

Success Metrics (V1.0 vs. MVP.2)

Metric	MVP.2 Target	V1.0 Target	Notes
Properties on Platform	100+	500+	5x growth
Monthly Bookings	0 (external only)	1,000+ (direct)	New capability
Monthly Booking Value	$0 (TVL)	$5M+	Revenue generation
Payment Success Rate	N/A	99%+	Stripe SLA
Payout Processing Time	N/A	<3 days	Industry standard
Average Booking Value	N/A	$1,400	Target
Direct Booking Conversion	N/A	3-5%	Industry benchmark
Platform Fee Revenue	$0	$750K/month	15% of $5M
Property Manager Satisfaction	90%+	90%+	Maintain
Guest Satisfaction	N/A	85%+	New metric

Risks & Mitigation

Risk 1: Payment Processing Downtime

Impact: HIGH - Cannot accept bookings if Stripe down Probability: LOW - Stripe has 99.99% uptime SLA Mitigation:

Queue payment intents for retry if Stripe unavailable
Display maintenance message to guests
Alert ops team immediately

Risk 2: Financial Reconciliation Errors

Impact: HIGH - Incorrect payouts damage trust Probability: MEDIUM - Complex financial logic Mitigation:

Automated daily reconciliation job
Manual monthly reconciliation by finance team
Alert on any balance discrepancies
Comprehensive audit trail

Risk 3: Pricing Engine Bugs

Impact: MEDIUM - Incorrect quotes lead to lost bookings or revenue loss Probability: MEDIUM - Complex dynamic pricing logic Mitigation:

Extensive unit tests (>90% coverage)
Manual price validation in staging
Rate limit price changes (admin approval required)
Price override capability for manual correction

Risk 4: Migration Data Loss

Impact: MEDIUM - Lost booking history impacts reporting Probability: LOW - Careful migration planning Mitigation:

Full database backup before migration
Dry-run migration in staging
Incremental backfill with validation
Rollback plan tested

V1.0 Product Specification - Full V1.0 vision
MVP Overview - What came before
MVP.2 Specification - Baseline for delta
MVP Data Model - Schema evolution
Roadmap - Full product timeline

Revision History

Date	Version	Changes	Author
2025-10-25	1.0	Initial delta specification	Claude Code

End of Document (Total Lines: 486)

Overview​

What V1.0 Adds (High-Level Summary)​

Business Capabilities Added​

Technical Transformation​

New Capabilities (vs. MVP.2)​

1. Direct Booking Engine (NEW)​

2. Payment Processing (NEW)​

3. Dynamic Pricing Engine (NEW)​

4. Financial Management & Reporting (NEW)​

5. Guest Communication & Portal (NEW)​

6. Advanced Calendar & Availability Management (ENHANCED)​

7. Operational Tools (NEW)​

Domain Changes (Domain by Domain)​

Domain 1: Identity & Tenancy (UNCHANGED)​

Domain 2: Authorization & Access (MINOR ENHANCEMENTS)​

Domain 3: Supply (Spaces & Units) (UNCHANGED)​

Domain 4: Availability & Calendars (MAJOR ENHANCEMENTS)​

Domain 5: Bookings (COMPLETE IMPLEMENTATION)​

Domain 6: Pricing & Revenue Rules (NEW DOMAIN)​

Domain 7: Payments & Financials (NEW DOMAIN)​

Domain 8: Channels & Distribution (UNCHANGED)​

Domain 9: Content & Metadata (MINOR ENHANCEMENTS)​

Domain 10: Analytics & Audit (ENHANCED)​

New Domains Added (V1.0)​

1. Pricing & Revenue Rules (NEW)​

2. Payments & Financials (NEW)​

3. Guest Portal & Communication (NEW)​

4. Operational Tools (NEW)​

Breaking Changes​

1. bookings Table Schema Expansion (BREAKING)​

2. holds Table Enhanced (NON-BREAKING)​

3. availability_calendars Unit-Level Support (NON-BREAKING)​

Migration Path (MVP.2 → V1.0)​

Phase 1: Database Schema Migration (Week 1)​

Phase 2: Data Backfill (Week 1-2)​

Phase 3: API Deployment (Week 2-3)​

Phase 4: Integration Testing (Week 3)​

Phase 5: Beta Launch (Week 4)​

Phase 6: General Availability (Week 6)​

Deprecations​

1. Read-Only Booking Ingestion (DEPRECATED in V1.0)​

2. Manual Price Updates (DEPRECATED in V1.0)​

API Changes​

New Endpoints (V1.0)​

Quotes​

Bookings​

Payments​

Refunds​

Payouts​

Pricing​

Reports​

Enhanced Endpoints (V1.0)​

Bookings​

Availability​

Removed Endpoints​

Configuration Changes​

New Environment Variables (V1.0)​

New Secrets (AWS Secrets Manager / GCP Secret Manager)​

Performance Impact​

Database Growth (MVP.2 → V1.0)​

API Latency Targets​

Background Job Load​

Security Enhancements​

PCI Compliance (V1.0)​

Data Encryption (V1.0)​

Access Control (V1.0)​

Testing Requirements​

New Test Suites (V1.0)​

Documentation Updates​

New Documentation Required (V1.0)​

Success Metrics (V1.0 vs. MVP.2)​

Risks & Mitigation​

Risk 1: Payment Processing Downtime​

Risk 2: Financial Reconciliation Errors​

Risk 3: Pricing Engine Bugs​

Risk 4: Migration Data Loss​

Related Documents​

Revision History​

Overview

What V1.0 Adds (High-Level Summary)

Business Capabilities Added

Technical Transformation

New Capabilities (vs. MVP.2)

1. Direct Booking Engine (NEW)

2. Payment Processing (NEW)

3. Dynamic Pricing Engine (NEW)

4. Financial Management & Reporting (NEW)

5. Guest Communication & Portal (NEW)

6. Advanced Calendar & Availability Management (ENHANCED)

7. Operational Tools (NEW)

Domain Changes (Domain by Domain)

Domain 1: Identity & Tenancy (UNCHANGED)

Domain 2: Authorization & Access (MINOR ENHANCEMENTS)

Domain 3: Supply (Spaces & Units) (UNCHANGED)

Domain 4: Availability & Calendars (MAJOR ENHANCEMENTS)

Domain 5: Bookings (COMPLETE IMPLEMENTATION)

Domain 6: Pricing & Revenue Rules (NEW DOMAIN)

Domain 7: Payments & Financials (NEW DOMAIN)

Domain 8: Channels & Distribution (UNCHANGED)

Domain 9: Content & Metadata (MINOR ENHANCEMENTS)

Domain 10: Analytics & Audit (ENHANCED)

New Domains Added (V1.0)

1. Pricing & Revenue Rules (NEW)

2. Payments & Financials (NEW)

3. Guest Portal & Communication (NEW)

4. Operational Tools (NEW)

Breaking Changes

1. `bookings` Table Schema Expansion (BREAKING)

2. `holds` Table Enhanced (NON-BREAKING)

3. `availability_calendars` Unit-Level Support (NON-BREAKING)

Migration Path (MVP.2 → V1.0)

Phase 1: Database Schema Migration (Week 1)

Phase 2: Data Backfill (Week 1-2)

Phase 3: API Deployment (Week 2-3)

Phase 4: Integration Testing (Week 3)

Phase 5: Beta Launch (Week 4)

Phase 6: General Availability (Week 6)

Deprecations

1. Read-Only Booking Ingestion (DEPRECATED in V1.0)

2. Manual Price Updates (DEPRECATED in V1.0)

API Changes

New Endpoints (V1.0)

Quotes

Bookings

Payments

Refunds

Payouts

Pricing

Reports

Enhanced Endpoints (V1.0)

Bookings

Availability

Removed Endpoints

Configuration Changes

New Environment Variables (V1.0)

New Secrets (AWS Secrets Manager / GCP Secret Manager)

Performance Impact

Database Growth (MVP.2 → V1.0)

API Latency Targets

Background Job Load

Security Enhancements

PCI Compliance (V1.0)

Data Encryption (V1.0)

Access Control (V1.0)

Testing Requirements

New Test Suites (V1.0)

Documentation Updates

New Documentation Required (V1.0)

Success Metrics (V1.0 vs. MVP.2)

Risks & Mitigation

Risk 1: Payment Processing Downtime

Risk 2: Financial Reconciliation Errors

Risk 3: Pricing Engine Bugs

Risk 4: Migration Data Loss

Related Documents

Revision History