Skip to main content

Supply (Spaces & Units) - Version Mapping

Shows which product versions use this domain and to what extent.

Version Matrix​

VersionScopeTables UsedKey Features
MVP.0Fullspaces, units, unit_snapshots, amenities, space_amenitiesSingle-unit spaces (villa model), CRUD operations, version tracking, ~50 amenities, soft deletes
MVP.1Full(no changes)Enhanced UI for property management, bulk amenity assignment, improved search filters
V1.0Full+unit-level featuresMulti-unit properties UI, unit-level calendars, bulk unit operations, unit groups/categories
V1.1Full+custom_amenities, +property_hierarchyCustom amenity creation, parent/child spaces, geospatial optimization (PostGIS), media integration
V1.2Full+floor_plans, +accessibility_metadataStructured floor plans, accessibility compliance, sustainability certifications, dynamic attributes
V2.0Full+property_networks, +franchise_linksProperty networks, franchise management, cross-property amenities, regional groupings

Changes by Version​

MVP.0 - Villa Focus (Foundation)​

Scope: Full implementation focusing on single-unit properties (villas).

Tables:

  • spaces - Physical properties (villas, retreats, resorts)
  • units - Bookable inventory within spaces (typically 1 unit per space in MVP)
  • unit_snapshots - Immutable version history for sync and audit
  • amenities - Global catalog of property features (~50 standard amenities)
  • space_amenities - Junction table linking spaces to amenities (with optional parametric values)

Features:

  • Basic Space and Unit CRUD operations
  • Auto-create default Unit on Space creation
  • Automatic UnitSnapshot creation on every Unit update
  • Version tracking with monotonic version numbers
  • Diff hash computation to detect actual changes
  • Amenity catalog seeded with 6 categories:
    • Essentials (wifi, kitchen, heating/cooling)
    • Comfort (linens, toiletries, workspace)
    • Entertainment (TV, games, books)
    • Outdoor (pool, garden, terrace, BBQ)
    • Safety (smoke detector, fire extinguisher, first aid)
    • Accessibility (wheelchair access, grab bars)
  • Org/Account ownership enforcement via foreign keys
  • Soft delete via status='archived'
  • Address stored as JSONB (street, city, region, country, postal_code, lat, lng)
  • Capacity stored as JSONB (max_guests, bedrooms, bathrooms, beds)

Business Rules:

  • Every Space must have at least one Unit (auto-created)
  • Space slug unique within Org
  • Unit version increments by 1 on each update (monotonic)
  • UnitSnapshot records never updated or deleted (immutable)
  • All queries filter by org_id (application layer in MVP.0)
  • Status transitions: draft → active, active ↔ inactive, any → archived

Implementation Details:

  • 5 tables total
  • 15+ indexes for query performance
  • 8+ constraints for data integrity
  • JSONB fields for flexible metadata
  • RLS policies defined but not enforced (activated in MVP.1)

Channel Integration:

  • Unit snapshots enable idempotent sync to Hostaway/Airbnb
  • Diff hash prevents unnecessary API calls
  • Version numbers track last-synced state per channel

Deferred:

  • Multi-unit management UI (API supports, UI limited)
  • Bulk import/export tools
  • Advanced property hierarchy
  • Geospatial search optimization (basic lat/lng only)
  • Custom amenity creation

MVP.1 - Enhanced Property Management​

Scope: Full - Improved UI and search capabilities.

Changes from MVP.0:

  • Enhanced property management UI
  • Bulk amenity assignment workflow
  • Advanced search filters by amenity
  • Row-Level Security enforcement

New Features:

  • Multi-select amenity assignment (checkbox grid)
  • Amenity-based property search (AND/OR filters)
  • Property map view with clustering (Google Maps API)
  • RLS policies enforced at database level
  • Improved property listing performance

Implementation Changes:

  • Enable RLS on spaces, units, unit_snapshots tables
  • Add GiST index for geospatial queries (lat, lng)
  • Cache amenity catalog in Redis (rarely changes)
  • Search index includes amenity tags

V1.0 - Multi-Unit Properties​

Scope: Full - Support for resorts, retreats, and multi-room properties.

Changes from MVP.1:

  • Enhanced UI for managing multiple Units per Space
  • Unit-level calendar management (separate from Space)
  • Bulk unit operations (create, update, archive)
  • Unit groups and categories (room types)

Schema Changes:

  • Add unit_group_id column to units table (nullable, self-referencing groups)
  • Add unit_type ENUM to units table (studio, one_bed, two_bed, suite, villa)
  • Add unit_order column for display sorting

New Features:

  • Unit grid view (all units for a Space in table)
  • Clone unit functionality (copy settings to new unit)
  • Bulk edit units (change multiple units simultaneously)
  • Unit availability aggregation at Space level
  • Unit type filtering and grouping
  • Per-unit pricing support (different rates per room type)

Business Rules:

  • Space-level operations cascade to all child Units
  • Unit groups support categorization (e.g., "Garden Suites", "Ocean View Rooms")
  • Unit ordering determines display sequence in booking flow
  • Archive Space archives all Units (reversible)

Use Cases:

  • Resorts with 10+ rooms of different types
  • Retreat centers with multiple accommodation options
  • Villas with separate guest houses (counted as additional units)

