aethex.live/docs/PHASE_2_SOCIAL_DISCOVERY.md

Phase 2: Social & Discovery - Complete Implementation Guide

Duration: Weeks 5-8 | Complexity: Medium-High | Team Size: 2-3 devs

Executive Summary

Phase 2 transforms AeThex from a simple streaming platform into a social discovery engine. Creators can now be discovered, followed, and recommended. Viewers can search for streams, browse categories, and receive personalized recommendations.

---

Phase 2 Goals

Primary Goals

1. Enable stream discovery and search
2. Build the social graph (follow system)
3. Implement recommendations algorithm
4. Create creator homepage/dashboard
5. Add notifications system

Success Criteria

• 📊 250+ creators onboarded
• 👥 2,000+ registered users
• 🔍 95% search response time <500ms
• ⭐ 20%+ streams discovered via recommendations
• 🔔 50%+ users enable notifications

---

Sprint Breakdown

Sprint 2.1: Social Graph Foundation

Duration: Days 1-5 | Team: 1-2 devs | Status: ⏳ NOT STARTED

User Story 2.1.1: Follow System

AS A viewer
I WANT to follow creators
SO THAT I get notified when they go live

Tasks:

• Build follow/unfollow button component
• Implement following/followers lists
• Add follower count to creator profile
• Reciprocal follow detection
• Follow analytics

Schema Updates:

// Already defined in Phase 1, but expand usage
model User {
  // ... existing fields
  followees         Follow[]  @relation("follower")
  followers         Follow[]  @relation("followee")
}

// Extend statistics
model ChannelStats {
  id                String    @id @default(cuid())
  channelId         String    @unique
  channel           Channel   @relation(fields: [channelId], references: [id])
  
  followerCount     Int       @default(0)
  viewCount         Int       @default(0)
  chatMessageCount  Int       @default(0)
  
  streamsCount      Int       @default(0)
  totalViewTime     Int       @default(0) // minutes
  
  updatedAt         DateTime  @updatedAt
}

API Routes:

• POST /api/users/{id}/follow - Follow user
• DELETE /api/users/{id}/unfollow - Unfollow
• GET /api/users/{id}/followers - Get followers
• GET /api/users/{id}/following - Get following list
• GET /api/users/{id}/is-following - Check if following

Components:

components/social/
├── FollowButton.tsx
├── FollowersList.tsx
├── FollowingList.tsx
├── CreatorCard.tsx
└── UserHover.tsx (tooltip with stats)

Database Indexes:

• CREATE INDEX idx_follow_follower ON Follow(followerId)
• CREATE INDEX idx_follow_followee ON Follow(followeeId)

Deliverables:

• Follow system working
• Followers/following lists
• Follow counts accurate
• Performance optimized

---

User Story 2.1.2: Creator Discovery

AS A viewer
I WANT to see popular creators
SO THAT I can find quality content

Tasks:

• Build "Explore" or "Browse" page
• Display live creators with metadata
• Sort by: live, trending, new
• Category filtering
• Creator cards with stats

Routes:

• GET /api/streams?status=LIVE - Get live streams
• GET /api/streams/trending - Trending streams
• GET /api/streams/new - Newest streams
• GET /api/streams/by-category/:category - Filter by category

Page Structure:

/discover
├── Live Tab (50+ concurrent viewers)
├── Trending Tab (most watched this week)
├── New Tab (just went live)
└── Category Browser

Components:

components/discover/
├── DiscoverPage.tsx
├── StreamCard.tsx
├── CategoryFilter.tsx
├── SortOptions.tsx
└── LiveBadge.tsx

Deliverables:

• Discover page functional
• Sorting/filtering working
• Real-time live stream list
• Load performance <1s

---

User Story 2.1.3: User Profiles & Hubs

AS A creator
I WANT a public profile page
SO THAT I can showcase my work and gain followers

Route: /channel/{creatorUsername}

Tasks:

• Build public creator profile
• Display channel info and stats
• Show recent streams
• Show VODs (Phase 3)
• Follow/unfollow button
• Social links display

Page Components:

/channel/[username].tsx
├── CreatorHeader (avatar, name, stats)
├── FollowButton
├── SocialLinks
├── Tabs:
│   ├── About (bio, description)
│   ├── Live/Upcoming
│   ├── VODs (Phase 3)
│   └── Clips (Phase 3)
└── RecentStreams

Data to Display:

• Channel name, avatar, banner
• Follower count, view count
• Recent streams
• Social links
• Bio/description
• Verified badge (Phase 4+)

Deliverables:

• Profile page beautiful and functional
• Mobile responsive
• Stats accurate and updating

---

Sprint 2.2: Discovery & Search

Duration: Days 6-10 | Team: 2 devs

