Skip to main content

Implementation Guides

Practical how-to guides for implementing TVL Platform features

This directory contains detailed implementation guides with code examples, patterns, and best practices for building TVL Platform functionality.

Overview​

Implementation guides bridge the gap between product specifications and actual code. Each guide provides:

  • Context - Why this pattern/approach is needed
  • Implementation - Step-by-step instructions with code examples
  • Best Practices - Recommended patterns and anti-patterns
  • Examples - Real-world code samples
  • Testing - How to validate the implementation

For product requirements, see: /docs/specifications/ For API specifications, see: /docs/reference/api/ For domain specifications, see: /docs/specifications/domains/

Quick Navigation​

🚀 Getting Started​

New to the project? Start here:

  1. Getting Started Guide - 15-minute developer onboarding
  2. Quick Environment Guide - Database setup TL;DR
  3. Environment Configuration - Deep dive into dev environments

🏗️ Core Patterns​

Essential implementation patterns for all developers:

🔌 Integration​

Building channel connectors and external integrations:

🛠️ Developer Setup​

Environment and secrets management:

Available Guides​

Quickstart Guides​

Getting Started​

Complete developer onboarding in 15 minutes.

Topics covered:

  • Dev container setup
  • Database connection verification
  • First API call
  • Common pnpm commands
  • Daily development workflow

Use this when:

  • You're a new developer joining the project
  • Setting up a new development machine
  • Onboarding team members

Doppler Setup​

Secrets management setup in 10 minutes.

Topics covered:

  • Doppler CLI installation
  • Authentication and project access
  • Secret syncing strategies
  • Troubleshooting common issues

Use this when:

  • Setting up secrets management
  • Configuring CI/CD pipelines
  • Managing environment variables across teams

Related: ADR-0008: Doppler Secrets Management

Database Setup​

Deep-dive into PostgreSQL, migrations, and RLS policies.

Topics covered:

  • Multi-tenancy rules (org_id + account_id)
  • RLS policy patterns
  • Migration templates
  • pgAdmin configuration
  • Testing database isolation

Use this when:

  • Creating new database tables
  • Writing database migrations
  • Testing RLS policies
  • Debugging multi-tenant data isolation

Related: ADR-0002: PostgreSQL Data Modeling

Core Platform Guides​

Quick Environment Guide​

TL;DR for choosing the right database environment.

Topics covered:

  • When to use local Docker PostgreSQL vs remote Supabase
  • Daily development workflow
  • Integration testing strategies
  • Staging and production environments

Use this when:

  • Confused about which database to use
  • Setting up local development
  • Planning integration tests
  • Troubleshooting environment issues

Related: Environment Configuration (full guide)

Environment Configuration​

Comprehensive guide to development environments.

Topics covered:

  • Dev container architecture
  • Docker Compose services
  • Environment variable management
  • Local vs remote database strategies
  • CI/CD environment configuration

Use this when:

  • Setting up dev containers
  • Configuring CI/CD pipelines
  • Troubleshooting environment issues
  • Planning multi-environment architecture

Related: Quick Environment Guide (TL;DR version)

Multi-Tenancy Implementation​

Complete guide to implementing multi-tenant isolation using PostgreSQL Row-Level Security (RLS).

Topics covered:

  • Organization and Account data model (3-tier: org → account → user)
  • RLS policy patterns for multi-tenant tables
  • Service layer code examples (TypeScript)
  • Testing multi-tenant isolation
  • Common pitfalls and solutions

Use this when:

  • Adding new tables to the system
  • Implementing domain services
  • Building API endpoints that access data
  • Debugging permission or data isolation issues

Related: ADR-0002: PostgreSQL Data Modeling

RLS Policy Patterns​

Standard Row-Level Security policy patterns for PostgreSQL.

Topics covered:

  • Basic RLS patterns (SELECT, INSERT, UPDATE, DELETE)
  • Multi-tenant isolation patterns
  • Owner-based access control
  • RBAC integration with RLS
  • Performance optimization for RLS queries
  • Testing RLS policies

Use this when:

  • Creating new database tables
  • Defining access control policies
  • Debugging permission issues
  • Optimizing query performance with RLS

Related: Multi-Tenancy Implementation

Channel Field Mappings​

Comprehensive field mapping guide for external channel integrations.

Topics covered:

  • Hostaway field mappings (properties, units, bookings, availability)
  • Airbnb field mappings (when available)
  • VRBO field mappings (when available)
  • Transformation logic and data type conversions
  • Handling missing/optional fields
  • Custom field extensions using JSONB

Use this when:

  • Building channel connectors
  • Syncing data from/to external platforms
  • Debugging field mapping issues
  • Adding new channel integrations

Related:

Product Versioning Strategy​

Guide to managing feature flags and version-gated functionality.

