aethex.live/docs/PHASE_1_FOUNDATION.md

# Phase 1: Foundation - Complete Implementation Guide

**Duration**: Weeks 1-4 | **Complexity**: High | **Status**: IN PROGRESS (50%)

## Executive Summary

Phase 1 establishes the core streaming platform: user authentication, creator channels, basic HLS streaming with chat functionality, and stream lifecycle management. This is the foundation upon which all subsequent phases are built.

---

## Phase 1 Goals

### Primary Goal
Launch a working live streaming platform where creators can:
1. Sign up and create a channel
2. Get an RTMP ingest URL for streaming
3. Go live and manage their stream
4. Communicate with viewers in real-time via chat

### Success Criteria
- ✅ 100+ creators onboarded
- ✅ 500+ registered users  
- ✅ 50+ concurrent peak viewers
- ✅ <2s stream start latency
- ✅ <100ms chat message latency
- ✅ 99.9% streaming uptime
- ✅ Zero critical bugs in production

---

## Sprint Breakdown

### Sprint 1.1: Database & Authentication
**Duration**: Days 1-5 | **Team**: 1-2 devs | **Status**: 🔄 IN PROGRESS

#### User Story 1.1.1: Database Setup
```
AS A developer
I WANT a PostgreSQL database schema
SO THAT I can store user and channel data reliably
```

**Tasks**:
- [ ] Create PostgreSQL database on Railway  
- [ ] Initialize Prisma project  
- [ ] Create initial schema (see below)
- [ ] Set up database migrations
- [ ] Add connection pooling

**Schema - Core Tables**:
```prisma
model User {
  id                String    @id @default(cuid())
  email             String    @unique
  username          String    @unique
  displayName       String
  avatar            String?
  bio               String?
  createdAt         DateTime  @default(now())
  updatedAt         DateTime  @updatedAt
  
  // Relations
  profile           Profile?
  channels          Channel[]
  followees         Follow[]  @relation("follower")
  followers         Follow[]  @relation("followee")
  chatMessages      Message[]
  subscriptions     Subscription[]
  
  // Clerk integration
  clerkId           String    @unique
}

model Profile {
  id                String    @id @default(cuid())
  userId            String    @unique
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  socialLinks       String?   // JSON: { twitch, youtube, twitter, etc }
  notificationEmail String?
  theme             String    @default("dark")
  language          String    @default("en")
  createdAt         DateTime  @default(now())
  updatedAt         DateTime  @updatedAt
}

model Channel {
  id                String    @id @default(cuid())
  creatorId         String
  creator           User      @relation(fields: [creatorId], references: [id], onDelete: Cascade)
  name              String
  slug              String    @unique
  description       String?
  avatar            String?
  banner            String?
  
  // Stream settings
  category          String    @default("just-chatting")
  tags              String[]  @default([])
  isPublic          Boolean   @default(true)
  
  // RTMP ingest
  streamKey         String    @unique @default(cuid())
  streamUrl         String    @default("rtmp://ingest.aethex.live/live")
  
  // Stats
  viewCount         Int       @default(0)
  followerCount     Int       @default(0)
  
  createdAt         DateTime  @default(now())
  updatedAt         DateTime  @updatedAt
  
  // Relations
  streams           Stream[]
  followers         ChannelFollow[]
  messages          Message[]
}

model Stream {
  id                String    @id @default(cuid())
  channelId         String
  channel           Channel   @relation(fields: [channelId], references: [id], onDelete: Cascade)
  
  title             String
  description       String?
  
  status            StreamStatus @default(OFFLINE) // OFFLINE, LIVE, ENDING, ARCHIVED
  startTime         DateTime?
  endTime           DateTime?
  
  // Streaming specifics
  viewerCount       Int       @default(0)
  peakViewers       Int       @default(0)
  duration          Int?      // in seconds
  
  // HLS details
  hlsUrl            String?
  thumbnailUrl      String?
  recordingPath     String?
  
  // VOD (added in Phase 3)
  isArchived        Boolean   @default(false)
  vodUrl            String?
  
  createdAt         DateTime  @default(now())
  updatedAt         DateTime  @updatedAt
  
  // Relations
  messages          Message[]
}

enum StreamStatus {
  OFFLINE
  LIVE
  ENDING
  ARCHIVED
}

model Message {
  id                String    @id @default(cuid())
  channelId         String
  channel           Channel   @relation(fields: [channelId], references: [id], onDelete: Cascade)
  streamId          String?
  stream            Stream?   @relation(fields: [streamId], references: [id], onDelete: SetNull)
  
  userId            String
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  content           String
  
  // For Phase 2+ features
  badges            String[]  @default([]) // moderator, subscriber, etc
  
  createdAt         DateTime  @default(now())
  
  // Soft delete for moderation
  deletedAt         DateTime?
}

// Social - Added in Phase 2, but framework in Phase 1
model Follow {
  id                String    @id @default(cuid())
  followerId        String
  follower          User      @relation("follower", fields: [followerId], references: [id], onDelete: Cascade)
  
  followeeId        String
  followee          User      @relation("followee", fields: [followeeId], references: [id], onDelete: Cascade)
  
  createdAt         DateTime  @default(now())
  
  @@unique([followerId, followeeId])
}

model ChannelFollow {
  id                String    @id @default(cuid())
  userId            String
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  channelId         String
  channel           Channel   @relation(fields: [channelId], references: [id], onDelete: Cascade)
  
  createdAt         DateTime  @default(now())
  
  @@unique([userId, channelId])
}

// Monetization - Added in Phase 4, framework in Phase 1
model Subscription {
  id                String    @id @default(cuid())
  userId            String
  user              User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  channelId         String
  
  tier              SubscriptionTier @default(BASIC)
  stripeSubId       String?
  
  status            SubStatus @default(ACTIVE) // ACTIVE, CANCELLED, EXPIRED
  startDate         DateTime  @default(now())
  renewalDate       DateTime?
  
  createdAt         DateTime  @default(now())
  updatedAt         DateTime  @updatedAt
}

enum SubscriptionTier {
  BASIC
  PREMIUM
  VIP
}

enum SubStatus {
  ACTIVE
  CANCELLED
  EXPIRED
}
```