User Story 2.2.1: Stream Search

AS A viewer
I WANT to search for streams
SO THAT I can find specific content

Tasks:

• Build search input component
• Implement full-text search database
• Search by: creator name, stream title, tags
• Real-time search results
• Search history/suggestions

Search Implementation Options:

Option A: PostgreSQL FTS (Easier)

-- Add search columns
ALTER TABLE Stream ADD COLUMN search_vector tsvector;

-- Create index for fast search
CREATE INDEX search_index ON Stream USING gin(search_vector);

-- Update trigger on insert/update
CREATE TRIGGER stream_search_update BEFORE INSERT OR UPDATE
ON Stream FOR EACH ROW
EXECUTE FUNCTION tsvector_update_trigger(search_vector, 'pg_catalog.english', title);

Option B: Algolia (Better UX)

• Managed search platform
• Real-time indexing
• Advanced filtering
• ~$45/month

API Routes:

• GET /api/search?q=query - Search all
• GET /api/search/streams?q=query - Search streams
• GET /api/search/creators?q=query - Search creators
• GET /api/search/suggestions?q=query - Autocomplete

Components:

components/search/
├── SearchInput.tsx
├── SearchResults.tsx
├── ResultCard.tsx
└── SearchSuggestions.tsx

Performance Targets:

• Suggestions response: <100ms
• Search results: <500ms
• Autocomplete: <50ms

Deliverables:

• Search working
• Real-time autocomplete
• Performance optimized
• Relevant results ranking

---

User Story 2.2.2: Category Browsing

AS A viewer
I WANT to browse streams by category
SO THAT I can find content I care about

Tasks:

• Define category taxonomy
• Build category page
• Display streams by category
• Category recommendations
• Subcategories (optional)

Categories (proposal):

const CATEGORIES = [
  { id: 'just-chatting', label: 'Just Chatting', icon: '💬' },
  { id: 'gaming', label: 'Gaming', icon: '🎮', 
    subcategories: ['FPS', 'RPG', 'Esports', 'Indie'] },
  { id: 'music', label: 'Music & DJs', icon: '🎵',
    subcategories: ['Beats Making', 'Live DJ', 'Karaoke'] },
  { id: 'creative', label: 'Creative', icon: '🎨',
    subcategories: ['Art', 'Music Production', 'Design'] },
  { id: 'education', label: 'Education', icon: '📚',
    subcategories: ['Tech', 'Languages', 'Business'] },
  { id: 'business', label: 'Business', icon: '💼',
    subcategories: ['Marketing', 'Finance', 'Startups'] },
]

Database:

model Category {
  id                String    @id @default(cuid())
  slug              String    @unique
  name              String
  description       String?
  icon              String?
  image             String?
  order             Int       @default(999)
  
  streams           Stream[]
}

// Update Stream model
model Stream {
  // ...
  categoryId        String?
  category          Category? @relation(fields: [categoryId], references: [id])
}

Routes:

• GET /api/categories - All categories
• GET /api/categories/:slug - Category page
• GET /api/categories/:slug/streams - Streams in category

Pages:

• /categories - Category grid browser
• /category/:slug - Category detail page

Deliverables:

• Categories defined
• Category browsing working
• Stream filtering by category
• Popular categories highlighted

---

User Story 2.2.3: Trending & Recommended

AS A viewer
I WANT to see recommended streams
SO THAT I discover quality content

Tasks:

• Build trending algorithm
• Implement recommendations
• Homepage feed with recommendations
• Trending streams widget
• "Recommended for You" section

Trending Algorithm (simple v1):

Score = (viewers / avg_viewers) * 0.5 + 
        (NEW streams * 2) + 
        (messages_per_minute / baseline) * 0.3

Recommendations Algorithm (v1 - collaborative filtering):

For each user:
1. Find similar users (who follow same creators)
2. Get streams those similar users watched
3. Filter out streams user already watched
4. Rank by similarity weight
5. Return top 10

Simpler v1: Just show what's trending to everyone

API Routes:

• GET /api/trending - Trending streams
• GET /api/recommendations - Personalized recommendations
• GET /api/featured - Admin-featured streams (Phase 4)

Components:

components/discover/
├── TrendingCarousel.tsx
├── RecommendedSection.tsx
├── StreamCarousel.tsx
└── CarouselCard.tsx

Home Page Redesign:

/
├── Hero (current live stream or CTA)
├── Featured Streams (3-5)
├── Recommended For You (10)
├── Live Now (scrollable list)
├── Popular Categories (carousel)
├── Top Creators (by followers)
└── FAQ/Links

Deliverables:

• Trending algorithm working
• Recommendations functioning
• Home page attractive and engaging
• Performance optimized (<1s load)

---

