← back to Watches

tasks/prd-omega-platform-v2.md

765 lines

# PRD: Omega Watch Platform V2 - Complete Enhancement Suite

## Introduction

Transform the Omega Watch Price History System from a static viewing tool into a comprehensive affiliate monetization platform for watch collectors. This PRD covers 7 major features that together create a full-stack production platform with user accounts, real-time data, intelligent alerts, and revenue-generating affiliate integrations.

**Target User:** Watch collectors tracking their collection value
**Business Model:** Affiliate monetization through dealer links, comparison tools, and marketplace integrations
**Data Sources:** Free APIs only (Wayback Machine, public feeds, GitHub-hosted datasets)

---

## Goals

- Enable user accounts with social login (Google, Apple, GitHub) and email authentication
- Migrate from JSON files to PostgreSQL for scalability and advanced querying
- Integrate real-time pricing from free public sources
- Implement price alerts via email and push notifications
- Complete affiliate integration for revenue generation
- Add ML-powered price predictions beyond simple linear regression
- Support multi-currency display with live exchange rates

---

## Feature 1: User Authentication

### US-101: Database schema for users
**Description:** As a developer, I need user tables to store account information and preferences.

**Acceptance Criteria:**
- [ ] Create `users` table with: id (UUID), email, name, avatar_url, provider, provider_id, created_at, updated_at
- [ ] Create `user_sessions` table for session management
- [ ] Create `user_preferences` table for settings (currency, notifications, theme)
- [ ] PostgreSQL migration script runs successfully
- [ ] Typecheck passes

### US-102: Google OAuth integration
**Description:** As a user, I want to sign in with my Google account so I don't need another password.

**Acceptance Criteria:**
- [ ] "Sign in with Google" button on login page
- [ ] OAuth 2.0 flow redirects to Google and back
- [ ] Creates user record on first login
- [ ] Stores Google avatar and name
- [ ] Sets session cookie (httpOnly, secure)
- [ ] Typecheck passes
- [ ] Verify in browser: complete OAuth flow end-to-end

### US-103: Apple OAuth integration
**Description:** As an iOS user, I want to sign in with Apple for privacy and convenience.

**Acceptance Criteria:**
- [ ] "Sign in with Apple" button on login page
- [ ] Apple OAuth flow with email relay support
- [ ] Handles Apple's "hide my email" feature
- [ ] Creates user record on first login
- [ ] Typecheck passes
- [ ] Verify in browser: complete OAuth flow end-to-end

### US-104: GitHub OAuth integration
**Description:** As a developer/tech-savvy user, I want to sign in with GitHub.

**Acceptance Criteria:**
- [ ] "Sign in with GitHub" button on login page
- [ ] GitHub OAuth flow with appropriate scopes (read:user, user:email)
- [ ] Creates user record on first login
- [ ] Stores GitHub avatar and username
- [ ] Typecheck passes
- [ ] Verify in browser: complete OAuth flow end-to-end

### US-105: Email/password authentication
**Description:** As a user without social accounts, I want to sign up with email and password.

**Acceptance Criteria:**
- [ ] Email/password registration form with validation
- [ ] Password requirements: min 8 chars, 1 uppercase, 1 number
- [ ] Email verification flow (send link, verify token)
- [ ] Password hashing with bcrypt (cost factor 12)
- [ ] Login form with "forgot password" link
- [ ] Password reset flow via email
- [ ] Typecheck passes
- [ ] Verify in browser: complete registration and login flows

### US-106: Session management and logout
**Description:** As a user, I want my session to persist and be able to log out securely.

**Acceptance Criteria:**
- [ ] Session persists across browser restarts (7-day expiry)
- [ ] Logout button in header when authenticated
- [ ] Logout clears session cookie and server-side session
- [ ] Protected routes redirect to login when unauthenticated
- [ ] API endpoints return 401 for unauthenticated requests to protected resources
- [ ] Typecheck passes
- [ ] Verify in browser: session persistence and logout

