MVP.0 - Foundation + One-Way Distribution
Timeline: Weeks 1-10
Status: In Design
Business Value: Single source of truth for properties, automated Hostaway distribution
Overview
MVP.0 establishes the foundational platform where property managers can manage their villa portfolio centrally and automatically distribute listings to Hostaway. This is a one-way sync (TVL → Hostaway) with manual retry capabilities.
Core Capabilities
1. Authentication & Access
- Google SSO (OIDC with PKCE)
- Server-side sessions with secure cookies
- Role-based access control (RBAC)
- 4 roles: Owner, ChannelPublisher, ContentManager, Viewer
2. Multi-Tenancy
- Organization management
- Account (sub-tenant) management
- User membership system
- Org-level data isolation
3. Supply Management
- Space CRUD (physical properties)
- Unit CRUD (bookable inventory)
- Basic amenity management
- Media URLs (no upload pipeline)
- Unit versioning and snapshots
4. Channel Distribution
- Hostaway channel target configuration
- Unit → Hostaway listing mapping
- One-way sync (TVL → Hostaway)
- Idempotent sync with payload hashing
- Manual retry mechanism
- Per-target rate limiting
5. Observability
- Structured JSON logging
- Basic metrics (sync success rate, latency)
- Audit trail for sync operations
- Sync status dashboard
Domains Implemented
| Domain | Scope | Priority |
|---|
| Identity & Tenancy | Full | CRITICAL |
| Authorization & Access | RBAC only | CRITICAL |
| Supply | Basic CRUD | CRITICAL |
| Channels & Distribution | One-way sync | CRITICAL |
| Analytics & Audit | Basic logging | HIGH |
Database Schema (14 Tables)
Identity & Tenancy (5 tables)
organizations - Top-level tenant boundaryaccounts - Sub-tenants within orgusers - Person identity (email-based)memberships - User → Org/Account + Rolesessions - Server-side session storage
Authorization (2 tables)
roles - Permission bundles (admin, ops, etc.)permissions - Action registry
Supply (3 tables)
spaces - Physical properties (villas)units - Bookable inventoryunit_snapshots - Version history
Channels (3 tables)
channel_targets - Hostaway site connectionschannel_listings - Unit → Listing mappingsoutbound_audit - Sync operation logs
Analytics (1 table)
audit_events - System-wide audit trail
Functional Requirements
FR-1: Google SSO Authentication
- Given: User visits TVL admin console
- When: User clicks "Sign in with Google"
- Then: OIDC auth code + PKCE flow initiated
- And: Session created with secure cookies
- And: User auto-provisioned as Viewer on first login
FR-2: Organization & Account Management
- Given: User with Owner role
- When: Creates new organization
- Then: Default account auto-created
- And: Creator assigned admin membership
- And: All subsequent resources scoped to org_id + account_id
FR-3: Space and Unit Management
- Given: User with ContentManager role
- When: Creates or updates Unit
- Then: Unit record persisted with version increment
- And: Unit snapshot created with diff hash
- And: Change logged to audit trail
FR-4: Channel Target Setup
- Given: User with Owner role
- When: Adds Hostaway channel target
- Then: API token stored in Secrets Manager
- And: Reference saved in channel_targets table
- And: Health check scheduled
FR-5: Unit → Hostaway Linking
- Given: User with ChannelPublisher role
- When: Links Unit to Hostaway target
- Then: channel_listing record created
- And: Sync job enqueued
- And: Status shown as "pending"
FR-6: One-Way Sync Execution
- Given: Sync job for (unit, target) pair
- When: Worker processes job
- Then: Payload built from current Unit state
- And: Idempotency key computed (sha256 of version + target)
- And: HTTP PUT to Hostaway API (if payload hash changed)
- And: Response logged to outbound_audit
- And: channel_listing status updated
- And: Retry scheduled on failure (max 3 attempts)
FR-7: Rate Limiting
- Given: Multiple sync jobs for same target
- When: Worker attempts requests
- Then: Per-target limiter enforces ≤12 req/10s
- And: 429 responses trigger fixed delay (5s)
- And: Failed jobs retried up to max attempts
FR-8: Manual Retry
- Given: Failed sync visible in dashboard
- When: Operator clicks "Retry"
- Then: New sync job enqueued
- And: Retry count incremented
- And: Status updated to "pending"
FR-9: Sync Status Dashboard
- Given: User with any role
- When: Views sync status page
- Then: List of all channel_listings shown
- And: Status, last_synced_at, error_message displayed
- And: Retry button for failed syncs
- And: Audit log accessible
Non-Functional Requirements
- Sync latency: <1 minute for single Unit
- API response time: <500ms (p95)
- Database queries: <100ms (p95)
NFR-2: Reliability
- Sync success rate: 99%+
- Zero data loss on sync failures
- Idempotent operations (safe retries)
NFR-3: Security
- Cookies: HttpOnly, Secure, SameSite=Lax
- API tokens: Secrets Manager only
- Session rotation on role changes
- Audit all sensitive operations
NFR-4: Scalability
- Support 10+ properties in MVP.0
- Support 1 Hostaway target
- Prepare for 100+ properties in MVP.1
Technical Architecture
Stack
- Backend: Node.js 20+ with TypeScript
- Framework: Express.js
- Database: PostgreSQL 15+
- Queue: BullMQ + Redis
- Auth: Google OIDC (Passport.js)
- Secrets: AWS Secrets Manager or GCP Secret Manager
- Deployment: Docker + Kubernetes
Key Design Decisions
| Decision | Choice | Rationale |
|---|
| Auth | Google SSO only | Simplest MVP, deferred email/password |
| Sessions | Server-side | Better security, session revocation |
| Sync | One-way (TVL → Hostaway) | Defer booking ingestion to MVP.1 |
| Idempotency | Payload hash | Prevent duplicate API calls |
| Rate Limiting | Per-target limiter | Avoid 429s, continue other targets |
| Retry | Fixed delay (5s) | Simple, defer jitter to MVP.1 |
| Snapshots | Simple audit log | Defer diff UI to MVP.1 |
Success Metrics
| Metric | Target | Measurement |
|---|
| Properties managed | 10+ | Count in spaces table |
| Sync success rate | 99%+ | outbound_audit success % |
| Sync latency | <1 min | Time from update to Hostaway |
| Zero data loss | 100% | No failed syncs without retry |
| User adoption | 3+ active users | sessions table |
Out of Scope (Deferred)
Deferred to MVP.1
- Two-way sync (Hostaway → TVL)
- Booking ingestion
- Availability calendar
- Pricing display
Deferred to MVP.2
- Multi-channel (Airbnb, VRBO)
- Conflict detection
- Advanced retry logic (jitter)
Deferred to V1.0
- Direct bookings
- Payment processing
- Dynamic pricing
- Guest portal
Dependencies
External Dependencies
- Google OIDC (cloud.google.com/identity)
- Hostaway API (docs.hostaway.com)
- Secrets Manager (AWS or GCP)
Internal Dependencies
Risks & Mitigation
| Risk | Impact | Probability | Mitigation |
|---|
| Hostaway API rate limits | HIGH | MEDIUM | Per-target limiters, monitoring |
| Google SSO downtime | HIGH | LOW | Clear error messages, retry logic |
| Database schema changes | MEDIUM | MEDIUM | Versioned migrations, no breaking changes |
| Security vulnerabilities | HIGH | LOW | OWASP checklist, security review |
Acceptance Criteria
Delivery Plan
Week 1-2: Foundation
- Database schema creation
- Migrations
- Google SSO integration
- Session management
Week 3-4: Supply Management
- Space/Unit CRUD APIs
- Unit snapshots
- Basic admin UI
Week 5-6: Supply UI
- Space/Unit forms
- Media URL management
- Amenity selection
Week 7-8: Channel Integration
- Hostaway connector
- Channel target management
- Listing mapping
- Sync job queue
Week 9: Testing & Hardening
- Integration tests
- Load testing
- Security review
- Bug fixes
Week 10: Launch Prep
- Documentation
- Runbooks
- Staging validation
- Production deployment