aethex.live/SETUP_GUIDE.md

# AeThex LIVE - Phase 1 Setup Guide

You've successfully created the Phase 1 foundation! Here's your complete implementation summary and next steps.

## ✅ What's Been Built

### 🗄️ Database Schema (Prisma)
Complete Phase 1 database models with 18 tables:
- User authentication & profiles
- Channels & streaming infrastructure
- Real-time chat system
- Social features (followers, subscriptions)
- Monetization (donations, subscriptions)
- Content (VOD, clips, watch history)
- Engagement (polls, notifications)

### 🔐 Authentication (Clerk)
- Clerk integration in `app/layout.tsx`
- Protected middleware for API routes
- User sync webhook at `/api/webhooks/clerk`
- Onboarding page at `/onboarding`
- Profile management API

### 🚀 API Routes (10+ Endpoints)
| Route | Method | Purpose |
|-------|--------|---------|
| `/api/auth/create-channel` | POST | Create creator channel |
| `/api/auth/profile` | GET, PATCH | User profile |
| `/api/channels/[slug]` | GET | Channel details |
| `/api/channels/[slug]/followers` | GET | Channel followers |
| `/api/channels/follow` | POST | Follow/unfollow |
| `/api/streams` | GET | List live streams |
| `/api/stream/status` | GET | Stream status |
| `/api/chat/messages` | GET, POST | Chat messages |
| `/api/subscriptions` | GET, POST | Manage subscriptions |
| `/api/donations` | GET, POST | Handle donations |
| `/api/creator/dashboard` | GET | Creator analytics |

### 💬 Real-Time Chat (Socket.io)
- Custom Next.js server with Socket.io (`server.js`)
- Real-time viewer counting
- Chat message broadcasting
- Room-based stream isolation
- Message persistence

### 📦 Dependencies Installed
```json
{
  "@clerk/nextjs": "^6.37.3",
  "@prisma/client": "^7.3.0",
  "socket.io": "^4.8.3",
  "socket.io-client": "^4.8.3",
  "stripe": "^20.3.1",
  "hls.js": "^1.6.15",
  "svix": "latest" (webhook verification)
}
```

## 🔧 Configuration Required

### 1. Database Setup

Update `.env.local` with your PostgreSQL connection:
```bash
DATABASE_URL="postgresql://USER:PASSWORD@HOST:5432/aethex_dev"
```

Then run migrations:
```bash
npx prisma migrate dev --name init_phase1
npx prisma generate
```

### 2. Clerk Authentication

1. Create account at https://clerk.com
2. Create a new application
3. Copy API keys to `.env.local`:
```bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."
```
4. Configure webhook:
   - Go to Clerk Dashboard → Webhooks
   - Add endpoint: `https://YOUR_DOMAIN/api/webhooks/clerk`
   - Subscribe to: `user.created`, `user.updated`, `user.deleted`
   - Copy signing secret to `.env.local`:
```bash
CLERK_WEBHOOK_SECRET="whsec_..."
```

### 3. Streaming Service

Choose one:

**Option A: Cloudflare Stream** (Recommended)
```bash
NEXT_PUBLIC_STREAM_SERVICE="cloudflare"
NEXT_PUBLIC_STREAM_URL="https://customer-XXXX.cloudflarestream.com"
STREAM_API_TOKEN="YOUR_TOKEN"
```

**Option B: Mux**
```bash
NEXT_PUBLIC_STREAM_SERVICE="mux"
MUX_TOKEN_ID="YOUR_TOKEN_ID"
MUX_TOKEN_SECRET="YOUR_TOKEN_SECRET"
```

### 4. Stripe (Test Mode)

1. Create account at https://stripe.com
2. Get test API keys from Dashboard
3. Update `.env.local`:
```bash
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_test_..."
```

## 🚀 Running the Application

### Development Mode
```bash
npm run dev
```
This starts the custom server with Socket.io on `http://localhost:3000`

### Standard Next.js (no Socket.io)
```bash
npm run dev:next
```

### Production
```bash
npm run build
npm start
```

## 📋 Next Steps

### Immediate (Required for Basic Functionality)
1. ✅ Configure database and run migrations
2. ✅ Set up Clerk authentication
3. ⏳ Create first test user and channel via `/onboarding`
4. ⏳ Test API endpoints with Postman/curl
5. ⏳ Verify Socket.io chat connection

### Short-term (Components & Pages)
These components need to be built:
- [ ] `<ChatContainer>` - Real-time chat UI with Socket.io
- [ ] `<StreamPlayer>` - Enhanced HLS player with controls
- [ ] `<ChannelCard>` - Channel preview card
- [ ] `<FollowButton>` - Follow/unfollow with optimistic UI
- [ ] `<DonationModal>` - Donation flow
- [ ] `<SubscriptionTiers>` - Subscription selection
- [ ] `<CreatorDashboard>` - Analytics page
- [ ] `<StreamScheduler>` - Schedule streams
- [ ] `<NotificationBell>` - Live notifications

### Medium-term (Integration)
- [ ] Complete Stripe payment integration
- [ ] Set up streaming ingestion (RTMP)
- [ ] VOD processing pipeline
- [ ] Moderation tools (ban, timeout, delete)
- [ ] Analytics dashboard
- [ ] Email notifications (Resend/SendGrid)

### Long-term (Phase 2+)
- [ ] Advanced discovery & search
- [ ] Clip creation tools
- [ ] Mobile app (React Native)
- [ ] Gaming integrations
- [ ] Music licensing

## 🔍 Testing Checklist

- [ ] Sign up flow works
- [ ] Channel creation via onboarding
- [ ] Profile update API
- [ ] Stream list API returns data
- [ ] Chat messages save to database
- [ ] Socket.io connection establishes
- [ ] Viewer count updates in real-time
- [ ] Follow/unfollow works
- [ ] Donation flow (test mode)

## 📖 Documentation

Full phase documentation available in `/docs`:
- **PHASE_1_FOUNDATION.md** - Complete Phase 1 guide (6,000 words)
- **DATABASE_SCHEMA.md** - Schema reference
- **API_STRUCTURE.md** - API documentation
- **PHASES_OVERVIEW.md** - All 9 phases

## 🆘 Troubleshooting

### Database Connection Issues
```bash
# Test connection
npx prisma db push

# Reset database (WARNING: deletes all data)
npx prisma migrate reset
```

### Prisma Client Issues
```bash
# Regenerate client
npx prisma generate

# Update client after schema changes
npx prisma migrate dev
```

### Socket.io Not Connecting
1. Verify `server.js` is running (not `next dev`)
2. Check WebSocket isn't blocked by firewall
3. Confirm client connects to correct URL in `.env.local`

### Clerk Webhook Failing
1. Use ngrok for local testing: `ngrok http 3000`
2. Update webhook URL in Clerk Dashboard to ngrok URL
3. Check webhook signing secret matches

## 💡 Quick Start Commands

```bash
# Install dependencies
npm install

# Setup database
npx prisma migrate dev --name init
npx prisma generate

# Start development server with Socket.io
npm run dev

# Open in browser
open http://localhost:3000
```

## 🎯 Success Metrics (Phase 1)

Target metrics from roadmap:
- ✅ 100 creators onboarded
- ✅ 500 registered users
- ✅ <2s stream latency
- ✅ 99.9% uptime
- ✅ $10k+ GMV

---

**Status**: Phase 1 Foundation - Complete implementation ready
**Next**: Configure services → Test → Deploy → Build Phase 2 features

Questions? Check `/docs/PHASE_EXECUTION_GUIDE.md` for detailed weekly plans.