### US-107: User profile page
**Description:** As a user, I want to view and edit my profile information.

**Acceptance Criteria:**
- [ ] Profile page at `/profile`
- [ ] Shows avatar, name, email, join date
- [ ] Edit name functionality
- [ ] Change password (for email auth users)
- [ ] Delete account option with confirmation
- [ ] Typecheck passes
- [ ] Verify in browser: profile viewing and editing

---

## Feature 2: PostgreSQL Database Migration

### US-201: Set up PostgreSQL connection
**Description:** As a developer, I need the app to connect to PostgreSQL instead of JSON files.

**Acceptance Criteria:**
- [ ] PostgreSQL connection pool configured (pg library)
- [ ] Environment variables for DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
- [ ] Connection health check on startup
- [ ] Graceful connection pool shutdown
- [ ] Typecheck passes

### US-202: Run existing schema migration
**Description:** As a developer, I need to apply the existing PostgreSQL schema.

**Acceptance Criteria:**
- [ ] Execute `database/schema.sql` on PostgreSQL instance
- [ ] All tables created: watches, specifications, features, price_history, etc.
- [ ] Indexes and constraints applied
- [ ] Partitioned tables set up correctly
- [ ] Verify with `\dt` command shows all tables

### US-203: Migrate JSON data to PostgreSQL
**Description:** As a developer, I need to import existing watch data from JSON to PostgreSQL.

**Acceptance Criteria:**
- [ ] Migration script reads `data/watches.json`
- [ ] Inserts all 32 watches with specifications
- [ ] Imports all price history records
- [ ] Handles data validation and errors gracefully
- [ ] Logs progress and any skipped records
- [ ] Verify data count matches JSON source
- [ ] Typecheck passes

### US-204: Update API endpoints to use PostgreSQL
**Description:** As a developer, I need all API endpoints to query PostgreSQL instead of JSON.

**Acceptance Criteria:**
- [ ] `/api/watches` queries PostgreSQL
- [ ] `/api/watches/:id` queries PostgreSQL with joins
- [ ] `/api/statistics` uses materialized view
- [ ] `/api/search` uses full-text search vectors
- [ ] All existing tests pass
- [ ] Response format unchanged (backward compatible)
- [ ] Typecheck passes

### US-205: Implement database repository pattern
**Description:** As a developer, I need a clean data access layer for maintainability.

**Acceptance Criteria:**
- [ ] Create `database/repositories/watches.js`
- [ ] Create `database/repositories/priceHistory.js`
- [ ] Create `database/repositories/users.js`
- [ ] Repository methods: findAll, findById, create, update, delete
- [ ] Parameterized queries to prevent SQL injection
- [ ] Typecheck passes

### US-206: Add database backup automation
**Description:** As an operator, I need automated PostgreSQL backups.

**Acceptance Criteria:**
- [ ] pg_dump script for daily backups
- [ ] Backup files stored in `/backups/postgres/`
- [ ] Retention: 7 daily, 4 weekly, 12 monthly
- [ ] Cron job configured
- [ ] Restore script tested
- [ ] Verify backup file is valid with pg_restore dry-run

---

## Feature 3: Real-time Pricing (Free APIs)

### US-301: Wayback Machine price scraper service
**Description:** As a developer, I need a service to fetch historical prices from Wayback Machine.

**Acceptance Criteria:**
- [ ] Service queries Wayback Machine CDX API
- [ ] Parses archived dealer pages for price data
- [ ] Rate limiting: max 1 request per second
- [ ] Caches results to avoid repeated scraping
- [ ] Error handling for unavailable snapshots
- [ ] Typecheck passes

### US-302: GitHub-hosted price dataset integration
**Description:** As a developer, I want to fetch price data from public GitHub repositories.

**Acceptance Criteria:**
- [ ] Identify/create GitHub repo for community price data
- [ ] Fetch raw JSON files via GitHub API
- [ ] Parse and validate price data format
- [ ] Update local cache on schedule (every 6 hours)
- [ ] Handle rate limiting (60 requests/hour unauthenticated)
- [ ] Typecheck passes