Sprint 2.3: Creator Dashboard & Notifications

Duration: Days 11-15 | Team: 1-2 devs

User Story 2.3.1: Enhanced Creator Dashboard

AS A creator
I WANT an improved dashboard
SO THAT I can see everything I need to manage streams

Tasks:

• Upgrade dashboard layout
• Real-time statistics
• Recent interactions
• Upcoming broadcast scheduler
• Quick stream start

Dashboard Sections:

/dashboard
├── Quick Stats (viewers, followers, messages)
├── Go Live Widget (one-click publishing)
├── Recent Streams (table with duration, viewers)
├── Analytics Summary
│   ├── Peak viewers (this stream, this week)
│   ├── Average watch time
│   ├── Chat messages
│   └── New followers
├── Recent Followers (scrollable list)
├── Chat Activity (recent messages)
└── Upcoming (if scheduling added)

Real-time Updates:

• Viewer count updates every 5 seconds
• New follower notifications
• Chat message count
• Stream health metrics

Components:

components/dashboard/
├── DashboardLayout.tsx
├── StatsCard.tsx
├── RecentStreamsList.tsx
├── AnalyticsSummary.tsx
├── RecentFollowers.tsx
├── QuickStartWidget.tsx
└── ChatActivity.tsx

Deliverables:

• Dashboard fully functional
• Real-time stats updating
• Mobile responsive
• Fast loading (<1s)

---

User Story 2.3.2: Notifications System

AS A user
I WANT to receive notifications
SO THAT I stay updated on channels I follow

Tasks:

• Create notifications table
• Build notification events
• In-app notification center
• Email notifications (optional)
• Push notifications (Phase 9)
• Notification preferences

Notification Types:

enum NotificationType {
  FOLLOW = 'follow',
  STREAM_LIVE = 'stream_live',
  STREAM_ENDED = 'stream_ended',
  NEW_CLIP = 'new_clip',
  SUBSCRIPTION = 'subscription',
  RAID = 'raid', // Phase 5
  GIFT = 'gift', // Phase 4
  MENTION = 'mention', // Phase 5
}

Schema:

model Notification {
  id                String    @id @default(cuid())
  userId            String
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  type              NotificationType
  
  // Polymorphic reference
  relatedUserId     String?   // For follows
  streamId          String?   // For stream events
  
  title             String
  message           String
  image             String?
  link              String?
  
  read              Boolean   @default(false)
  readAt            DateTime?
  
  createdAt         DateTime  @default(now())
}

model NotificationPreference {
  id                String    @id @default(cuid())
  userId            String    @unique
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  streamLiveEmail    Boolean   @default(true)
  streamLiveInApp    Boolean   @default(true)
  
  followsEmail      Boolean   @default(false)
  followsInApp      Boolean   @default(true)
  
  clipsEmail        Boolean   @default(false)
  clipsInApp        Boolean   @default(true)
  
  updatedAt         DateTime  @updatedAt
}

API Routes:

• GET /api/notifications - Get user notifications
• PUT /api/notifications/:id/read - Mark as read
• PUT /api/notifications/read-all - Mark all read
• DELETE /api/notifications/:id - Delete notification
• GET /api/notification-preferences - Get preferences
• PUT /api/notification-preferences - Update preferences

WebSocket Events (for real-time):

socket.emit('stream:live', { streamId, creatorId })
// Automatically notify all followers

Components:

components/notifications/
├── NotificationBell.tsx
├── NotificationCenter.tsx
├── NotificationItem.tsx
├── NotificationPreferences.tsx
└── NotificationDropdown.tsx

Deliverables:

• Notification system working
• In-app notifications functional
• Preferences page working
• Email notifications optional

---

Sprint 2.4: Polish & Integration

Duration: Days 16-20 | Team: 2 devs

User Story 2.4.1: Home Page Redesign

AS A visitor
I WANT an engaging homepage
SO THAT I'm encouraged to sign up and explore

Homepage Layout:

pages/index.tsx
├── Navigation
├── Hero Section
│   ├── Headline "Stream Your Way"
│   ├── CTA (Sign Up)
│   └── Video background or demo
├── Feature Highlights (3 columns)
│   ├── Creator-Friendly
│   ├── Community-Focused
│   └── Multi-Format
├── Live Streams Section (carousel)
├── Statistics/Numbers
├── Testimonials (Phase 2+)
├── FAQ Section
└── Footer

Deliverables:

• Homepage attractive
• Mobile responsive
• High conversion rate

---

User Story 2.4.2: Mobile Responsiveness

AS A mobile user
I WANT a perfect experience
SO THAT I can use AeThex on any device

Tasks:

