Skip to main content

TVL Platform - Sequence Flows

Summary​

This document illustrates key end-to-end workflows using sequence diagrams to show interactions between components, services, and external systems.

1. User Authentication Flow​

2. Create Property & Unit Flow​

3. Availability Check Flow​

4. Quote Generation Flow​

5. Hold Creation & Booking Confirmation Flow (with Payment)​

6. Hostaway Webhook Ingestion Flow​

7. Channel Sync Flow (Availability Push)​

8. Payment Failure & Retry Flow​

9. Admin Dashboard Load Flow​

Validation & Alternatives​

Workflow Optimizations​

✅ Agree: Hold mechanism prevents double-booking during payment flow

  • Alternative: Direct booking without hold (race condition risk)
  • Trade-off: Hold adds complexity but eliminates booking conflicts

✅ Agree: Asynchronous channel sync via job queue

  • Alternative: Synchronous sync (blocking API call)
  • Trade-off: Async is more resilient but adds latency (eventual consistency)

⚠️ Consider: Payment retry strategy

  • Current: Transient failures retried via job queue
  • Alternative: User-initiated retry only
  • Recommendation: Implement smart retry (transient errors only, not declined cards)

✅ Agree: Webhook idempotency via payload hashing

  • Alternative: Process all webhooks, accept duplicates
  • Trade-off: Idempotency prevents duplicate bookings but requires storage

Known Gaps & Assumptions​

Assumptions​

  1. Payment capture happens synchronously during booking confirmation (< 5s)
  2. Hostaway webhook delivery is reliable (they retry up to 3 times)
  3. Cache invalidation is sufficient (no cache stampede issues)
  4. Availability locks via holds expire after 15 minutes

Gaps​

  1. No distributed transaction pattern (saga) for booking + payment
    • Risk: Payment succeeds but booking fails (orphaned payment)
    • Mitigation: Compensating transaction (refund) on booking failure
  2. No concurrency control for availability checks
    • Risk: Two users book same unit simultaneously
    • Mitigation: Database unique constraint on unit_id + dates
  3. No webhook replay mechanism for processing failures
    • Risk: Missed webhook = out-of-sync data
    • Mitigation: Manual sync trigger + reconciliation job

Sources​

  • meta/research-log.md
  • docs/01-architecture/logical-architecture.md
  • docs/01-architecture/context-diagram.md