**Deliverables**:
- [ ] Prisma schema file
- [ ] Migration files
- [ ] Database deployed on Railway
- [ ] Connection tests passing

---

#### User Story 1.1.2: Clerk Authentication
```
AS A user
I WANT to sign up and authenticate
SO THAT I can access the platform securely
```

**Tasks**:
- [ ] Set up Clerk account
- [ ] Install @clerk/nextjs
- [ ] Create auth middleware
- [ ] Build sign-up page (`/auth/register`)
- [ ] Build login page (`/auth/login`)
- [ ] Build onboarding form (username, avatar, bio)
- [ ] Sync Clerk users to database

**Components to Build**:
```
components/auth/
├── SignUpForm.tsx
├── LoginForm.tsx
├── OnboardingForm.tsx
└── AuthGuard.tsx
```

**API Routes**:
- `POST /api/auth/onboard` - Create user profile after Clerk signup
- `GET /api/auth/user` - Get current user
- `PUT /api/auth/profile` - Update profile

**Deliverables**:
- [ ] Sign up flow working
- [ ] Clerk + Prisma sync
- [ ] Protected routes working
- [ ] User profiles created

---

#### User Story 1.1.3: Creator Profile Management
```
AS A creator
I WANT to manage my channel profile
SO THAT I can customize my brand
```

**Tasks**:
- [ ] Build profile edit page (`/dashboard/profile`)
- [ ] Avatar upload to Cloudflare R2
- [ ] Banner upload to Cloudflare R2
- [ ] Bio/description editing
- [ ] Social links configuration
- [ ] Theme preferences

**Components**:
```
components/dashboard/
├── ProfileEditor.tsx
├── AvatarUpload.tsx
├── BannerUpload.tsx
└── SocialLinksForm.tsx
```

**API Routes**:
- `PUT /api/profile` - Update user profile
- `POST /api/upload/avatar` - Upload avatar
- `POST /api/upload/banner` - Upload banner

