Skip to main content

TVL Platform Documentation

Status: Phase 2 Complete ✅ Last Updated: 2025-10-25 Documentation Version: 2.0

Overview​

This directory contains the complete Product Requirements Documentation (PRD) for the TVL vacation rental platform. The documentation is organized by product versions (MVP → V1 → V2 → V3) and domain-driven design principles.

Quick Navigation​

Looking for implementation details?

Directory Structure​

docs/product/
├── 00-index.md                          # Master navigation (START HERE)
├── README.md                            # This file
├── roadmap.md                           # Complete timeline with Gantt chart
│
├── specifications/                      # Product version specifications
│   ├── README.md                        # Specifications index
│   ├── mvp_overview.md                  # MVP strategy overview
│   ├── mvp.0_specification.md           # MVP.0 detailed spec (Weeks 1-10)
│   ├── mvp.1_specification.md           # MVP.1 detailed spec (Weeks 11-16)
│   ├── mvp.2_specification.md           # MVP.2 detailed spec (Weeks 17-24)
│   ├── v1_product-specification.md      # V1.0 vision (Villas Complete)
│   ├── v2_product-specification.md      # V2.0 vision (Events Complete)
│   └── v3_product-specification.md      # V3.0 vision (Global Marketplace)
│
├── deltas/                              # Version delta documents
│   ├── README.md                        # Delta documents index
│   ├── v1_delta-from-mvp.md             # What changed: MVP → V1
│   ├── v2_delta-from-v1.md              # What changed: V1 → V2
│   └── v3_delta-from-v2.md              # What changed: V2 → V3
│
├── data-models/                         # Database schemas by version
│   ├── README.md                        # Data models index
│   ├── mvp_data-model.md                # MVP complete schema (20 tables)
│   ├── v1_data-model.md                 # V1 complete schema (28 tables)
│   ├── v2_data-model.md                 # V2 complete schema (36 tables)
│   └── v3_data-model.md                 # V3 complete schema (54 tables)
│
├── domains/                             # Domain specifications (14 domains)
│   ├── 01-identity-tenancy/
│   │   ├── identity-tenancy_specification.md
│   │   ├── identity-tenancy_schema.sql
│   │   ├── identity-tenancy_version-mapping.md
│   │   └── identity-tenancy_seeds.sql
│   ├── 02-authorization-access/
│   │   ├── authorization-access_specification.md
│   │   ├── authorization-access_schema.sql
│   │   ├── authorization-access_version-mapping.md
│   │   └── authorization-access_seeds.sql
│   ├── 03-supply/ through 14-events-experiences/
│   │   └── (same structure: spec, schema, version-mapping, seeds if applicable)
│
├── migrations/                          # Database migrations by version
│   ├── mvp.0/
│   │   ├── README.md
│   │   ├── 001_initial_schema.sql       # Complete MVP.0 schema
│   │   ├── 002_rls_policies.sql         # Row-level security
│   │   └── 003_seed_data.sql            # Roles and permissions
│   ├── mvp.1/ through v3/               # Future migrations (stubs ready)
│
├── guides/                              # Implementation guides
│   ├── multi-tenancy-implementation.md  # RLS patterns and code examples
│   ├── channel-field-mappings.md        # Hostaway/Airbnb/VRBO transforms
│   ├── rls-policy-patterns.md           # Row-level security patterns
│   ├── product-versioning-strategy.md   # Feature flags and versioning
│   └── api-error-handling.md            # RFC 7807 error handling
│
├── source-prds/                         # Original source documents
│   ├── TVL-Platform-Specification-2025-10-21.md
│   ├── TVL Data and Domain Model Specification 2025-10-21 (1).md
│   └── tvl-mvp-v0-prd.updated.md
│
└── _project-management/                 # Project meta-documents
    ├── PHASE1_HANDOFF.md                # Phase 1 completion summary
    ├── PHASE2_COMPLETE.md               # Phase 2 final report
    ├── PHASE2_COMPLETION_SUMMARY.md     # Phase 2 statistics
    ├── PHASE2_FINAL_STATUS.md           # Phase 2 status report
    ├── VALIDATION_SUMMARY.md            # Link validation summary
    ├── LINK_FIXES_REQUIRED.md           # Link fixes needed
    ├── link-validation-report.md        # Detailed link analysis
    ├── broken-links-detailed.csv        # Broken links tracking
    └── validate_links.py                # Link validation script

Product Versioning Strategy​

MVP (Minimum Viable Product)​

Foundation for property distribution with 3 deployable increments:

  • MVP.0 (Weeks 1-10): Foundation + One-way Hostaway sync
  • MVP.1 (Weeks 11-16): Two-way sync + Booking awareness
  • MVP.2 (Weeks 17-24): Multi-channel (Airbnb, VRBO)

V1.0 - Villas Complete (Months 7-12)​

Full booking engine, payments, dynamic pricing, owner portal

V2.0 - Events Complete (Months 13-18)​

Add events/experiences domain, ticket sales, bundled packages

V3.0 - Global Marketplace (Months 19-24)​