Topics covered:

  • Feature flag architecture
  • Version detection (MVP.0, MVP.1, MVP.2, V1.0, V2.0, V3.0)
  • Enabling/disabling features per organization
  • Database schema versioning
  • API endpoint versioning
  • Testing multi-version scenarios

Use this when:

  • Adding version-gated features
  • Planning database migrations
  • Building progressive feature rollout
  • Supporting multiple product tiers

Related: Product Roadmap

API Error Handling​

Standardized error handling following RFC 7807 (Problem Details).

Topics covered:

  • RFC 7807 Problem Details format
  • Standard error types and codes
  • Error response structure
  • Client error handling patterns
  • Logging and observability for errors
  • Error translation for external APIs

Use this when:

  • Building API endpoints
  • Handling errors in service layer
  • Implementing error middleware
  • Integrating with external APIs

Related: ADR-0025: RFC 7807 Error Handling

Guide Structure​

All implementation guides follow a standard structure:

# Guide Title

## Overview
Brief description and use cases

## Prerequisites
Required knowledge, tools, or setup

## Context
Why this approach? Problem being solved

## Implementation
Step-by-step instructions with code examples

## Code Examples
Real-world code samples (TypeScript/SQL)

## Best Practices
Recommended patterns and anti-patterns

## Testing
How to validate the implementation

## Troubleshooting
Common issues and solutions

## References
Related docs, ADRs, external resources

How to Use These Guides​

For New Developers​

  1. Start here:
  2. Setup essentials:
  3. Learn core patterns:

For Implementing New Features​

  1. Review relevant domain specification in /docs/specifications/domains/
  2. Check implementation guides for patterns to follow
  3. Review API specifications in /docs/reference/api/
  4. Check relevant ADRs in /docs/reference/decisions/
  5. Implement following guide patterns
  6. Test following guide recommendations

For Bug Fixes​

  1. Identify the domain and component
  2. Review relevant implementation guide for expected behavior
  3. Check troubleshooting section
  4. Verify implementation matches guide patterns
  5. Check ADRs for architectural decisions

For Code Reviews​

  1. Check that implementation follows guide patterns
  2. Verify multi-tenancy isolation (if applicable)
  3. Confirm error handling follows RFC 7807
  4. Validate RLS policies match patterns
  5. Check ADR compliance

Contributing New Guides​

When adding implementation guides:

  1. Follow the standard structure (see above)
  2. Include real code examples - TypeScript/SQL preferred
  3. Add troubleshooting section - Common issues and solutions
  4. Link to related docs - Specifications, ADRs, API specs
  5. Keep guides focused - Split large topics into multiple guides
  6. Update this README - Add your guide to the appropriate section
  7. Cross-reference ADRs - Link to relevant Architecture Decision Records

Naming Conventions​

  • Quickstart guides: quickstart/{topic}-setup.md or quickstart/{topic}.md
  • Implementation guides: {topic}-implementation.md or {pattern}-patterns.md
  • Configuration guides: {topic}-configuration.md

Frequently Asked Questions​

Q: How do I know which guide to use?

A: Start with the Getting Started Guide if you're new. For specific features, start with the domain specification, then find guides tagged with that domain.

Q: What's the difference between guides and specifications?

A:

  • Specifications (in /docs/specifications/) define WHAT to build (requirements, features, user stories)
  • Guides (in /docs/guides/) show HOW to build (code patterns, best practices, examples)
  • ADRs (in /docs/reference/decisions/) explain WHY we made technical decisions

Q: What if a guide conflicts with a specification?

A: Specifications are source of truth for WHAT to build. Guides show HOW to build. If they conflict on requirements, the specification wins. File an issue to update the guide.

Q: Can I suggest improvements to guides?

A: Yes! Submit a PR or create an issue with suggested changes. Guides should be living documents that improve over time.

Q: Are there code examples in other languages?

A: Currently focused on TypeScript/Node.js backend and React frontend (per ADR-0005, ADR-0006, ADR-0015, ADR-0016). Other languages are not planned at this time.

Q: Where are domain-specific implementation details?

A: Domain-specific specifications are in /docs/specifications/domains/. This /docs/guides/ folder contains cross-cutting implementation patterns (multi-tenancy, RLS, error handling, etc.) that apply to multiple domains.

Guide Statistics​

  • Total Guides: 10
    • Quickstart Guides: 3 (getting-started, doppler-setup, database-setup)
    • Core Platform Guides: 7 (environment, multi-tenancy, RLS, channel mappings, versioning, error handling, quick environment)
  • Last Updated: 2025-01-26
  • Maintained By: Engineering Team

Questions? See CONTRIBUTING.md or ask in #tvl-dev Slack channel.

Last Updated: 2025-01-26 Status: Active - All guides current and accurate