# CoopCredits Setup Guide

This guide will walk you through setting up the complete CoopCredits ecosystem.

## Prerequisites

- Node.js 20+
- Docker & Docker Compose
- Solana CLI (for blockchain development)
- Anchor Framework (for Solana program deployment)

## 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
- `PLEX_CLIENT_ID` & `PLEX_CLIENT_SECRET` - From Plex.tv
- `TAUTULLI_API_KEY` - From Tautulli settings
- `OVERSEER_API_KEY` - From Overseer settings
- `SOLANA_MINT_AUTHORITY_KEYPAIR` - Will be generated in step 3

### 3. Solana Setup

```bash
# Run the Solana setup script
npm run setup:solana

# This will:
# - Install Solana CLI if needed
# - Create a devnet keypair
# - Request airdrop (2 SOL)
# - Output the private key for your .env file
```

Copy the `SOLANA_MINT_AUTHORITY_KEYPAIR` value into your `.env` file.

### 4. Deploy Solana Program

```bash
cd anchor-program

# Build the program
anchor build

# Deploy to devnet
anchor deploy

# Note the Program ID and update .env SOLANA_PROGRAM_ID
```

### 5. Database Setup

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

# Push schema to database (no migrations needed for fresh setup)
cd backend
npx prisma db push

# Generate Prisma client
npx prisma generate
```

### 6. Start Development

```bash
# Start all services
npm run dev

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

### 7. Configure Tautulli Webhook

1. Open Tautulli Settings
2. Go to Notification Agents → Add Agent → Webhook
3. Configure:
   - Webhook URL: `http://your-server:3001/webhooks/tautulli`
   - Webhook Method: POST
   - JSON Payload: See webhook template in Admin Dashboard
4. Enable "Notify on Watched"

### 8. Production Deployment

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

# Deploy (Caddy handles SSL termination)
docker-compose up -d --build
```

**Note:** This setup runs HTTP only on port 80. Place behind Caddy or another reverse proxy for SSL termination.

## Architecture Overview

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User Browser  │────▶│  Next.js (3000) │────▶│  Express (3001) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                         ┌─────────────────┐           │
                         │  PostgreSQL     │◀──────────┘
                         │  (Database)     │
                         └─────────────────┘
                                ▲
                         ┌─────────────────┐
                         │  Solana Devnet  │
                         │  ($COOP Token)  │
                         └─────────────────┘
                                ▲
        ┌───────────────────────┴───────────────────────┐
        │                                               │
┌───────▼───────┐                             ┌────────▼──────┐
│  Tautulli     │                             │   Overseer    │
│ (Watch Events)│                             │  (Requests)   │
└───────────────┘                             └───────────────┘
```

## User Flow

1. **Login**: User authenticates with Plex OAuth
2. **Wallet**: Auto-created Solana wallet (or connect existing)
3. **Watch**: Viewing on Plex → Tautulli triggers webhook
4. **Earn**: Backend validates → Mints $COOP tokens
5. **Spend**: Request content on Overseer → Deducts $COOP

## Admin Features

Access `/admin` with an admin account to:
- View system analytics
- Manage users and grant bonuses
- Configure minting rates
- Pause/resume minting
- Monitor transactions

## Troubleshooting

### Database Connection Issues
```bash
# Reset database
docker-compose down -v
docker-compose up -d postgres
npx prisma migrate dev
```

### Solana Transaction Failures
```bash
# Check balance
solana balance <pubkey>

# Request airdrop
solana airdrop 2 <pubkey>
```

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

## Security Considerations

1. **Private Keys**: 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
5. **Rate Limiting**: Nginx config includes rate limits

## 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`