Skip to main content

Reference Documentation

Quick reference materials, ADRs, patterns, and glossary

This directory contains consolidated reference materials for quick lookups, architectural decisions, UI component specifications, and connector documentation.

Overview​

The reference section provides quick-access documentation for:

  • Architecture Decision Records (ADRs) - Key technical decisions and rationale
  • UI Component Specifications - Admin interface patterns and components
  • Connector Specifications - External system integration details
  • Glossary - Platform terminology and definitions

For implementation details, see: /docs/guides/ For product specifications, see: /docs/specifications/

Contents​

📋 Architecture Decisions (ADRs)​

Architecture Decision Records documenting key technical choices and their rationale.

Standard ADRs:

When to read ADRs:

  • Understanding why a technical decision was made
  • Evaluating alternative approaches
  • Making new architectural decisions (learn from previous rationale)
  • Onboarding new team members to architecture

ADR Format:

# ADR-NNNN: Decision Title

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
Problem statement and constraints

## Decision
What was decided

## Consequences
Benefits and drawbacks

## Alternatives Considered
Other options and why they weren't chosen

🎨 UI Component Specifications​

Admin interface specifications, UI patterns, and component libraries.

Topics covered:

  • Admin UI specification
  • Component library (shadcn/ui)
  • Layout patterns
  • Form patterns
  • Table/grid patterns
  • Navigation structure

When to use:

  • Building admin interface features
  • Implementing new UI components
  • Ensuring consistent UX patterns
  • Code reviews for frontend changes

🔗 Connector Specifications​

External system integration specifications for channel connectors.

Available Connectors:

  • Hostaway - Property management system (MVP.0+)
  • Airbnb - Short-term rental platform (MVP.2+)
  • VRBO - Vacation rental platform (MVP.2+)

Connector documentation includes:

When to use:

  • Integrating new channels
  • Debugging sync issues
  • Understanding field transformations
  • Planning connector features

📖 Glossary​

Platform terminology, acronyms, and definitions.

Categories:

  • Domain Terms - Business concepts (property, unit, booking, etc.)
  • Technical Terms - Architecture concepts (RLS, tenant, domain, etc.)
  • Acronyms - TVL-specific abbreviations
  • External Terms - Third-party system terminology

When to use:

  • Understanding platform terminology
  • Clarifying ambiguous terms
  • Onboarding new team members
  • Writing documentation consistently

Example entries:

  • Property - A physical vacation rental location (villa, apartment, etc.)
  • Unit - A bookable space within a property (entire place, or specific room)
  • Organization (Org) - Top-level tenant in multi-tenant architecture
  • RLS - Row-Level Security (PostgreSQL feature for data isolation)

Quick Reference Patterns​

Multi-Tenancy​

-- Standard multi-tenant table pattern
CREATE TABLE example_table (
  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,
  -- ... other columns
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Enable RLS
ALTER TABLE example_table ENABLE ROW LEVEL SECURITY;

-- Standard tenant isolation policy
CREATE POLICY tenant_isolation ON example_table
  USING (org_id = current_setting('app.current_org_id')::uuid);

See Multi-Tenancy Implementation Guide for complete details.

Error Response Format (RFC 7807)​

{
  "type": "https://api.tvl.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Property name is required",
  "instance": "/properties/123",
  "errors": [
    {
      "field": "name",
      "message": "Name must not be empty"
    }
  ]
}

See API Error Handling Guide for complete details.

Feature Flag Check​

// TypeScript example
import { isFeatureEnabled } from '@/lib/feature-flags';

async function createBooking(orgId: string, data: BookingData) {
  // Check if org has booking feature enabled
  if (!await isFeatureEnabled(orgId, 'bookings.direct_booking')) {
    throw new FeatureNotEnabledError('Direct booking not available for your plan');
  }

  // ... proceed with booking creation
}

See Product Versioning Strategy for complete details.

How to Use This Section​

For Quick Lookups​

  1. Term unclear? → Check Glossary
  2. Why was X decided? → Check ADRs
  3. How to integrate Y? → Check Connectors
  4. UI pattern for Z? → Check UI

For In-Depth Understanding​

  1. Start with quick reference here
  2. Follow links to detailed guides in /docs/guides/
  3. Review product specifications in /docs/specifications/
  4. Check API contracts in /docs/reference/api/

Contributing to Reference Docs​

Adding a New ADR​

  1. Use next sequential number: adr-NNNN-short-title.md
  2. Follow ADR template structure (Status, Context, Decision, Consequences)
  3. Link to related ADRs and product specs
  4. Update this README with new ADR in list above

Updating Glossary​

  1. Add term in alphabetical order within category
  2. Provide clear, concise definition
  3. Link to related documentation where applicable
  4. Use consistent formatting

Adding UI Patterns​

  1. Include visual examples (screenshots or diagrams)
  2. Provide code examples (React/TypeScript)
  3. Document responsive behavior
  4. Link to component library (shadcn/ui)

Adding Connector Docs​

  1. Follow existing connector documentation structure
  2. Include API version and authentication details
  3. Document all webhook events
  4. Provide field mapping tables
  5. Include error handling patterns

Reference Statistics​

CategoryCountLast Updated
ADRs4+2025-10-24
UI Specifications1+2025-10-24
Connectors3 (Hostaway, Airbnb, VRBO)2025-10-24
Glossary Terms50+2025-10-24

Last Updated: 2025-10-25 Version: 3.0 (Unified Structure)