CoopCredits ($COOP) — Hoboken Chicken Media Rewards

A jokey barnyard-themed rewards system for the Hoboken Chicken family and friends. Watch stuff on Plex, earn $COOP credits, request new media through Overseer. Buy extra credits via Ko-fi when the silo runs low.

Theme: Everything is chickens, eggs, coops, and corn. Comic Sans / Chalkboard font, thick borders, earthy palette.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           coop.hobokenchicken.com                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                      │
│  │   Next.js    │  │   Express    │  │  PostgreSQL  │                      │
│  │   Frontend   │◄─┤    API       │◄─┤   Database   │                      │
│  │   (3000)     │  │   (3002)     │  │   (5432)     │                      │
│  └──────────────┘  └──────────────┘  └──────────────┘                      │
│         ▲                 ▲                    ▲                           │
│         │                 │                    │                           │
│    Plex OAuth      Tautulli Webhooks     Ko-fi Webhooks                    │
│         │                 │                    │                           │
│         ▼                 ▼                    ▼                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                     │
│  │ Plex Server  │  │  Tautulli    │  │   Ko-fi      │                     │
│  │172.20.1.220  │  │172.20.1.255  │  │  (Payments)  │                     │
│  └──────────────┘  └──────────────┘  └──────────────┘                     │
│                                                                              │
│  ┌──────────────┐                                                           │
│  │  Overseer    │  (Requests & disk space for dynamic pricing)              │
│  │172.20.1.225  │                                                           │
│  └──────────────┘                                                           │
└─────────────────────────────────────────────────────────────────────────────┘

Key Features

• Plex OAuth Login — No passwords, just Plex auth
• Watch-to-Earn — Tautulli webhooks credit $COOP for watched content (30-day backfill on signup)
• Request-to-Spend — Request movies/shows through Overseer, pay $COOP
• Dynamic Pricing — Request costs rise as disk space fills (scarcity multiplier)
• TV Episode Tiers — Long-running shows cost more per episode count
• Ko-fi Purchases — Buy $COOP with real money via Ko-fi store items
• Admin Dashboard — Manage users, view donations, sync request statuses, adjust barn rules
• Barnyard Theme — "Peck for Feed", "Join the Flock", thick borders, earthy palette

Quick Start

# 1. Clone
git clone <repository> coop-credits
cd coop-credits

# 2. Install dependencies
npm run install:all

# 3. Configure environment
cp .env.example .env
# Edit .env with your API keys (Plex, Tautulli, Overseer, Ko-fi)

# 4. Start services
docker-compose up -d --build

# 5. Initialize database (first time only)
docker exec coop-backend npx prisma db push --accept-data-loss

# 6. Configure Caddy (see docs/CADDY-CONFIG.md)

Project Structure

coop-credits/
├── backend/                 # Express API server (port 3002)
│   ├── src/
│   │   ├── routes/          # API routes (auth, users, wallet, overseer, admin, webhooks)
│   │   ├── services/        # Tautulli backfill, socket handlers
│   │   ├── middleware/      # Auth, rate limiting, error handling
│   │   └── utils/           # Prisma client
│   └── prisma/
│       └── schema.prisma    # DB schema (User, Transaction, WatchEvent, ContentRequest, KofiPayment, etc.)
├── frontend/                # Next.js 16 dashboard (port 3000)
│   └── src/
│       ├── app/
│       │   ├── page.tsx              # Landing page ("Enter the Coop")
│       │   ├── login/page.tsx        # Plex OAuth login
│       │   ├── dashboard/page.tsx    # User dashboard
│       │   ├── admin/page.tsx        # Admin panel
│       │   └── dashboard/components/ # WatchHistory, RequestHistory, SearchRequestModal, BuyCreditsModal, etc.
│       └── lib/
│           ├── api.ts       # API client
│           ├── store.ts     # Zustand auth store
│           └── socket.ts    # Socket.io connection
├── docs/                    # Documentation
│   ├── CADDY-CONFIG.md     # Reverse proxy setup
│   ├── INFRASTRUCTURE.md   # Network architecture
│   ├── SETUP-INFRASTRUCTURE.md
│   └── TROUBLESHOOTING.md
├── docker-compose.yml       # Docker orchestration
└── .env.example             # Environment template

User Flow

1. Login → Visit coop.hobokenchicken.com, click "Join the Flock", authenticate with Plex
2. Auto-Backfill → First login triggers 30-day Tautulli history import (DB-only credits)
3. Watch → Viewing on Plex → Tautulli webhook → $COOP credited to DB balance
4. Earn → Real-time balance updates via Socket.io on dashboard
5. Spend → "Peck for Feed" → Search → Request content → $COOP deducted immediately
6. Buy More → "Buy Feed" → Ko-fi store → Credits auto-delivered via webhook

Admin Features

Access /admin with an admin account:

• The Flock — User list with search, reward bonuses, manual backfill, promote/demote admins
• Barn Rules — Edit credits per minute, min watch %/minutes, movie/TV costs
• Donations — View all incoming Ko-fi payments with status (CREDITED / UNCLAIMED)
• The Feed Queue — All content requests across users, manual Overseer sync button
• Egg Stats — Analytics cards: flock size, total $COOP, total requests, pending count

Environment Variables

See .env.example for full configuration. Key vars:

# Database
DATABASE_URL="postgresql://coop:password@localhost:5432/coop_credits?schema=public"

# Server
PORT=3002
API_URL=https://coop.hobokenchicken.com

# JWT (generate: openssl rand -hex 32)
JWT_SECRET="..."

# Plex OAuth
PLEX_CLIENT_ID="..."
PLEX_CLIENT_SECRET="..."
PLEX_REDIRECT_URI=https://coop.hobokenchicken.com/auth/callback

# Tautulli (host network mode required)
TAUTULLI_URL=http://172.20.1.255:8181
TAUTULLI_API_KEY="..."

# Overseer (host network mode required)
OVERSEER_URL=http://172.20.1.225:5055
OVERSEER_API_KEY="..."

# Ko-fi
KOFI_VERIFICATION_TOKEN="..."

# Security
ENCRYPTION_KEY="..."  # openssl rand -base64 32

Dynamic Pricing

Request costs are adjusted by disk scarcity:

• Multiplier = 1 + (usedPercent × 2)
• At 0% disk used → 1× base cost
• At 50% disk used → 2× base cost
• At 90% disk used → 2.8× base cost

TV shows also have episode tier multipliers on top of scarcity:

• ≤50 episodes → base
• 51-100 → 1.3×
• 101-200 → 1.6×
• 201-400 → 2.0×
• 400+ → 2.5×

Theme

• Primary: Terracotta (#C06F4A)
• Secondary: Duck Egg Blue (#D4E4E0)
• Accent: Wheat (#E8D5B5)
• Muted: Feather Grey (#C4B5AA)
• Font: Comic Sans MS / Chalkboard SE (fallback system-ui)
• Style: Thick 4px borders, hard black box shadows, rounded-3xl corners

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui, Zustand
Backend	Express.js, TypeScript, Prisma ORM, Socket.io
Database	PostgreSQL 16
Cache	Redis 7 (sessions, Socket.io adapter)
Auth	Plex OAuth 2.0 + JWT
Payments	Ko-fi webhooks
Deployment	Docker Compose, Caddy reverse proxy

License

Private — Hoboken Chicken family use only.