Skip to main content

TVL Platform - Context Diagram

Summary​

This document provides a high-level system context view (C4 Level 1) showing TVL platform boundaries, external actors, and system integrations.

System Context​

plantuml

Actor Descriptions​

Internal Users (Authenticated via Google OIDC)​

Property Manager​

  • Role: Primary user persona
  • Responsibilities:
    • Manage property portfolio (5-500+ properties)
    • Configure pricing and availability
    • Monitor bookings and revenue
    • Respond to channel inquiries
  • Access Level: Full access to assigned properties within organization

Property Owner​

  • Role: Passive oversight, may delegate to manager
  • Responsibilities:
    • View performance reports
    • Approve or block bookings (optional)
    • Access financial statements
  • Access Level: Read-only or approval-only for owned properties

Operations Staff​

  • Role: Day-to-day operations
  • Responsibilities:
    • Process bookings and cancellations
    • Update calendars with blocks
    • Coordinate maintenance
  • Access Level: Limited write access to assigned properties

Finance/Accounting​

  • Role: Financial management
  • Responsibilities:
    • Reconcile transactions
    • Generate tax reports
    • Track payouts
  • Access Level: Read-only financial data across organization

Platform Administrator (TVL Internal)​

  • Role: System operator
  • Responsibilities:
    • Monitor platform health
    • Manage tenant accounts
    • Troubleshoot integration issues
    • Deploy updates
  • Access Level: Super-admin across all tenants

External Systems​

Hostaway PMS​

  • Type: Property Management System (PMS)
  • Integration Pattern: Bi-directional REST API + Webhooks
  • Data Flow:
    • Outbound (TVL → Hostaway): Property updates, manual sync triggers
    • Inbound (Hostaway → TVL): Bookings, availability changes, guest data
  • Authentication: API key per tenant
  • Rate Limits: 100 requests/min per tenant

OTA Channels (Airbnb, VRBO, Booking.com)​

  • Type: Online Travel Agencies
  • Integration Pattern: Indirect via Hostaway connector
  • Data Flow:
    • Outbound: Listing publication, availability sync, pricing updates
    • Inbound: Bookings, guest messages, reviews
  • Note: TVL does not directly integrate with channel APIs; Hostaway acts as aggregator

Google OIDC​

  • Type: Authentication Provider
  • Integration Pattern: OpenID Connect (OAuth 2.0)
  • Data Flow: User authentication and profile retrieval
  • Credentials: OAuth client ID and secret

Stripe​

  • Type: Payment Processor
  • Integration Pattern: REST API + Webhooks
  • Data Flow:
    • Outbound: Payment intent creation, capture, refund
    • Inbound: Webhook events (payment succeeded, failed, etc.)
  • Authentication: API key (secret) per environment
  • PCI Compliance: Stripe handles card data; TVL never stores PAN

Email Service (SendGrid / AWS SES)​

  • Type: Transactional Email
  • Integration Pattern: SMTP or REST API
  • Data Flow: Outbound only (notifications, reports, invitations)
  • Templates: Booking confirmation, cancellation, payment receipt

SMS Service (Twilio)​

  • Type: SMS Gateway
  • Integration Pattern: REST API
  • Data Flow: Outbound only (urgent alerts, 2FA codes)
  • Rate Limits: Configurable per account

Object Storage (AWS S3 / Supabase Storage)​

  • Type: Blob storage
  • Integration Pattern: S3-compatible API
  • Data Flow:
    • Upload: Property images, documents, reports
    • Download: Signed URLs with expiration
  • Bucket Policy: Private with signed URL access

HubSpot CRM​

  • Type: Customer Relationship Management
  • Integration Pattern: MCP (Model Context Protocol)
  • Data Flow: Sync customer accounts, usage metrics for sales team
  • Authentication: OAuth 2.0

Grafana Cloud​

  • Type: Observability Platform
  • Integration Pattern: OpenTelemetry (OTel) push
  • Data Flow:
    • Metrics (Prometheus format)
    • Traces (Tempo)
    • Logs (Loki)
  • Authentication: API key