• Mobile navigation (hamburger menu)
• Responsive discovery page
• Mobile-friendly chat
• Touch-friendly buttons
• Optimized images
• Fast loading (<3s on 4G)

Testing:

• iPhone 12/14/15 test
• Android Galaxy S series test
• iPad/tablet test
• 4G network test
• Lighthouse scores >90

Deliverables:

• All pages mobile responsive
• Fast mobile experience
• Touch-optimized UI

---

Database Schema - Phase 2 Updates

New Models:

model Category {
  id                String    @id @default(cuid())
  slug              String    @unique
  name              String
  icon              String?
  order             Int
  
  streams           Stream[]
}

model Notification {
  id                String    @id @default(cuid())
  userId            String
  user              User      @relation(fields: [userId], references: [id])
  type              NotificationType
  title             String
  message           String
  read              Boolean   @default(false)
  createdAt         DateTime  @default(now())
}

model NotificationPreference {
  id                String    @id @default(cuid())
  userId            String    @unique
  user              User      @relation(fields: [userId], references: [id])
  streamLiveEmail    Boolean
  streamLiveInApp    Boolean
  // ... more fields
}

Updated Models:

model Stream {
  // ... existing
  categoryId        String?
  category          Category? @relation(fields: [categoryId])
}

model ChannelStats {
  // Add viewer trending
  peakViewersToday  Int
  avgViewersToday   Int
  // Add for trending calculation
}

---

API Routes - Phase 2 Additions

Social

• POST /api/users/:id/follow
• DELETE /api/users/:id/unfollow
• GET /api/users/:id/followers
• GET /api/users/:id/following

Discovery

• GET /api/streams?status=LIVE&sort=trending
• GET /api/categories
• GET /api/categories/:slug/streams
• GET /api/search?q=query
• GET /api/trending
• GET /api/recommendations

Notifications

• GET /api/notifications
• PUT /api/notifications/:id/read
• PUT /api/notification-preferences

---

Components - Phase 2 Additions

Discover

components/discover/
├── DiscoverPage.tsx
├── StreamCard.tsx
├── CreatorCard.tsx
├── CategoryFilter.tsx
├── TrendingCarousel.tsx
└── RecommendedSection.tsx

Social

components/social/
├── FollowButton.tsx
├── FollowersList.tsx
├── CreatorProfile.tsx
└── UserHover.tsx

Search

components/search/
├── SearchInput.tsx
├── SearchResults.tsx
└── SearchSuggestions.tsx

Notifications

components/notifications/
├── NotificationBell.tsx
├── NotificationCenter.tsx
├── NotificationItem.tsx
└── NotificationPreferences.tsx

---

Third-Party Services

Search (Optional - Phase 2B)

• Algolia: $45/month for full-text search
• ElasticSearch: Self-hosted or Elastic Cloud

Analytics (For recommendations)

• PostHog: Already optional in Phase 1
• Build in-house tracking for Phase 2

---

Success Metrics

Discovery Metrics

• 100k+ searches/month by week 8
• <500ms average search latency
• 95% search relevance rating
• 20% of viewers use search

Social Metrics

• 2,000+ follow relationships
• 50%+ of viewers follow creators
• 30% of users on finding via recommendations
• 15% growth in followers/channel

Notification Metrics

• 60%+ users enable notifications
• 40%+ click-through on notifications
• <10 false positives per user/month
• <5s latency on notifications

Engagement Metrics

• 20% increase in daily active users
• 30% increase in stream discovery
• 25% increase in average session time
• 15% increase in followers/creator

---

Known Issues & Limitations

Phase 2 Limitations

1. Simple recommendations: No ML, just collaborative filtering
2. No trending prediction: Trends calculated in real-time
3. No hot clips featured: Added in Phase 3
4. No creator verification: Added in Phase 4
5. Generic categories: Can be expanded with specific game/genre data

Improvements in Future Phases

• Phase 3: Trending clips
• Phase 4: Verified badges, featured streams
• Phase 5: Advanced moderators, pinned messages
• Phase 9: ML-based recommendations

---

Development Timeline

Week	Sprint	Focus
5	2.1	Follow system, discovery basics
6	2.2	Search, category browsing
7	2.3	Notifications, creator dashboard
8	2.4	Polish, mobile, deployment

---

Phase 2 Completion Checklist

• Follow system working
• Discovery page attractive
• Search functional and fast
• Notifications working
• Creator dashboard enhanced
• Mobile responsive
• Database optimized
• Tests passing
• Deployed to production
• 250+ creators onboarded
• 2000+ users registered

---

Phase 2 Estimated Completion: Week 8 (by March 28, 2025)
Next Phase: Phase 3 - Creator Tools & VOD (April 1, 2025)

See PHASE_3_CREATOR_TOOLS.md for Phase 3 details.