Multi-vendor, white-label, franchise management, global expansion

See roadmap.md for complete timeline.

Domain-Driven Design​

The platform is decomposed into 14 bounded contexts (domains):

Core Business Domains​

  1. Identity & Tenancy - Multi-tenancy, user accounts, organizations
  2. Authorization & Access - RBAC, permissions, sessions
  3. Supply - Properties (spaces) and bookable inventory (units)
  4. Availability & Calendar - Time-based inventory control, blocking
  5. Pricing & Revenue - Dynamic pricing, fees, taxes, revenue splits
  6. Bookings - Reservation lifecycle (quotes, holds, confirmations)
  7. Payments & Financials - Payment processing, payouts, reconciliation

Supporting Domains​

  1. Content & Media - Property descriptions, photos, translations
  2. Channels & Distribution - Multi-channel syndication (Hostaway, Airbnb, VRBO)
  3. Delegation & Collaboration - Cross-org access, team management
  4. Search & Indexing - Full-text search, faceted filtering, geospatial
  5. Analytics & Audit - Metrics, reporting, compliance audit trail

Cross-Cutting Domains​

  1. System Architecture - Event-driven architecture, caching, queues
  2. Events & Experiences - Events/activities domain (V2.0+)

Each domain folder contains:

  • {domain}_specification.md - Complete domain specification
  • {domain}_schema.sql - Database schema (CREATE TABLE statements)
  • {domain}_version-mapping.md - Version applicability matrix
  • {domain}_seeds.sql - Seed data (where applicable)

File Naming Conventions​

Markdown Files​

  • Kebab-case with hyphens: identity-tenancy_specification.md
  • Version prefix: mvp.0, mvp.1, mvp.2, v1, v2, v3 (lowercase, dot separator)
  • Descriptive suffixes: _specification, _schema, _version-mapping, _seeds

SQL Files​

  • Kebab-case with hyphens: identity-tenancy_schema.sql
  • Migration numbering: 001_initial_schema.sql, 002_rls_policies.sql

Folders​

  • Numbered domains: 01-identity-tenancy, 02-authorization-access, etc.
  • Version folders: mvp.0, mvp.1, v1, v2 (lowercase)

Database Schema Standards​

All CREATE TABLE statements must follow these standards:

Required Columns​

id UUID PRIMARY KEY DEFAULT gen_random_uuid()
org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE
account_id UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE  -- for actor-owned entities
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()

Required Elements​

  • Primary keys (UUID with gen_random_uuid())
  • Foreign keys with ON DELETE behavior (CASCADE, SET NULL, RESTRICT)
  • Unique constraints where appropriate
  • Check constraints for data integrity
  • Indexes on foreign keys, org_id, account_id
  • JSONB columns with GIN indexes where applicable
  • Row-Level Security (RLS) policies

Multi-Tenancy​

  • ALL actor-owned tables MUST have both org_id AND account_id
  • System/lookup tables may have org_id only
  • RLS policies enforce org-level isolation

Implementation Guides​

Located in /docs/guides/:

Migration Strategy​

Database migrations are organized by version in migrations/:

  • mvp.0/ - Foundation schema (14 tables)
  • mvp.1/ - Two-way sync additions (availability, bookings read-only)
  • mvp.2/ - Multi-channel additions (Airbnb, VRBO connectors)
  • v1/ - Full booking engine, payments, pricing
  • v2/ - Events domain
  • v3/ - Enterprise features

Each migration folder contains:

  • README.md - Migration overview and order
  • 00X_*.sql - Numbered migration files
  • Rollback scripts where applicable

In This Repository​

External References​

Contributing​

When adding or modifying documentation:

  1. Follow naming conventions (kebab-case with hyphens)
  2. Extract from source PRDs - Don't invent content
  3. Maintain cross-references - Link related documents
  4. Keep files under 500 lines - Split if needed for LLM context
  5. Update version-mapping - Track which versions use each feature
  6. Validate schema standards - Ensure org_id + account_id on actor-owned tables

Phase 2 Completion Status ✅​

All Tasks Complete (100%)​

  • ✅ All 14 domain specifications (9,257 lines)
  • ✅ All 14 schema.sql files (7,147 lines)
  • ✅ All 14 version-mapping.md files (6,128 lines)
  • ✅ MVP.0, MVP.1, MVP.2 specifications (1,220 lines)
  • ✅ V1, V2, V3 product specifications
  • ✅ MVP, V1, V2, V3 data models (3,680 lines)
  • ✅ V1, V2, V3 delta documents (3,320 lines)
  • ✅ Migration SQL files for MVP.0 (1,691 lines)
  • ✅ Seed data files (508 lines)
  • ✅ 5 implementation guides (3,166 lines)
  • ✅ Link validation reports and tools
  • ✅ Naming standardization (MVP.0 format)
  • ✅ Folder organization (specifications/, deltas/, data-models/)

Total Documentation: 70 files, ~39,000 lines

See /.claude/sessions/PHASE2_COMPLETE.md for full details.

Questions or Issues?​

Refer to: