`DATA_SOURCES.md`

416 lines
# LUXVAULT Data Sources & Premium Features

## Current Data Sources (All Mock/Hardcoded)

### 1. **Homepage** (`src/app/page.tsx`)
**Featured Bags:**
```typescript
// Lines 151-245: Hardcoded featured bags
{
  brand: 'Hermès',
  model: 'Birkin 25',
  pricePerShare: 25,
  totalValue: 42000,
  appreciation: 12.4,
  image: 'https://images.unsplash.com/...' // Unsplash placeholder
}
```
**Source:** Hardcoded static data
**Updates:** Manual code changes required

**Stats Bar:**
```typescript
// Lines 121-136: Hardcoded statistics
total_listings: '27,000+' (static text)
avgReturn: '14.2%' (static)
minInvestment: '$10' (static)
```
**Source:** Hardcoded values
**API Endpoint:** `/api/stats` (currently returns mock data)

---

### 2. **Marketplace** (`src/app/marketplace/page.tsx`)
**6 Investment Bags:**
```typescript
// Lines 10-95: Complete hardcoded array
const bags = [
  {
    id: 1,
    brand: 'Hermès',
    model: 'Birkin 25',
    pricePerShare: 25,
    totalValue: 42000,
    sharesAvailable: 1680,
    appreciation: 12.4,
    image: 'https://images.unsplash.com/...'
  },
  // ... 5 more bags
]
```
**Source:** Hardcoded static data in component
**Updates:** Manual code changes required
**Images:** Unsplash placeholder images (not actual products)

---

### 3. **Museum** (`src/app/museum/page.tsx`)
**60 Bags Across 3 Brands:**

#### Hermès (20 bags)
```typescript
// Lines 32-433: Complete hardcoded brand data
{
  name: 'Hermès',
  bags: [
    {
      name: 'Birkin 25',
      model: 'Togo Leather',
      priceHistory: [
        { year: 2015, price: 8500 },
        { year: 2016, price: 9200 },
        // ... yearly prices through 2025
      ],
      currentPrice: 42000,
      appreciation: 394
    }
    // ... 19 more bags
  ]
}
```

#### Chanel (20 bags)
```typescript
// Lines 435-818: Hardcoded Chanel data
```

#### Louis Vuitton (20 bags)
```typescript
// Lines 820-1199: Hardcoded LV data
```

**Source:** Hardcoded static data
**Historical Prices:** Mock data (not real market prices)
**Appreciation %:** Calculated from mock price history
**Images:** Unsplash placeholder images

---

### 4. **Admin Dashboard** (`src/app/admin/page.tsx`)
**Currently Using Real Database:**
```typescript
// API: /api/admin/dashboard
// Queries Prisma database for:
- Total listings (real count from DB)
- Active deals (real count)
- Average deal percentage (calculated from DB)
- Top brands (real data from listings table)
```

**Database Schema:**
```prisma
model Listing {
  id          String
  brand       String?
  model       String?
  priceUsd    Float?
  productUrl  String?
  imageUrl    String?
  crawledAt   DateTime
  is_active   Boolean
}

model DealAnalysis {
  id               String
  deal_percentage  Float?
  is_deal          Boolean
}
```

**Source:** SQLite database at `prisma/handbags.db`
**Updates:** Real-time from crawlers (luxvault-ingestion, luxvault-deal-detector)

---

## Premium Feature Roadmap

### **Tier 1: Free** (Current State)
- ✅ Browse 6 marketplace bags (static data)
- ✅ View museum with 60 bags (static historical data)
- ✅ See mock appreciation charts
- ✅ Basic platform access
- ❌ No real-time data
- ❌ No actual investment capability

### **Tier 2: Basic - $9.99/month**
**Real-Time Data Integration:**
- 🔄 Live marketplace prices from database
- 🔄 Real appreciation tracking (updated daily)
- 🔄 Price alerts for favorite bags
- 🔄 Historical price charts (real data)
- 🔄 Browse 50+ actual investment opportunities

**Data Sources to Implement:**
```typescript
// API: /api/marketplace/live
{
  bags: [
    {
      id: "listing-123",
      brand: "Hermès",
      model: "Birkin 25",
      currentPrice: await getRealtimePrice(listingId),
      priceHistory: await getPriceHistory(listingId, '30d'),
      appreciation: calculateAppreciation(history),
      source: "1stDibs / Vestiaire Collective"
    }
  ]
}
```

### **Tier 3: Pro - $29.99/month**
**Advanced Analytics:**
- 📊 AI-powered deal detection (using Claude automation)
- 📊 Portfolio tracking & performance metrics
- 📊 Market trends & predictions
- 📊 Exclusive early access to new listings
- 📊 Museum with 500+ bags (all brands)
- 📊 Custom price alerts via email/SMS

**Data Sources:**
```typescript
// Real-time scraping from:
- 1stDibs API
- Vestiaire Collective
- The RealReal API
- Rebag API
- Fashionphile

// AI Analysis:
- Claude deal detection (already built: deal-detector.ts)
- Price prediction models
- Market sentiment analysis
```

### **Tier 4: Investor - $99.99/month**
**Full Investment Platform:**
- 💰 Actual fractional ownership (SEC-compliant)
- 💰 Blockchain-verified shares
- 💰 Physical custody & insurance
- 💰 Secondary market trading
- 💰 Quarterly dividend distributions
- 💰 White-glove concierge service
- 💰 Access to ultra-rare pieces (>$100k)

**Data Sources:**
```typescript
// Blockchain integration:
- Ethereum smart contracts
- NFT certificates of ownership
- On-chain transaction history

// Financial data:
- Real SEC filings
- Insurance valuations
- Custody receipts
- Auction house results (Christie's, Sotheby's)
```

