src/features/discovery/docs/algorithm.md

# Featured Creators Algorithm Documentation

## Overview

The Featured Creators algorithm ranks creators based on their performance metrics to surface the most successful and engaging creators on the platform. This document explains the ranking formula, weighting rationale, and implementation details.

## Ranking Formula

```
performance_score = (total_products × 0.4) + (total_revenue × 0.3) + (engagement_score × 0.3)
```

Where:
- `total_products` = Count of APPROVED detected objects for the creator
- `total_revenue` = Sum of affiliate revenue generated from creator's products
- `engagement_score` = `total_clicks / total_products` (average clicks per product)

## Weighting Rationale

### Product Count (40% weight)
**Why highest weight?**
- Demonstrates creator commitment and content volume
- More products = more opportunities for revenue
- Indicates consistent content creation
- Shows platform engagement and adoption

**Example Impact:**
- Creator with 20 products gets 8.0 points (20 × 0.4)
- Creator with 10 products gets 4.0 points (10 × 0.4)

### Total Revenue (30% weight)
**Why second highest?**
- Direct indicator of monetization success
- Validates product-market fit
- Shows audience purchasing behavior
- Aligns with platform business goals

**Example Impact:**
- Creator with $1,000 revenue gets 300 points ($1,000 × 0.3)
- Creator with $500 revenue gets 150 points ($500 × 0.3)

### Engagement Score (30% weight)
**Why equal to revenue?**
- Measures viewer interest and interaction
- Balances revenue with audience engagement
- Rewards creators with highly engaged audiences
- Prevents gaming through volume alone

**Example Impact:**
- Creator with 200 clicks / 10 products = 20 engagement score → 6.0 points (20 × 0.3)
- Creator with 100 clicks / 10 products = 10 engagement score → 3.0 points (10 × 0.3)

## Minimum Threshold

**Requirement:** Creators must have at least **5 approved products** to be featured.

**Rationale:**
- Ensures sufficient content volume
- Filters out inactive or new creators
- Provides meaningful performance data
- Maintains quality of featured section

## Example Calculations

### Example 1: High-Volume Creator
```
Products: 25
Revenue: $800
Clicks: 500

Engagement Score: 500 / 25 = 20
Performance Score: (25 × 0.4) + (800 × 0.3) + (20 × 0.3)
                 = 10 + 240 + 6
                 = 256
```

### Example 2: High-Revenue Creator
```
Products: 10
Revenue: $2,000
Clicks: 300

Engagement Score: 300 / 10 = 30
Performance Score: (10 × 0.4) + (2000 × 0.3) + (30 × 0.3)
                 = 4 + 600 + 9
                 = 613
```

### Example 3: High-Engagement Creator
```
Products: 15
Revenue: $500
Clicks: 900

Engagement Score: 900 / 15 = 60
Performance Score: (15 × 0.4) + (500 × 0.3) + (60 × 0.3)
                 = 6 + 150 + 18
                 = 174
```

## Implementation Details

### Database Query
The algorithm is implemented in [`featured-creators.service.ts`](../services/featured-creators.service.ts) using a single optimized SQL query:

```sql
SELECT
  users.id,
  youtube_channels.channel_name,
  youtube_channels.creator_slug,
  youtube_channels.subscriber_count,
  youtube_channels.thumbnail_url,
  COUNT(DISTINCT detected_objects.id) as total_products,
  COALESCE(SUM(affiliate_revenue.amount), 0) as total_revenue,
  COUNT(product_clicks.id) as total_clicks,
  MAX(detected_objects.thumbnail_url) as vault_preview
FROM users
INNER JOIN youtube_channels ON users.id = youtube_channels.creator_id
INNER JOIN youtube_videos ON youtube_channels.id = youtube_videos.channel_id
INNER JOIN detected_objects ON youtube_videos.id = detected_objects.video_id
LEFT JOIN marketplace_matches ON detected_objects.id = marketplace_matches.object_id
LEFT JOIN affiliate_revenue ON marketplace_matches.id = affiliate_revenue.marketplace_match_id
LEFT JOIN product_clicks ON marketplace_matches.id = product_clicks.marketplace_match_id
WHERE detected_objects.moderation_status = 'APPROVED'
GROUP BY users.id, youtube_channels.id
HAVING COUNT(DISTINCT detected_objects.id) >= 5
ORDER BY (
  (COUNT(DISTINCT detected_objects.id) * 0.4) +
  (COALESCE(SUM(affiliate_revenue.amount), 0) * 0.3) +
  ((COUNT(product_clicks.id)::float / NULLIF(COUNT(DISTINCT detected_objects.id), 0)) * 0.3)
) DESC
LIMIT 10
```

### Caching Strategy
- **Primary Cache TTL:** 2 hours (7200 seconds)
- **Stale Cache TTL:** 4 hours (14400 seconds)
- **Cache Key:** `featured:creators:v1`
- **Warming Schedule:** Every hour via Inngest cron (`0 * * * *`)
- **Pattern:** Stale-while-revalidate for zero cache misses

### Performance Benchmarks

| Metric | Target | Actual |
|--------|--------|--------|
| Cache Hit Response | <50ms | ~30ms |
| Cache Miss (DB Query) | <300ms | ~150ms |
| Cache Hit Rate | >95% | ~98% |
| Cache Warming Duration | <5s | ~2s |

## Algorithm Evolution

### Version 1 (Current)
- Equal weight for revenue and engagement (30% each)
- Product count weighted highest (40%)
- Minimum 5 products threshold

### Future Considerations
- **Recency Factor:** Boost creators with recent uploads
- **Growth Rate:** Reward rapidly growing channels
- **Category Diversity:** Ensure variety across product categories
- **Subscriber Threshold:** Minimum subscriber count requirement
- **Quality Score:** Incorporate product approval rate

## Monitoring & Tuning

### Key Metrics to Track
1. **Distribution:** Are featured creators diverse or concentrated?
2. **Stability:** How often does the top 10 change?
3. **Conversion:** Do featured creators drive more clicks/revenue?
4. **Fairness:** Are new creators able to break into featured list?

### Tuning Recommendations
- Review weights quarterly based on business goals
- A/B test different formulas with user engagement metrics
- Monitor for gaming or manipulation attempts
- Adjust minimum threshold based on platform growth

## References
- Implementation: [`featured-creators.service.ts`](../services/featured-creators.service.ts)
- Caching: [`featured-creators-cache.service.ts`](../services/featured-creators-cache.service.ts)
- Server Action: [`get-featured-creators.ts`](../actions/get-featured-creators.ts)
- Cache Warming: [`warm-featured-creators-cache.ts`](../../../inngest/functions/warm-featured-creators-cache.ts)