Sentry​

  • Type: Error Tracking
  • Integration Pattern: SDK (Node.js, React)
  • Data Flow: Exception reports, performance monitoring
  • Authentication: DSN (Data Source Name)

System Boundary​

Inside TVL Platform​

  • User authentication and authorization
  • Property and unit management
  • Availability calendar
  • Pricing engine
  • Booking workflow
  • Payment orchestration (not processing)
  • Admin UI
  • Background job processing
  • API gateway
  • Database (Postgres)
  • Cache and queue (Redis)

Outside TVL Platform (External Dependencies)​

  • Channel distribution (via Hostaway)
  • Payment processing (Stripe)
  • Authentication (Google)
  • Email/SMS delivery
  • Object storage
  • Observability collection
  • CRM data

Data Flow Summary​

Inbound Data Flows​

  1. User Actions → TVL Platform

    • Property CRUD operations
    • Booking management
    • Configuration changes

  2. Hostaway Webhooks → TVL Platform

    • New bookings from channels
    • Availability changes
    • Guest information updates

  3. Stripe Webhooks → TVL Platform

    • Payment confirmations
    • Refund completions
    • Payment failures

  4. Google OIDC → TVL Platform

    • User authentication tokens
    • Profile information

Outbound Data Flows​

  1. TVL Platform → Hostaway API

    • Property synchronization
    • Manual sync triggers

  2. TVL Platform → Stripe API

    • Payment intent creation
    • Payment capture
    • Refund requests

  3. TVL Platform → Email/SMS Services

    • Transactional notifications
    • Alerts and reports

  4. TVL Platform → Object Storage

    • Property image uploads
    • Document storage

  5. TVL Platform → Observability Systems

    • Metrics, traces, logs
    • Error reports

  6. TVL Platform → HubSpot (via MCP)

    • Customer account sync
    • Usage metrics

Network & Security Boundaries​

Public Internet​

  • Web UI (Vercel CDN)
  • API endpoints (Railway/Fly with TLS)
  • Webhook receivers (authenticated)

Private Network​

  • Supabase Postgres (connection pooler)
  • Redis (Upstash via TLS)
  • Internal service-to-service communication (if microservices deployed)

Managed Services​

  • All external integrations via HTTPS
  • API keys stored in Secret Manager
  • No direct database access from external systems

Validation & Alternatives​

Architectural Decisions​

✅ Agree: Using Hostaway as channel aggregator reduces integration complexity

  • Alternative: Direct channel integrations (Airbnb, VRBO APIs)
  • Trade-off: Dependency on Hostaway, but 80% faster time-to-market

✅ Agree: Google OIDC-only authentication for MVP

  • Alternative: Magic links, social auth (Facebook, Apple)
  • Trade-off: Less flexibility, but simpler implementation and security

✅ Agree: Stripe as payment processor

  • Alternative: PayPal, Square, Adyen
  • Trade-off: Stripe has best developer experience and API

⚠️ Consider: Direct S3 vs. Supabase Storage

  • Current: Supabase Storage (simpler, integrated)
  • Alternative: AWS S3 (more features, CDN options)
  • Recommendation: Start with Supabase, migrate to S3 if storage costs or CDN requirements grow

Known Gaps & Assumptions​

Assumptions​

  1. Hostaway uptime and reliability is acceptable (no SLA defined)
  2. Google OIDC availability > 99.9%
  3. Stripe webhook delivery is reliable (they retry up to 3 days)
  4. All external services support HTTPS/TLS 1.2+

Gaps​

  1. No backup channel aggregator if Hostaway fails
  2. No fallback authentication if Google OIDC is down
  3. No disaster recovery for Supabase (managed service handles this)

Mitigation Strategies​

  1. Hostaway Dependency: Design connector interface to be pluggable; document migration path
  2. Auth Fallback: Consider magic link backup auth (future)
  3. Payment Redundancy: Stripe automatic retries + manual admin interface for failed payments

Sources​

  • meta/research-log.md
  • docs/00-overview/platform-overview.md
  • domains/system-architecture-scalability.md