# CoopCredits Setup Guide

This guide walks you through setting up the complete CoopCredits ecosystem.

## Prerequisites

- Node.js 20+
- Docker & Docker Compose
- Access to Plex, Tautulli, and Overseer instances
- Domain name (for production)

## Quick Start

### 1. Clone and Install

```bash
git clone <repository>
cd coop-credits
npm run install:all
```

### 2. Environment Configuration

```bash
# Copy example environment file
cp .env.example .env

# Edit with your values
nano .env
```

Required environment variables:
- `DATABASE_URL` - PostgreSQL connection string
- `JWT_SECRET` - Random string for JWT signing (openssl rand -hex 32)
- `PLEX_CLIENT_ID` & `PLEX_CLIENT_SECRET` - From Plex.tv
- `TAUTULLI_API_KEY` - From Tautulli settings
- `OVERSEER_API_KEY` - From Overseer settings
- `ENCRYPTION_KEY` - For encrypting session data (openssl rand -base64 32)
- `KOFI_VERIFICATION_TOKEN` - From Ko-fi settings (optional)

### 3. Database Setup

```bash
# Start PostgreSQL and Redis
docker-compose up -d postgres redis

# Push schema to database
cd backend
npx prisma db push

# Generate Prisma client
npx prisma generate
```

### 4. Start Development

```bash
# Start all services
npm run dev

# Or individually:
npm run dev:backend   # API on port 3002
npm run dev:frontend  # Next.js on port 3000
```

### 5. Production Deployment

```bash
# Create public directory (required for build)
mkdir -p frontend/public

# Deploy
docker-compose up -d --build
```

**Note:** This runs HTTP internally. Place behind Caddy or another reverse proxy for SSL termination. Backend runs on port 3002.

## Architecture Overview

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User Browser  │────▶│  Next.js (3000) │────▶│  Express (3002) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                         ┌─────────────────┐           │
                         │  PostgreSQL     │◀──────────┘
                         │  (Database)     │
                         └─────────────────┘
                                ▲
                         ┌─────────────────┐
                         │   Ko-fi         │
                         │  (Purchases)    │
                         └─────────────────┘
                                ▲
        ┌───────────────────────┴───────────────────────┐
        │                                               │
┌───────▼───────┐                             ┌────────▼──────┐
│  Tautulli     │                             │   Overseer    │
│ (Watch Events)│                             │  (Requests)   │
└───────────────┘                             └───────────────┘
```

## User Flow

1. **Login**: User authenticates with Plex OAuth
2. **Backfill**: First login triggers 30-day Tautulli history import
3. **Watch**: Viewing on Plex → Tautulli triggers webhook → $COOP credited to DB
4. **Earn**: Real-time balance updates on dashboard via Socket.io
5. **Spend**: Request content on Overseer → $COOP deducted from DB balance
6. **Buy**: Ko-fi purchase → Webhook → $COOP added to DB balance

## Admin Features

Access `/admin` with an admin account to:
- **The Flock** — User list with search, bonuses, backfill, promote/demote
- **Barn Rules** — Edit credits per minute, watch thresholds, request costs
- **Donations** — View Ko-fi payment history
- **The Feed Queue** — All content requests with Overseer sync button
- **Egg Stats** — Analytics cards (users, total credits, requests, pending)

## Troubleshooting

### Database Connection Issues
```bash
# Reset database
docker-compose down -v
docker-compose up -d postgres
cd backend && npx prisma db push
```

### Tautulli Webhook Not Working
1. Check webhook URL is accessible
2. Verify `TAUTULLI_WEBHOOK_SECRET` matches (optional)
3. Check backend logs: `docker-compose logs backend`

### Request Stuck on PENDING
1. Check Overseer webhook is configured
2. Use admin dashboard **The Feed Queue** → **SYNC** button
3. Or use dashboard **Requests** tab → refresh button

## Security Considerations

1. **Never commit `.env` files**
2. **JWT Secret**: Use a strong random string (32+ chars)
3. **Encryption Key**: Use `openssl rand -base64 32`
4. **SSL**: Always use HTTPS in production (Caddy handles this)
5. **Rate Limiting**: 1000 req/15min per IP

## Support

For issues or questions:
1. Check logs: `docker-compose logs -f`
2. Review environment variables
3. Verify all services are running: `docker-compose ps`
4. Check `docs/TROUBLESHOOTING.md`