# 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**:
```prisma
// 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)*
```sql
-- 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):
```typescript
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**:
```prisma
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**:
```typescript
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**:
```prisma
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):
```typescript
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**:
```prisma
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**:
```prisma
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](PHASE_3_CREATOR_TOOLS.md) for Phase 3 details.