### US-303: Chrono24 public listing scraper
**Description:** As a developer, I need to scrape publicly visible Chrono24 listings.

**Acceptance Criteria:**
- [ ] Scrape public search results pages (no auth required)
- [ ] Extract: price, condition, seller location, listing date
- [ ] Respect robots.txt and rate limits
- [ ] Store raw data with source attribution
- [ ] Run as background job, not blocking API
- [ ] Typecheck passes

### US-304: Price aggregation service
**Description:** As a developer, I need to combine prices from multiple sources into unified data.

**Acceptance Criteria:**
- [ ] Aggregates prices from: Wayback, GitHub dataset, Chrono24 scraper
- [ ] Calculates: average, median, min, max, standard deviation
- [ ] Weights by recency (newer data weighted higher)
- [ ] Confidence score based on data points count
- [ ] Stores aggregated results in PostgreSQL
- [ ] Typecheck passes

### US-305: Real-time price display on watch cards
**Description:** As a user, I want to see current market prices on each watch card.

**Acceptance Criteria:**
- [ ] Watch cards show "Market Price" with range (min-max)
- [ ] Shows data freshness ("Updated 2 hours ago")
- [ ] Confidence indicator (high/medium/low based on data points)
- [ ] Click to see price breakdown by source
- [ ] Typecheck passes
- [ ] Verify in browser: prices display correctly with freshness

### US-306: Price update scheduler
**Description:** As an operator, I need automated price updates on a schedule.

**Acceptance Criteria:**
- [ ] Cron job runs price scrapers every 6 hours
- [ ] Staggered execution to avoid rate limits
- [ ] Logs success/failure for each source
- [ ] Alerts on consecutive failures (3+ in a row)
- [ ] PM2 configuration for scheduler process
- [ ] Typecheck passes

---

## Feature 4: Price Alerts

### US-401: Price alert database schema
**Description:** As a developer, I need to store user price alerts.

**Acceptance Criteria:**
- [ ] Create `price_alerts` table: id, user_id, watch_id, target_price, direction (above/below), is_active, triggered_at, created_at
- [ ] Foreign keys to users and watches tables
- [ ] Index on (user_id, is_active) for efficient queries
- [ ] Migration runs successfully
- [ ] Typecheck passes

### US-402: Create price alert UI
**Description:** As a user, I want to set a price alert for a watch I'm interested in.

**Acceptance Criteria:**
- [ ] "Set Alert" button on watch detail page
- [ ] Modal with: target price input, direction dropdown (above/below)
- [ ] Validates price is positive number
- [ ] Shows current market price for reference
- [ ] Saves alert to database
- [ ] Success toast notification
- [ ] Typecheck passes
- [ ] Verify in browser: create alert flow

### US-403: Manage alerts page
**Description:** As a user, I want to view and manage all my price alerts.

**Acceptance Criteria:**
- [ ] Alerts page at `/alerts` (authenticated only)
- [ ] Lists all alerts: watch name, target price, direction, status
- [ ] Toggle alert active/inactive
- [ ] Delete alert with confirmation
- [ ] Shows triggered alerts with trigger date
- [ ] Empty state when no alerts
- [ ] Typecheck passes
- [ ] Verify in browser: alert management

### US-404: Alert evaluation service
**Description:** As a developer, I need a service that checks if alerts should trigger.

**Acceptance Criteria:**
- [ ] Service runs after each price update
- [ ] Queries active alerts and current prices
- [ ] Triggers alert when: (direction=below AND price <= target) OR (direction=above AND price >= target)
- [ ] Marks alert as triggered with timestamp
- [ ] Queues notifications for triggered alerts
- [ ] Typecheck passes

### US-405: Email notifications for alerts
**Description:** As a user, I want to receive email when my price alert triggers.

**Acceptance Criteria:**
- [ ] Email template with: watch name, target price, current price, link to watch
- [ ] Uses SendGrid or similar free tier (100 emails/day)
- [ ] Unsubscribe link in email
- [ ] Tracks email delivery status
- [ ] Typecheck passes