V1.1 - Advanced Property Features​

Scope: Full - Custom amenities and property relationships.

Changes from V1.0:

  • Custom amenity creation per Org
  • Property hierarchy (parent/child Spaces for resorts/brands)
  • Geospatial search optimization (PostGIS)
  • Media management integration

New Tables:

  • custom_amenities - Org-specific amenity definitions
  • property_hierarchy - Parent-child relationships between Spaces

Schema Changes:

  • Add parent_space_id column to spaces table (nullable, self-referencing)
  • Add property_brand column to spaces table (brand affiliation)
  • Enable PostGIS extension for advanced geospatial queries

New Features:

  • Create org-specific amenities (beyond global catalog)
  • Property groups (brand with multiple locations)
  • Parent property manages child properties
  • Advanced geospatial search:
    • Within radius (miles/km from point)
    • Within bounding box (map viewport)
    • Proximity sorting (nearest first)
  • Media library integration (link photos to spaces/units)
  • Property comparison view (side-by-side amenities)

Business Rules:

  • Custom amenities scoped to Org (not shared globally)
  • Parent spaces aggregate data from children (occupancy, revenue)
  • Maximum hierarchy depth: 2 levels (parent → child only)
  • Circular references prevented via constraint

V1.2 - Enhanced Metadata​

Scope: Full - Compliance and detailed property information.

Changes from V1.1:

  • Structured floor plans and layouts
  • Accessibility compliance metadata
  • Sustainability certifications and ratings
  • Dynamic property attributes

New Tables:

  • floor_plans - Structured layout data (rooms, dimensions, connections)
  • accessibility_metadata - ADA/WCAG compliance details
  • certifications - Green certifications, ratings (LEED, Energy Star)

Schema Changes:

  • Add floor_plan_url to units table (link to uploaded plan image)
  • Add accessibility_score to spaces table (computed from metadata)
  • Add sustainability_rating to spaces table (computed from certifications)

New Features:

  • Upload and annotate floor plans
  • Accessibility checklist and scoring
  • Sustainability certification tracking
  • Seasonal closures (e.g., "Pool closed Nov-Mar")
  • Renovation status tracking
  • Historical property information (built year, renovated year)

Business Rules:

  • Accessibility metadata required for publicly listed properties
  • Floor plans must be to scale (validation)
  • Certifications expire and require renewal tracking
  • Dynamic attributes versioned (included in unit snapshots)

Compliance:

  • ADA Title III compliance for public accommodations
  • Local jurisdiction accessibility requirements
  • Environmental disclosure requirements

V2.0 - Multi-Location and Franchising​

Scope: Full - Enterprise-level property management.

Changes from V1.2:

  • Property networks and brand relationships
  • Franchise management features
  • Cross-property amenity sharing
  • Regional property groupings

New Tables:

  • property_networks - Defined networks (brands, franchises, partnerships)
  • network_memberships - Links Spaces to networks
  • franchise_agreements - Franchise-specific terms and configurations
  • regional_groupings - Geographic property clusters (markets)

Schema Changes:

  • Add network_id to spaces table (nullable, franchise affiliation)
  • Add franchise_tier ENUM to spaces table (owned, franchisee, affiliate)
  • Add market_id to spaces table (regional market assignment)

New Features:

  • Brand management dashboard (all properties in network)
  • Franchise agreement tracking and compliance
  • Cross-property reporting and analytics
  • Shared amenity inventory (e.g., shuttle service, concierge)
  • Regional market analysis
  • Network-wide search and discovery
  • Franchise fee calculations
  • Centralized brand standards enforcement

Business Rules:

  • Franchisees have limited org admin rights
  • Brand owners can view all franchise properties
  • Network memberships require approval workflow
  • Regional groupings determined by proximity and market

Use Cases:

  • Luxury villa brands with 50+ properties globally
  • Boutique hotel franchises
  • Property management companies with regional offices
  • Vacation rental cooperatives

Analytics:

  • Network-wide occupancy rates
  • Franchise performance benchmarking
  • Regional market trends
  • Cross-property guest preferences

Operational Notes​

MVP.0 Performance Targets​

  • Space creation: <200ms
  • Unit update with snapshot: <150ms
  • Amenity assignment: <100ms
  • Property search (no filters): <300ms

Monitoring Requirements​

  • Track Space creation rate (growth metric)
  • Monitor Unit update frequency (content activity)
  • Alert on failed snapshot creation (data integrity issue)
  • Track amenity usage (feature adoption)

Scaling Considerations​

  • Spaces table grows with property acquisition
  • Unit_snapshots is write-heavy (one record per unit update)
  • Partition unit_snapshots by year for performance (V1.2+)
  • Amenities table is read-heavy (cache in Redis)
  • Space_amenities junction table grows with property detail

Backup & Retention​

  • Unit snapshots retained 90 days by default (configurable)
  • Archived spaces retained indefinitely (soft delete only)
  • Snapshot pruning job runs weekly (delete snapshots older than retention period)
  • Media assets backed up separately (Content domain)

Channel Sync Performance​

  • Snapshot creation triggers async sync jobs
  • Diff hash prevents redundant API calls to Hostaway/Airbnb
  • Sync status tracked per channel listing
  • Failed syncs retry with exponential backoff