feat: subscription tiers, period filter, dashboards, docs

- Add subscription tiers (Basic/Pro/Business) with listing limits and dynamic commission - Add daily/monthly period filter on rentals page - Add landlord dashboard with earnings chart, stat cards, property performance - Add landlord subscription management page - Add tenant dashboard with upcoming stays - Add business model documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 16:19:33 -08:00
parent 68beca8f30
commit dcd2dcb841
24 changed files with 1352 additions and 167 deletions
--- a/docs/business-model.md
+++ b/docs/business-model.md
@@ -0,0 +1,56 @@
+# Revenue Model
+
+## Overview
+
+The platform generates revenue through 5 distinct streams, creating a diversified monetization strategy.
+
+## Revenue Streams
+
+### 1. Listing Fee (Marketplace)
+- **Amount:** $5 per marketplace listing
+- **Who pays:** Seller
+- **When:** At listing creation
+
+### 2. Marketplace Commission
+- **Rate:** 5% of sale price
+- **Who pays:** Seller (deducted from payout)
+- **When:** Upon successful sale completion
+
+### 3. Rental Commission
+- **Rate:** 5-10% of booking subtotal (varies by landlord subscription tier)
+- **Who pays:** Landlord (deducted from payout)
+- **When:** Upon booking completion
+
+| Tier | Commission Rate |
+|------|----------------|
+| BASIC | 10% |
+| PRO | 7% |
+| BUSINESS | 5% |
+
+### 4. Promoted Listings
+- **Rate:** $2.99 - $3.99 per day
+- **Who pays:** Seller / Landlord
+- **Description:** Boosted visibility in search results and category pages
+
+### 5. Subscription Plans
+
+| Plan | Monthly Price |
+|------|--------------|
+| BASIC | Free |
+| PRO | $9.99/month |
+| BUSINESS | $29.99/month |
+
+- **Who pays:** Landlord
+- **When:** Monthly recurring
+
+## Revenue Formula
+
+```
+Total Revenue = Listing Fees + Marketplace Commission + Rental Commission + Promotions + Subscriptions
+
+Monthly Revenue = (N_listings × $5)
+                + (GMV_marketplace × 0.05)
+                + (GMV_rental × avg_commission_rate)
+                + (N_promos × avg_promo_price × avg_days)
+                + (N_pro × $9.99 + N_business × $29.99)
+```
--- a/docs/commission-structure.md
+++ b/docs/commission-structure.md
@@ -0,0 +1,64 @@
+# Commission Structure
+
+## Overview
+
+The platform charges two types of commissions: marketplace commissions on product sales and rental commissions on property bookings.
+
+## Marketplace Commission
+
+- **Rate:** 5% of sale price (fixed, configured in PlatformConfig)
+- **Payer:** Seller
+- **Deduction:** Automatically deducted from seller payout
+- **Formula:**
+
+```
+Commission = Sale Price × 0.05
+Seller Payout = Sale Price - Commission
+```
+
+**Example:** Product sold for $100
+- Commission: $100 × 5% = $5.00
+- Seller receives: $95.00
+
+## Rental Commission
+
+- **Rate:** Variable, 5-10% based on landlord's subscription tier
+- **Payer:** Landlord
+- **Deduction:** Automatically deducted from landlord payout on booking completion
+
+| Tier | Commission Rate | Effective Savings vs BASIC |
+|------|----------------|--------------------------|
+| BASIC | 10% | - |
+| PRO | 7% | 30% less commission |
+| BUSINESS | 5% | 50% less commission |
+
+### Formula
+
+```
+Commission Amount = Booking Subtotal × (Tier Commission Rate / 100)
+Landlord Payout = Booking Subtotal - Commission Amount
+Total Charged to Tenant = Booking Subtotal + Deposit
+```
+
+### Calculation Flow
+
+1. Tenant creates booking request
+2. System looks up landlord's subscription tier
+3. Commission rate is determined from TIER_CONFIG
+4. Commission is calculated on subtotal (price × periods)
+5. On completion, payout is created: gross - commission = net
+
+### Example: $1,000 Monthly Booking
+
+| Component | BASIC (10%) | PRO (7%) | BUSINESS (5%) |
+|-----------|-------------|----------|---------------|
+| Subtotal | $1,000 | $1,000 | $1,000 |
+| Commission | $100 | $70 | $50 |
+| Landlord Payout | $900 | $930 | $950 |
+| Platform Revenue | $100 | $70 | $50 |
+
+## Deposit Handling
+
+- Deposits are separate from commission calculations
+- Deposits are fully returned on cancellation (regardless of refund policy)
+- Deposits are not subject to commission
--- a/docs/growth-projections.md
+++ b/docs/growth-projections.md
@@ -0,0 +1,97 @@
+# Growth Projection Template
+
+## Key Formulas
+
+### Monthly Recurring Revenue (MRR)
+
+```
+MRR = (N_pro × $9.99) + (N_business × $29.99) + Monthly Commission Revenue
+
+Monthly Commission Revenue = Sum of all booking commissions in month
+```
+
+### Annual Recurring Revenue (ARR)
+
+```
+ARR = MRR × 12
+```
+
+### Customer Lifetime Value (LTV)
+
+```
+LTV = ARPL × Average Customer Lifetime (months)
+
+ARPL = (Subscription Revenue + Commission Revenue) / Total Active Landlords
+
+Average Customer Lifetime = 1 / Monthly Churn Rate
+```
+
+### Customer Acquisition Cost (CAC)
+
+```
+CAC = Total Marketing Spend / New Landlords Acquired
+
+LTV:CAC Ratio target: > 3:1
+```
+
+### Average Booking Value (ABV)
+
+```
+ABV = Total Booking GMV / Number of Bookings
+```
+
+## Projection Model
+
+### Assumptions
+
+| Metric | Month 1 | Month 6 | Month 12 |
+|--------|---------|---------|----------|
+| Total Landlords | 50 | 300 | 1,000 |
+| BASIC (%) | 80% | 60% | 50% |
+| PRO (%) | 15% | 25% | 30% |
+| BUSINESS (%) | 5% | 15% | 20% |
+| Avg Bookings/Landlord/mo | 2 | 3 | 4 |
+| Avg Booking Value | $300 | $350 | $400 |
+| Monthly Churn | 10% | 7% | 5% |
+
+### Revenue Projections
+
+| Revenue Stream | Month 1 | Month 6 | Month 12 |
+|---------------|---------|---------|----------|
+| **Subscriptions** | | | |
+| PRO (N × $9.99) | $74.93 | $749.25 | $2,997.00 |
+| BUSINESS (N × $29.99) | $74.98 | $1,349.55 | $5,998.00 |
+| **Rental Commissions** | | | |
+| BASIC (10%) | $2,400 | $18,900 | $80,000 |
+| PRO (7%) | $315 | $3,675 | $33,600 |
+| BUSINESS (5%) | $75 | $1,575 | $16,000 |
+| **Total Monthly Revenue** | **$2,939.91** | **$26,248.80** | **$138,595.00** |
+
+### Growth Metrics
+
+```
+Month-over-Month Growth = (MRR_current - MRR_previous) / MRR_previous × 100
+
+Net Revenue Retention = (MRR from existing customers at end) / (MRR from same customers at start) × 100
+
+Gross Margin = (Revenue - COGS) / Revenue × 100
+  COGS = Stripe fees + Hosting + Support
+  Target Gross Margin: > 70%
+```
+
+## Scenario Planning
+
+### Conservative
+- 30% MoM landlord growth
+- 60% stay on BASIC
+- ABV: $250
+
+### Base
+- 50% MoM landlord growth
+- 50% upgrade to PRO/BUSINESS within 6 months
+- ABV: $350
+
+### Aggressive
+- 80% MoM landlord growth
+- 60% upgrade to PRO/BUSINESS within 3 months
+- ABV: $500
--- a/docs/subscription-tiers.md
+++ b/docs/subscription-tiers.md
@@ -0,0 +1,54 @@
+# Subscription Tier Comparison
+
+## Tier Overview
+
+| Feature | BASIC | PRO | BUSINESS |
+|---------|-------|-----|----------|
+| **Monthly Price** | Free | $9.99 | $29.99 |
+| **Max Active Listings** | 3 | 10 | Unlimited |
+| **Commission Rate** | 10% | 7% | 5% |
+| **Promo Discount** | None | 25% off | Free |
+| **Badge** | None | Priority | Verified |
+| **Advanced Analytics** | No | No | Yes |
+
+## Detailed Breakdown
+
+### BASIC (Free)
+- Best for: New landlords testing the platform
+- Up to 3 active rental listings
+- Standard 10% commission on bookings
+- No promotional discounts
+- No special badges
+- Basic dashboard access
+
+### PRO ($9.99/month)
+- Best for: Growing landlords with multiple properties
+- Up to 10 active rental listings
+- Reduced 7% commission (30% savings vs BASIC)
+- 25% discount on promoted listings
+- Priority badge on listings
+- Standard dashboard access
+
+### BUSINESS ($29.99/month)
+- Best for: Professional property managers
+- Unlimited active rental listings
+- Lowest 5% commission (50% savings vs BASIC)
+- Free promoted listings
+- Verified badge on listings
+- Advanced analytics dashboard
+
+## Break-Even Analysis
+
+### PRO Plan Break-Even
+At 7% commission instead of 10%, you save 3% per booking.
+Break-even monthly booking volume: $9.99 / 0.03 = **$333/month in bookings**
+
+### BUSINESS Plan Break-Even
+At 5% commission instead of 10%, you save 5% per booking.
+Break-even monthly booking volume: $29.99 / 0.05 = **$600/month in bookings**
+
+## Subscription Management
+- Plans can be changed at any time
+- Downgrades take effect immediately
+- Upgrades take effect immediately with a new 30-day billing period
+- Cancellation reverts to BASIC tier
--- a/docs/unit-economics.md
+++ b/docs/unit-economics.md
@@ -0,0 +1,59 @@
+# Unit Economics
+
+## Per-Booking P&L by Tier
+
+### Scenario: $500 Daily Rental (10 days × $50/day)
+
+| Line Item | BASIC | PRO | BUSINESS |
+|-----------|-------|-----|----------|
+| Booking Subtotal | $500.00 | $500.00 | $500.00 |
+| Commission Rate | 10% | 7% | 5% |
+| Commission Amount | $50.00 | $35.00 | $25.00 |
+| **Landlord Payout** | **$450.00** | **$465.00** | **$475.00** |
+| **Platform Revenue** | **$50.00** | **$35.00** | **$25.00** |
+
+### Scenario: $1,200 Monthly Rental (2 months × $600/month)
+
+| Line Item | BASIC | PRO | BUSINESS |
+|-----------|-------|-----|----------|
+| Booking Subtotal | $1,200.00 | $1,200.00 | $1,200.00 |
+| Commission Rate | 10% | 7% | 5% |
+| Commission Amount | $120.00 | $84.00 | $60.00 |
+| **Landlord Payout** | **$1,080.00** | **$1,116.00** | **$1,140.00** |
+| **Platform Revenue** | **$120.00** | **$84.00** | **$60.00** |
+
+## Monthly Landlord P&L (Example: 5 bookings/month, avg $400)
+
+| Line Item | BASIC | PRO | BUSINESS |
+|-----------|-------|-----|----------|
+| Gross Booking Revenue | $2,000 | $2,000 | $2,000 |
+| Subscription Cost | $0 | -$9.99 | -$29.99 |
+| Commission Paid | -$200 | -$140 | -$100 |
+| **Net Revenue** | **$1,800** | **$1,850.01** | **$1,870.01** |
+| **Savings vs BASIC** | - | **+$50.01** | **+$70.01** |
+
+## Platform Revenue per Landlord (Monthly)
+
+| Revenue Source | BASIC | PRO | BUSINESS |
+|----------------|-------|-----|----------|
+| Subscription Fee | $0 | $9.99 | $29.99 |
+| Commission (5 × $400) | $200 | $140 | $100 |
+| **Total Platform Revenue** | **$200** | **$149.99** | **$129.99** |
+
+> Note: While BASIC generates more per-landlord revenue, PRO/BUSINESS tiers drive retention and higher booking volumes, resulting in higher lifetime value.
+
+## Key Metrics
+
+```
+Average Revenue Per Landlord (ARPL) = Subscription + Commission
+Gross Margin = (Revenue - Payment Processing) / Revenue
+Payment Processing ≈ 2.9% + $0.30 per transaction (Stripe)
+```
+
+### Net Revenue per $1,000 Booking After Stripe Fees
+
+| Tier | Commission | Stripe Fee | Net Platform Revenue |
+|------|-----------|------------|---------------------|
+| BASIC | $100 | ~$3.20 | $96.80 |
+| PRO | $70 | ~$2.33 | $67.67 |
+| BUSINESS | $50 | ~$1.75 | $48.25 |