**Deliverables**:
- [ ] Profile editing working
- [ ] File uploads to R2
- [ ] Profile display on public pages

---

### Sprint 1.2: Basic Streaming
**Duration**: Days 6-10 | **Team**: 2 devs | **Status**: ✅ MOSTLY DONE

#### User Story 1.2.1: Creator Dashboard
```
AS A creator
I WANT a dashboard to manage my streams
SO THAT I can go live and monitor activity
```

**Tasks**:
- [x] Build dashboard layout (`/dashboard`)
- [x] Display stream key securely
- [x] Show/hide stream key functionality
- [x] Copy stream key to clipboard
- [x] Stream status display
- [x] Viewer count display
- [x] Go live button
- [x] End stream button

**Components**:
```
components/dashboard/
├── Dashboard.tsx
├── StreamKeyDisplay.tsx
├── StreamStatus.tsx
├── GoLiveButton.tsx
└── StreamSettings.tsx
```

**Deliverables**:
- [x] Dashboard functional
- [x] Stream key shown securely
- [x] Go live/end stream buttons

---

#### User Story 1.2.2: HLS Player Implementation
```
AS A viewer
I WANT to watch live streams
SO THAT I can see creators' content
```

**Current Status**: ✅ DONE

**Components**:
```
components/
├── HLSPlayer.tsx (DONE)
├── VideoControls.tsx (DONE)
└── QualitySelector.tsx (DONE)
```

**Features Implemented**:
- [x] HLS.js integration
- [x] Adaptive bitrate switching
- [x] Auto-recovery on disconnection
- [x] Full-screen support
- [x] Mobile responsive

**Deliverables**:
- [x] Player component reusable
- [x] Error handling
- [x] Mobile responsive

---

#### User Story 1.2.3: Stream Ingestion Setup
```
AS PLATFORM OWNER
I WANT to receive RTMP streams
SO THAT creators can broadcast
```

**Tasks**:
- [ ] Set up Cloudflare Stream or Mux account
- [ ] Configure RTMP ingest endpoint
- [ ] Set up HLS playback endpoint
- [ ] Stream key validation
- [ ] Bitrate/quality management
- [ ] Automated stream archival

**Config**:
```
// config/streaming.ts
export const streamingConfig = {
  provider: 'cloudflare-stream', // or 'mux'
  rtmpIngest: 'rtmp://ingest.aethex.live/live',
  hlsPlayback: 'https://video.aethex.live/{streamId}.m3u8',
  recordingPath: 's3://aethex-archive/',
  qualities: ['1080p', '720p', '480p'],
  bitrates: [8000, 5000, 2500], // kbps
}
```

**API Routes**:
- `POST /api/stream/create` - Start streaming session
- `POST /api/stream/end` - End stream
- `GET /api/stream/{id}` - Get stream info
- `GET /api/stream/{id}/hls` - Get HLS URL

**Deliverables**:
- [ ] Cloudflare/Mux integrated
- [ ] RTMP ingest working
- [ ] HLS playback working
- [ ] Stream archival configured

---

#### User Story 1.2.4: Stream Lifecycle
```
AS A system
I WANT to manage stream state
SO THAT viewers and creators see accurate status
```

**Tasks**:
- [ ] Stream creation on go live
- [ ] Stream status updates
- [ ] View count tracking
- [ ] Peak viewer tracking
- [ ] Stream ending/cleanup
- [ ] Recording management

**Database Updates**:
- `streams.status` (OFFLINE → LIVE → ENDING → ARCHIVED)
- `streams.startTime`, `endTime`
- `streams.viewerCount`, `peakViewers`
- `streams.duration`

**API Routes**:
- `POST /api/streams/{channelId}/start` - Go live
- `PUT /api/streams/{id}/status` - Update status
- `POST /api/streams/{id}/end` - End stream

**Deliverables**:
- [ ] Stream state machine working
- [ ] Status updates real-time (via Socket.io)
- [ ] View counts accurate

---

### Sprint 1.3: Real-time Chat
**Duration**: Days 11-15 | **Team**: 1-2 devs | **Status**: 🔄 IN PROGRESS