### US-406: Push notifications for alerts
**Description:** As a user, I want browser push notifications for price alerts.

**Acceptance Criteria:**
- [ ] Permission request for notifications (on alerts page)
- [ ] Store push subscription in database
- [ ] Send push notification when alert triggers
- [ ] Notification shows watch name and price
- [ ] Click notification opens watch detail page
- [ ] Typecheck passes
- [ ] Verify in browser: push notification flow

### US-407: Alert preferences
**Description:** As a user, I want to control how I receive alert notifications.

**Acceptance Criteria:**
- [ ] Preferences in user profile: email on/off, push on/off
- [ ] Quiet hours setting (don't send between X and Y time)
- [ ] Frequency limit (max N alerts per day)
- [ ] Saves to user_preferences table
- [ ] Typecheck passes
- [ ] Verify in browser: preferences UI

---

## Feature 5: Affiliate Integration

### US-501: Affiliate links database schema
**Description:** As a developer, I need to store affiliate program configurations.

**Acceptance Criteria:**
- [ ] Create `affiliate_programs` table: id, name, base_url, tracking_param, commission_rate, is_active
- [ ] Create `affiliate_clicks` table: id, user_id, watch_id, program_id, clicked_at, converted, commission
- [ ] Seed data for: Chrono24, eBay, Jomashop, Bob's Watches
- [ ] Typecheck passes

### US-502: Affiliate link generator
**Description:** As a developer, I need a service to generate tracked affiliate links.

**Acceptance Criteria:**
- [ ] Function: generateAffiliateLink(watchRef, programId, userId)
- [ ] Appends tracking parameters to base URL
- [ ] Includes user ID for commission tracking (hashed)
- [ ] Returns null for inactive programs
- [ ] Typecheck passes

### US-503: "Buy Now" buttons on watch cards
**Description:** As a user, I want to see where I can buy a watch with direct links.

**Acceptance Criteria:**
- [ ] "Buy Now" dropdown on watch detail page
- [ ] Lists active affiliate partners with logos
- [ ] Each option opens affiliate link in new tab
- [ ] Tracks click in affiliate_clicks table
- [ ] Shows estimated prices per dealer if available
- [ ] Typecheck passes
- [ ] Verify in browser: affiliate links work correctly

### US-504: Price comparison widget
**Description:** As a user, I want to compare prices across dealers.

**Acceptance Criteria:**
- [ ] Comparison table showing: dealer, price, condition, shipping
- [ ] Sorted by price (lowest first)
- [ ] "Best Deal" badge on cheapest option
- [ ] Each row has affiliate link
- [ ] Last updated timestamp
- [ ] Typecheck passes
- [ ] Verify in browser: comparison widget displays

### US-505: Affiliate dashboard (admin)
**Description:** As an admin, I want to see affiliate performance metrics.

**Acceptance Criteria:**
- [ ] Dashboard at `/admin/affiliates` (admin auth required)
- [ ] Metrics: total clicks, clicks by program, conversion rate, estimated revenue
- [ ] Date range filter (7d, 30d, 90d, custom)
- [ ] Chart showing clicks over time
- [ ] Export to CSV
- [ ] Typecheck passes
- [ ] Verify in browser: dashboard displays metrics

### US-506: Japan arbitrage calculator
**Description:** As a collector, I want to calculate potential savings buying from Japan.

**Acceptance Criteria:**
- [ ] Calculator widget on watch detail page
- [ ] Inputs: Japan price (JPY), current exchange rate
- [ ] Calculates: USD equivalent, import duty estimate, total cost
- [ ] Compares to US market price
- [ ] Shows potential savings/loss
- [ ] Affiliate links to Japan dealers
- [ ] Typecheck passes
- [ ] Verify in browser: calculator works correctly

### US-507: Affiliate disclosure compliance
**Description:** As a platform, I need proper affiliate disclosure for legal compliance.

**Acceptance Criteria:**
- [ ] Footer disclosure: "We may earn commission from purchases"
- [ ] Individual link disclosure icon/tooltip
- [ ] Full disclosure page at `/affiliate-disclosure`
- [ ] Disclosure visible before any affiliate click
- [ ] Typecheck passes
- [ ] Verify in browser: disclosures visible

---

## Feature 6: ML Price Predictions

### US-601: Historical data preparation
**Description:** As a developer, I need to prepare training data for ML models.

**Acceptance Criteria:**
- [ ] Export price history to CSV format
- [ ] Features: year, month, model, reference, condition, source_type
- [ ] Target: price
- [ ] Handle missing values (interpolation or removal)
- [ ] Split into train/test sets (80/20)
- [ ] Typecheck passes

### US-602: Linear regression baseline
**Description:** As a developer, I need a baseline model to compare against.

**Acceptance Criteria:**
- [ ] Implement simple linear regression (year vs price)
- [ ] Calculate R-squared and RMSE metrics
- [ ] Store model coefficients in database
- [ ] Predict function: predictPrice(watchId, year)
- [ ] Typecheck passes

### US-603: Polynomial regression model
**Description:** As a developer, I want a more sophisticated model for non-linear trends.

**Acceptance Criteria:**
- [ ] Implement polynomial regression (degree 2-3)
- [ ] Cross-validation to select optimal degree
- [ ] Compare metrics to linear baseline
- [ ] Store model coefficients
- [ ] Typecheck passes

### US-604: Random forest model
**Description:** As a developer, I want an ensemble model for better predictions.

**Acceptance Criteria:**
- [ ] Implement Random Forest regression (TensorFlow.js or ml.js)
- [ ] Features: year, model_age, collection, material, movement_type
- [ ] Hyperparameter tuning (trees, depth, min samples)
- [ ] Model serialization for production use
- [ ] Typecheck passes

### US-605: Model evaluation and selection
**Description:** As a developer, I need to compare models and select the best one.

**Acceptance Criteria:**
- [ ] Evaluation script comparing all models
- [ ] Metrics: RMSE, MAE, R-squared on test set
- [ ] Stores evaluation results in database
- [ ] Selects best model per watch collection
- [ ] Documents model selection rationale
- [ ] Typecheck passes

### US-606: Price prediction API endpoint
**Description:** As a developer, I need an API to serve predictions.

**Acceptance Criteria:**
- [ ] Endpoint: GET `/api/predictions/:watchId`
- [ ] Returns: predicted prices for next 1, 3, 5 years
- [ ] Includes confidence intervals (if supported by model)
- [ ] Includes model metadata (type, last trained, accuracy)
- [ ] Caches predictions (refresh on new data)
- [ ] Typecheck passes

### US-607: Prediction display on watch detail
**Description:** As a user, I want to see predicted future prices for a watch.

**Acceptance Criteria:**
- [ ] "Price Prediction" section on watch detail page
- [ ] Shows predicted price for 2025, 2027, 2030
- [ ] Visual confidence indicator (high/medium/low)
- [ ] Disclaimer: "Predictions are estimates, not financial advice"
- [ ] Toggle to show/hide prediction overlay on price chart
- [ ] Typecheck passes
- [ ] Verify in browser: predictions display correctly

### US-608: Model retraining scheduler
**Description:** As an operator, I need models to retrain periodically.

**Acceptance Criteria:**
- [ ] Cron job to retrain models monthly
- [ ] Retrains only when new data available
- [ ] Compares new model to current, only deploys if better
- [ ] Logs training metrics and duration
- [ ] Alerts on training failures
- [ ] Typecheck passes

---

## Feature 7: Multi-Currency Support

### US-701: Currency configuration
**Description:** As a developer, I need to define supported currencies.

**Acceptance Criteria:**
- [ ] Config file with currencies: USD, EUR, GBP, JPY, CHF, AUD, CAD
- [ ] Each currency has: code, symbol, decimal places, name
- [ ] Default currency: USD
- [ ] Typecheck passes

### US-702: Exchange rate service
**Description:** As a developer, I need live exchange rates.

**Acceptance Criteria:**
- [ ] Integrate free exchange rate API (exchangerate-api.com or similar)
- [ ] Fetch rates on startup and cache for 1 hour
- [ ] Fallback to last known rates on API failure
- [ ] Store historical rates for reference
- [ ] Function: convertCurrency(amount, from, to)
- [ ] Typecheck passes

### US-703: Currency selector UI
**Description:** As a user, I want to choose my preferred currency.

**Acceptance Criteria:**
- [ ] Currency dropdown in header
- [ ] Shows flag icon + currency code
- [ ] Selection persists in localStorage (anonymous) or user_preferences (authenticated)
- [ ] Updates all prices on page without reload
- [ ] Typecheck passes
- [ ] Verify in browser: currency switching works

### US-704: Price display formatting
**Description:** As a user, I want prices formatted correctly for my currency.

**Acceptance Criteria:**
- [ ] Prices show correct currency symbol
- [ ] Proper thousand separators (1,234.56 vs 1.234,56)
- [ ] Correct decimal places (JPY has 0, most have 2)
- [ ] Shows original currency in tooltip (e.g., "Originally $5,000 USD")
- [ ] Typecheck passes
- [ ] Verify in browser: formatting correct for all currencies

### US-705: Historical price conversion
**Description:** As a user, I want historical prices converted to my currency.

**Acceptance Criteria:**
- [ ] Option to show historical prices in: original currency OR current currency
- [ ] Uses historical exchange rates when available
- [ ] Falls back to current rate with disclaimer
- [ ] Chart updates to show converted values
- [ ] Typecheck passes
- [ ] Verify in browser: historical conversion works

### US-706: Currency in exports
**Description:** As a user, I want exported data in my selected currency.

**Acceptance Criteria:**
- [ ] CSV/JSON exports include currency column
- [ ] Prices converted to user's selected currency
- [ ] Exchange rate and date included in export metadata
- [ ] Option to export in original currencies
- [ ] Typecheck passes

---

## Functional Requirements Summary

### Authentication
- FR-1: Support OAuth login via Google, Apple, and GitHub
- FR-2: Support email/password registration with verification
- FR-3: Session management with 7-day persistence
- FR-4: Password reset via email
- FR-5: User profile management with delete account

### Database
- FR-6: PostgreSQL as primary data store
- FR-7: All existing API endpoints maintain backward compatibility
- FR-8: Repository pattern for data access
- FR-9: Automated daily backups with retention policy

### Real-time Pricing
- FR-10: Aggregate prices from multiple free sources
- FR-11: Update prices every 6 hours automatically
- FR-12: Display price freshness and confidence indicators
- FR-13: Rate limit all external API calls

### Price Alerts
- FR-14: Users can create price alerts (above/below threshold)
- FR-15: Alerts trigger via email and/or push notification
- FR-16: Users can manage alerts (view, toggle, delete)
- FR-17: Alert preferences for notification control

### Affiliate
- FR-18: Generate tracked affiliate links for all partners
- FR-19: Track clicks and estimated conversions
- FR-20: Display price comparisons across dealers
- FR-21: Japan arbitrage calculator
- FR-22: Legal affiliate disclosure throughout site

### ML Predictions
- FR-23: Multiple model types (linear, polynomial, random forest)
- FR-24: Predictions for 1, 3, 5 year horizons
- FR-25: Confidence intervals where available
- FR-26: Monthly model retraining

### Multi-Currency
- FR-27: Support 7+ major currencies
- FR-28: Live exchange rate updates
- FR-29: User preference persistence
- FR-30: Proper locale-based formatting

---

## Non-Goals (Out of Scope)

- Native mobile apps (iOS/Android) - PWA is sufficient
- Real-time WebSocket price streaming - 6-hour updates sufficient
- User-to-user marketplace/selling - affiliate model only
- Watch authentication/verification services
- Physical watch inspection or appraisal
- Paid API integrations (Chrono24 official API, etc.)
- Multi-language/internationalization (English only)
- Admin CMS for content management
- Social features (comments, reviews, following users)
- Watch news/blog content system
- Integration with watch insurance providers

---

## Technical Considerations

### Authentication
- Use Passport.js for OAuth strategies
- JWT tokens for API authentication
- Session storage in PostgreSQL (connect-pg-simple)
- CSRF protection for form submissions

### Database
- PostgreSQL 14+ for JSON support and partitioning
- Connection pooling with pg-pool (max 20 connections)
- Read replicas for scaling (future)
- Schema migrations with node-pg-migrate

### Real-time Pricing
- Puppeteer for JavaScript-rendered pages
- Cheerio for static HTML parsing
- Rate limiting with bottleneck library
- Redis for scrape result caching (optional)

### ML Models
- TensorFlow.js for browser-compatible models
- ml.js as lightweight alternative
- Model artifacts stored in PostgreSQL as JSONB
- Python scripts for training (optional, for complex models)

### Performance
- Target: <200ms API response times
- CDN for static assets (Cloudflare)
- Database query optimization with EXPLAIN ANALYZE
- Lazy loading for charts and heavy components

---

## Success Metrics

### Authentication
- 50% of returning users create accounts
- <5 second OAuth flow completion
- <1% password reset requests per month

### Database
- Zero data loss during migration
- API response times unchanged or improved
- Successful automated backups 100% of time

### Real-time Pricing
- 90%+ of watches have fresh prices (<24 hours)
- Price confidence "high" for 70%+ of listings
- Zero rate limit violations from external APIs

### Price Alerts
- 10% of registered users create at least one alert
- 95% alert notification delivery rate
- <5 minute delay from price change to notification

### Affiliate
- 5% click-through rate on affiliate links
- Track 100% of outbound affiliate clicks
- 2%+ estimated conversion rate

### ML Predictions
- R-squared >0.85 for best model
- 80%+ of predictions within 20% of actual
- All models retrain successfully monthly

### Multi-Currency
- <100ms currency conversion time
- Exchange rates updated within 2 hours of market
- Zero formatting errors across locales

---

## Open Questions

1. **OAuth credentials:** Do we have Google Cloud, Apple Developer, and GitHub OAuth apps set up?
2. **PostgreSQL hosting:** Self-hosted on VPS or managed service (Supabase, Neon)?
3. **Email provider:** SendGrid free tier, or alternative?
4. **Affiliate programs:** Are partnerships with Chrono24, eBay, Jomashop confirmed?
5. **ML complexity:** Should we pursue TensorFlow.js in-browser or Python backend training?
6. **Exchange rate API:** Which free tier service? (exchangerate-api.com, frankfurter.app?)
7. **Push notification service:** Web Push via service worker only, or Firebase Cloud Messaging?

---

## Implementation Priority

### Phase 1: Foundation (Features 1 & 2)
User Authentication + Database Migration
*Required for all other features*

### Phase 2: Value (Features 3 & 4)
Real-time Pricing + Price Alerts
*Core user value proposition*

### Phase 3: Revenue (Feature 5)
Affiliate Integration
*Monetization layer*

### Phase 4: Intelligence (Feature 6)
ML Price Predictions
*Differentiation and engagement*

### Phase 5: Polish (Feature 7)
Multi-Currency Support
*International accessibility*

---

## Appendix: User Stories Count

| Feature | Stories | Complexity |
|---------|---------|------------|
| Authentication | 7 | High |
| Database Migration | 6 | Medium |
| Real-time Pricing | 6 | High |
| Price Alerts | 7 | Medium |
| Affiliate Integration | 7 | Medium |
| ML Predictions | 8 | High |
| Multi-Currency | 6 | Low |
| **Total** | **47** | - |

---

*PRD Generated: January 2026*
*Version: 1.0*
*Author: Claude Code / Ralph PRD Generator*