LobotomyLabs/coop
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation to reflect current project state

Browse Source
This commit is contained in:
Dustin Newkirk
2026-04-23 14:35:08 -04:00
parent 8b31045dcf
commit 3029ce7053
9 changed files with 566 additions and 639 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+152 -49
View File
@@ -1,89 +1,192 @@
# CoopCoins: Our Family Media Rewards
# CoopCredits ($COOP) — Hoboken Chicken Media Rewards
Welcome to our private media rewards system for the Hoboken Chicken family and friends! It's powered by Solana and integrates with our Plex, Tautulli, and Overseer setup. Earn CoopCoins ($COOP) for enjoying media, and use them to request new content!
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.
## System Architecture
> **Theme:** Everything is chickens, eggs, coops, and corn. Comic Sans / Chalkboard font, thick borders, earthy palette.
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ coop.hobokenchicken.com │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Next.js │ │ Express │ │ PostgreSQL │ │ Solana Devnet │ │
│ │ Frontend │◄─┤ API │◄─┤ Database │◄─┤ $COOP SPL │ │
│ │ │ │ │ │ │ │ Token │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └─────────────────┘ │
│ ▲ ▲ │
│ │ │ │
│ Plex OAuth Tautulli Webhooks │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Plex Server │ │ Tautulli │ │ Overseer │ │
│ │ (Content) │ │ (Analytics) │ │ (Requests) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 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
```bash
# 1. Clone and install dependencies
# 1. Clone
git clone <repository> coop-credits
cd coop-credits
npm install
# 2. Set up environment
# 2. Install dependencies
npm run install:all
# 3. Configure environment
cp .env.example .env
# Edit .env with your values
# 3. Create public directory
mkdir -p frontend/public
# 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-compose exec backend npx prisma db push
docker exec coop-backend npx prisma db push --accept-data-loss
# 6. Configure Caddy (see docs/CADDY-CONFIG.md)
# Services expose ports 3000 (frontend) and 3001 (backend) on localhost
```
See `docs/CADDY-CONFIG.md` for reverse proxy setup.
## Project Structure
```
coop-credits/
├── anchor-program/ # Solana Anchor program for $COOP token
├── backend/ # Express API server
├── frontend/ # Next.js dashboard
├── shared/ # Shared types and utilities
├── 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
├── docker-compose.yml # Docker orchestration (no nginx)
└── .env.example # Environment template
│ ├── CADDY-CONFIG.md # Reverse proxy setup
│ ├── INFRASTRUCTURE.md # Network architecture
│ ├── SETUP-INFRASTRUCTURE.md
│ └── TROUBLESHOOTING.md
├── docker-compose.yml # Docker orchestration
└── .env.example # Environment template
```
**Note:** No internal reverse proxy. Use Caddy/Nginx/Traefik externally.
## User Flow
1. **Login** → User visits coop.hobokenchicken.com, authenticates with Plex
2. **Wallet** → Auto-created Solana wallet or connect existing
3. **Watch** → Viewing on Plex → Tautulli triggers → $COOP minted
4. **Earn** → Real-time balance updates on dashboard
5. **Spend** → Request content on Overseer → $COOP deducted
6. **History** → Full transaction history visible on dashboard
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
- System overview and analytics
- User management and balance adjustments
- Minting rate controls
- Spending controls and promotions
- Emergency pause and recovery
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 `backend/.env.example` and `frontend/.env.local.example` for full configuration.
See `.env.example` for full configuration. Key vars:
```env
# 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.