#### User Story 1.3.1: Chat Backend Setup
```
AS A viewer
I WANT to send and receive chat messages
SO THAT I can interact in real-time
```

**Tasks**:
- [ ] Set up Socket.io server on Next.js
- [ ] Create chat rooms per stream
- [ ] User connection tracking
- [ ] Message broadcasting
- [ ] Message persistence to database
- [ ] Chat history loading

**Socket Events**:
```typescript
// Client → Server
socket.emit('chat:join', { streamId: string })
socket.emit('chat:send', { content: string })
socket.emit('chat:leave')

// Server → Client
socket.on('chat:message', (message: Message))
socket.on('chat:user-joined', (user: User))
socket.on('chat:user-left', (userId: string))
socket.on('chat:history', (messages: Message[]))
```

**API Routes**:
- `GET /api/streams/{id}/messages` - Get chat history
- `POST /api/streams/{id}/messages` - Send message
- `DELETE /api/messages/{id}` - Delete message (moderation)

**Deliverables**:
- [ ] Socket.io server running
- [ ] Chat messages persisted
- [ ] Real-time broadcasting
- [ ] History loading

---

#### User Story 1.3.2: Chat UI Component
```
AS A viewer
I WANT an intuitive chat interface
SO THAT I can easily participate
```

**Tasks**:
- [ ] Build chat message list
- [ ] Build message input
- [ ] Typing indicators
- [ ] User list (online viewers)
- [ ] Message timestamps
- [ ] Scroll to latest message
- [ ] Mobile responsive chat

**Components**:
```
components/chat/
├── ChatContainer.tsx
├── MessageList.tsx
├── MessageItem.tsx
├── ChatInput.tsx
├── UserList.tsx
└── TypingIndicator.tsx
```

**Features**:
- [ ] Auto-scroll to latest
- [ ] Emotes (Phase 5)
- [ ] Moderation badges
- [ ] Timestamp formatting

**Deliverables**:
- [ ] Chat UI fully functional
- [ ] Mobile responsive
- [ ] Accessible (ARIA labels)

---

#### User Story 1.3.3: Chat Moderation Foundation
```
AS A creator
I WANT to moderate chat
SO THAT I can enforce community standards
```

**Tasks**:
- [ ] Creator moderation dashboard
- [ ] Delete message functionality
- [ ] Basic profanity filter
- [ ] User block/ignore feature
- [ ] Message reporting UI

**API Routes**:
- `DELETE /api/messages/{id}` - Delete message
- `POST /api/users/{id}/block` - Block user
- `PUT /api/channels/{id}/filters` - Set content filters
- `POST /api/reports` - Report message/user

**Components**:
```
components/moderation/
├── ModerationPanel.tsx
├── MessageActions.tsx
├── BlockUserModal.tsx
└── FilterSettings.tsx
```

**Deliverables**:
- [ ] Message deletion working
- [ ] Block system working
- [ ] Moderation panel functional

---

### Integration: Stream Page
**Duration**: Days 16-20 | **Team**: 2 devs

Bring everything together into a complete live stream page.

#### User Story 1.3.4: Live Stream Viewer Page
```
AS A viewer
I WANT to watch a live stream with chat
SO THAT I can enjoy content and interact
```

**Route**: `/streams/{channelSlug}`

**Page Components**:
```
pages/streams/[channelSlug].tsx
├── HLSPlayer (full width)
├── ChatContainer
├── ViewerCount
├── StreamInfo (title, creator, description)
└── CreatorCard (follow button, social)
```

**Features**:
- [ ] Responsive layout (player + chat side-by-side on desktop)
- [ ] Chat mobile drawer (mobile)
- [ ] Real-time viewer count
- [ ] Stream information display
- [ ] Creator profile card with follow button
- [ ] Share buttons
- [ ] Quality selector

**Styling**:
- [ ] Use existing Tailwind setup
- [ ] Dark theme friendly
- [ ] Accessibility (keyboard nav, screen readers)

**Deliverables**:
- [ ] Full-featured stream page
- [ ] Mobile responsive
- [ ] Real-time updates

---

### Testing & Deployment
**Duration**: Days 21-28 | **Team**: 2-3 devs