---

## Implementation Plan

### Phase 1: Connect Database to Frontend (Week 1)
**Replace hardcoded data with real DB queries:**

```typescript
// src/app/marketplace/page.tsx - BEFORE
const bags = [
  { id: 1, brand: 'Hermès', ... } // hardcoded
]

// AFTER
const bags = await fetch('/api/marketplace/live')
  .then(res => res.json())
// Returns real listings from database
```

**Database Integration Points:**
1. `/api/marketplace/live` - Real bags from `listings` table
2. `/api/museum/brands` - Aggregated brand data
3. `/api/bags/[id]/history` - Price history per bag
4. `/api/stats` - Real platform statistics

### Phase 2: Real-Time Price Tracking (Week 2-3)
**Build price history table:**
```prisma
model PriceHistory {
  id          String   @id @default(cuid())
  listingId   String
  price       Float
  source      String
  recordedAt  DateTime @default(now())

  listing     Listing  @relation(fields: [listingId], references: [id])
}
```

**Automated tracking:**
- Crawlers run every 0.9 seconds (already built)
- Store price snapshots in `PriceHistory`
- Calculate appreciation in real-time

### Phase 3: Premium Paywall (Week 4)
**Implement subscription system:**
```typescript
// src/middleware.ts
export async function middleware(req: NextRequest) {
  const tier = await getUserSubscriptionTier(req)

  if (req.nextUrl.pathname.startsWith('/marketplace/premium')) {
    if (tier === 'free') {
      return NextResponse.redirect('/pricing')
    }
  }
}
```

**Show data source attribution:**
```typescript
// Display on each card:
<div className="text-xs text-gray-500">
  📊 Data from: 1stDibs • Updated: 2 min ago
</div>
```

### Phase 4: Blockchain Integration (Week 5-8)
**Smart contract for fractional ownership:**
```solidity
contract LuxVaultShares {
  mapping(uint => BagListing) public bags;
  mapping(address => mapping(uint => uint)) public shares;

  function buyShares(uint bagId, uint amount) public payable {
    // Transfer funds
    // Mint shares
    // Emit ownership event
  }
}
```

---

## Data Transparency Features

### Real-Time Data Attribution
**Show on every page:**
```typescript
<footer className="text-xs text-gray-500">
  📊 Market data provided by: 1stDibs, Vestiaire Collective, The RealReal
  🤖 AI analysis powered by Claude (Anthropic)
  ⏰ Last updated: {lastUpdate}
  📈 Data accuracy: {accuracyScore}%
</footer>
```

### Data Quality Indicators
```typescript
// Show confidence scores
<div className="flex items-center gap-2">
  <span>Price: $42,000</span>
  <Badge variant="green">98% confident</Badge>
  <Tooltip>Based on 15 data points from 3 sources</Tooltip>
</div>
```

### Historical Data Attribution
```typescript
// Museum page
<p className="text-xs text-gray-400">
  Historical prices: Aggregated from Christie's auction results,
  Sotheby's archive, and authorized dealer reports (2015-2025)
</p>
```

---

## Current State Summary

### What's REAL Now:
✅ Admin dashboard (connected to real database)
✅ Crawlers collecting actual listings (luxvault-ingestion)
✅ AI deal detection (deal-detector.ts with Claude)
✅ Database with real handbag listings

### What's MOCK Now:
❌ Marketplace bags (6 hardcoded items)
❌ Museum historical prices (fabricated)
❌ Homepage featured bags (static)
❌ All product images (Unsplash placeholders)
❌ Appreciation percentages (calculated from mock data)
❌ Share prices (hardcoded)

### Next Steps:
1. **Wire up database to frontend** (replace all hardcoded arrays)
2. **Build price history tracking** (store snapshots over time)
3. **Implement real image CDN** (replace Unsplash with actual product photos)
4. **Add data source badges** (show where each price comes from)
5. **Build premium tiers** (paywall for real-time data)
6. **Add blockchain integration** (actual fractional ownership)

---

## Revenue Model

### Subscription Revenue (Monthly)
- Free: $0 (10,000 users) = $0
- Basic: $9.99 (1,000 users) = $9,990
- Pro: $29.99 (500 users) = $14,995
- Investor: $99.99 (100 users) = $9,999
**Total MRR: $34,984 (~$420k ARR)**

### Transaction Revenue
- 2% platform fee on all fractional purchases
- $100 avg transaction × 1,000 monthly transactions = $100,000
- 2% fee = $2,000/month

### Data Licensing Revenue
- Sell aggregated market data to:
  - Luxury brands (market intelligence)
  - Investment firms (alternative assets data)
  - Insurance companies (valuation data)
- Estimated: $10,000-50,000/month

**Total Potential Revenue: $500k-550k ARR**

---

## Data Attribution Template

**Add to all pages:**
```typescript
// components/DataAttribution.tsx
export function DataAttribution({ source, updated, confidence }) {
  return (
    <div className="border-t border-white/10 pt-4 mt-8">
      <h4 className="text-sm font-semibold mb-2">Data Sources</h4>
      <div className="space-y-1 text-xs text-gray-400">
        <p>📊 Pricing: {source}</p>
        <p>⏰ Updated: {updated}</p>
        <p>✅ Confidence: {confidence}%</p>
        <p>🤖 AI Analysis: Claude (Anthropic)</p>
      </div>
    </div>
  )
}
```

**Usage:**
```tsx
<DataAttribution
  source="1stDibs, Vestiaire Collective"
  updated="2 minutes ago"
  confidence={98}
/>
```