#### Testing Coverage
- [ ] Unit tests for API routes (95% coverage)
- [ ] Integration tests for Socket.io
- [ ] E2E tests: Sign up → Create channel → Go live → View stream
- [ ] Load testing with 1000 concurrent viewers
- [ ] Chat stress test (1000 msg/sec)

#### Deployment Checklist
- [ ] Environment variables set on Railway
- [ ] Database migrations run
- [ ] Clerk configured for production
- [ ] Cloudflare/Mux configured
- [ ] R2 bucket created and policy set
- [ ] Socket.io CORS configured
- [ ] Vercel deployment working
- [ ] Custom domain DNS set
- [ ] SSL certificate configured
- [ ] Monitoring setup (Sentry, PostHog)

#### Production Monitoring
- [ ] Uptime monitoring (Uptime Robot)
- [ ] Error tracking (Sentry)
- [ ] Analytics (PostHog)
- [ ] Database performance (Railway dashboard)
- [ ] Stream quality (Cloudflare/Mux metrics)

---

## Database Schema - Complete Phase 1

See Prisma schema defined in Sprint 1.1 above. Key tables:
- `User` - User accounts
- `Profile` - User profiles
- `Channel` - Creator channels
- `Stream` - Live streams
- `Message` - Chat messages
- `Follow` - User-to-user follows (framework)
- `ChannelFollow` - Channel follows (framework)
- `Subscription` - Subscriptions (framework)

---

## API Routes - Phase 1

### Authentication
- `POST /api/auth/onboard` - Create user after signup
- `GET /api/auth/user` - Get current logged-in user
- `PUT /api/auth/profile` - Update profile

### User Management
- `GET /api/users/{id}` - Get user profile
- `PUT /api/users/{id}` - Update user
- `POST /api/users/{id}/block` - Block user
- `POST /api/upload/avatar` - Upload avatar
- `POST /api/upload/banner` - Upload banner

### Channels
- `POST /api/channels` - Create channel
- `GET /api/channels/{slug}` - Get channel info
- `PUT /api/channels/{id}` - Update channel
- `GET /api/channels/{id}/vod` - Get VODs

### Streaming
- `POST /api/streams` - Create stream session
- `GET /api/streams/{id}` - Get stream info
- `PUT /api/streams/{id}/status` - Update stream status
- `POST /api/streams/{id}/end` - End stream
- `GET /api/streams/{id}/messages` - Get chat history

### Chat
- `POST /api/messages` - Send message (via Socket.io preferred)
- `GET /api/streams/{id}/messages` - Get message history
- `DELETE /api/messages/{id}` - Delete message

See [API_STRUCTURE.md](API_STRUCTURE.md) for complete details.

---

## Components - Phase 1

### Layout Components
- `App/layout.tsx` - Root layout
- `components/Navigation.tsx` - Top nav
- `components/Sidebar.tsx` - Side navigation

### Auth Components
- `components/auth/SignUpForm.tsx`
- `components/auth/LoginForm.tsx`
- `components/auth/OnboardingForm.tsx`

### Dashboard Components
- `components/dashboard/Dashboard.tsx`
- `components/dashboard/StreamKeyDisplay.tsx`
- `components/dashboard/StreamStatus.tsx`
- `components/dashboard/ProfileEditor.tsx`

### Streaming Components
- `components/HLSPlayer.tsx` ✅
- `components/ViewerCount.tsx`
- `components/NowPlaying.tsx`

### Chat Components
- `components/chat/ChatContainer.tsx`
- `components/chat/MessageList.tsx`
- `components/chat/MessageItem.tsx`
- `components/chat/ChatInput.tsx`
- `components/chat/UserList.tsx`

### Page Components
- `app/page.tsx` - Home/landing
- `app/dashboard/page.tsx` - Creator dashboard
- `app/streams/[channelSlug]/page.tsx` - Stream viewer page

---

## Third-Party Integrations

### 1. Clerk (Authentication)
- **Status**: 🔄 IN PROGRESS
- **Setup**: Web dashboard at clerk.com
- **Config**: .env.local varaiables set
- **Integration**: Next.js middleware + components

### 2. Cloudflare Stream OR Mux (Video)
- **Status**: ⏳ NOT STARTED
- **Choose one**:
  - Cloudflare Stream: $0.05/min cheaper, simpler
  - Mux: Better UI, more features
- **Setup**: Account created, API key obtained
- **Integration**: API calls for stream creation, HLS URLs
- **Cost**: ~$200-500/month at scale

### 3. R2 (File Storage)
- **Status**: ⏳ NOT STARTED
- **Setup**: Cloudflare R2 bucket created
- **Access**: API tokens generated
- **Integration**: Avatar/banner uploads, VOD storage
- **Cost**: ~$20/month at scale

### 4. PostgreSQL (Database)
- **Status**: ⏳ NOT STARTED (or 🔄 IN PROGRESS)
- **Where**: Railway.app
- **Setup**: Database created, connection string obtained
- **Integration**: Prisma connection string in .env
- **Cost**: ~$10-20/month

### 5. Redis (Optional - for Phase 2+)
- **Status**: ⏳ NOT STARTED
- **Use**: Caching, rate limiting, sessions
- **Provider**: Upstash or Railway
- **Cost**: ~$5-10/month

---

## Success Metrics

### User Metrics
- [ ] 100+ creators signed up
- [ ] 500+ total users (including viewers)
- [ ] 10+ daily active creators
- [ ] 50+ daily active users

### Engagement Metrics
- [ ] 50+ concurrent peak viewers
- [ ] 100+ chat messages per stream
- [ ] Average 5+ minute watch time
- [ ] 20%+ creator return rate

### Technical Metrics
- [ ] 99.9% streaming uptime (0 minutes downtime)
- [ ] <2s stream connection latency
- [ ] <100ms chat message latency
- [ ] <500ms page load time

### Quality Metrics
- [ ] 0 critical bugs in production
- [ ] Zero unplanned downtime
- [ ] <5% error rate on API calls
- [ ] <2% failed chat messages

---

## Known Issues & Future Improvements

### Phase 1 Limitations
1. **Single server**: Not horizontally scalable yet
2. **No persistent chat**: Messages lost on server restart
3. **No clips/VOD**: Added in Phase 3
4. **No monetization**: Added in Phase 4
5. **Basic moderation**: Improved in Phase 5

### Improvements for Future Phases
- Phase 2: Discover, follow, recommendations
- Phase 3: VOD archival, clips editor
- Phase 4: Subscriptions, donations
- Phase 5: Advanced moderation, emotes

---

## Resources & Links

- **Clerk Docs**: https://clerk.com/docs
- **Prisma Docs**: https://www.prisma.io/docs
- **Cloudflare Stream**: https://developers.cloudflare.com/stream
- **Mux Docs**: https://docs.mux.com
- **Socket.io Docs**: https://socket.io/docs
- **HLS.js**: https://github.com/video-dev/hls.js

---

## Completion Checklist

### Sprint 1.1 ✅
- [ ] Database schema created
- [ ] Migrations working
- [ ] Clerk authentication integrated
- [ ] User profiles created
- [ ] Profile editing working

### Sprint 1.2 ✅
- [ ] Dashboard built
- [ ] Stream key management
- [ ] HLS player integrated
- [ ] Go live / end stream working
- [ ] Viewer count updating

### Sprint 1.3 🔄
- [ ] Socket.io server running
- [ ] Chat messages persisting
- [ ] Chat UI built
- [ ] Real-time messaging working
- [ ] Moderation basics working

### Integration
- [ ] Full stream page working
- [ ] Mobile responsive
- [ ] All systems integrated

### Testing & Deployment
- [ ] Tests passing
- [ ] Deployed to production
- [ ] Monitoring configured
- [ ] Team trained

---

**Phase 1 Estimated Completion**: Week 4 (by February 28, 2025)  
**Next Phase**: Phase 2 - Social & Discovery (March 1, 2025)

See [PHASE_2_SOCIAL_DISCOVERY.md](PHASE_2_SOCIAL_DISCOVERY.md) for Phase 2 details.