whats-the-point/README.md

What's The Point

A web app for tracking predictions and points in TV/movie challenges with friends.

Features

• 🔐 Register/login with email and password (JWT authentication)
• 🎬 Create challenges for shows/movies with TMDB integration
• 📝 Make and validate predictions with friends
• 🏆 Leaderboards (per-challenge and global)
• 👥 Friend system for easy invitations
• 📱 Mobile-first, modern dark UI

Tech Stack

• Frontend: React 18, React Router, Vite
• Backend: Node.js, Express
• Database: MariaDB
• Auth: JWT with bcrypt
• APIs: The Movie Database (TMDB) with caching
• Deployment: Docker, self-hosted via Gitea + Portainer

Getting Started

Prerequisites

• Docker & Docker Compose
• TMDB API Key (free from https://www.themoviedb.org/settings/api)

Local Development

1. Copy environment file:

   cp backend/.env.example backend/.env
   

2. Add your TMDB API key to backend/.env:

   TMDB_API_KEY=your_actual_key_here
   

3. Build and start all services:

   docker compose up --build
   

4. Access the app:

   • Frontend/App: http://localhost:4000
   • Database: localhost:3306

The database will auto-initialize with the required schema on first run.

Production Deployment

1. Update prod-compose.yml with your environment variables:

   • Set a strong JWT_SECRET
   • Set a strong DB_PASSWORD
   • Add your TMDB_API_KEY

2. The Gitea workflow (.gitea/workflows/rebuild-prod.yaml) will:

   • Build the Docker image
   • Push to your registry
   • Deploy via Portainer API

3. Environment variables for Gitea secrets:

   • PROD_ENV: Base64-encoded .env file with production values
   • PORTAINER_TOKEN: Your Portainer API token

How It Works

User Flow

1. Register/Login - Create an account or sign in
2. Create Challenge - Search for a TV show or movie via TMDB
3. Invite Friends - Add participants by username/email
4. Make Predictions - Submit your predictions about the show
5. Validate Predictions - Approve or invalidate others' predictions (not your own)
6. Track Points - View leaderboards and profiles

Key Features

• TMDB Integration: Search shows/movies with autocomplete, cached for 7 days
• Friend System: Dedicated friends page + auto-friends from challenge participation
• Leaderboards: Per-challenge and global rankings
• Profile Stats: Total points, pending predictions, challenges created/joined
• Responsive Design: Mobile-first with dark theme

API Endpoints

Auth

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• GET /api/auth/me - Get current user

Challenges

• GET /api/challenges - List user's challenges
• GET /api/challenges/:id - Get challenge details
• POST /api/challenges - Create new challenge
• POST /api/challenges/:id/invite - Invite users
• POST /api/challenges/:id/respond - Accept/reject invitation

Predictions

• GET /api/predictions/challenge/:id - List predictions
• POST /api/predictions - Create prediction
• POST /api/predictions/:id/validate - Validate/invalidate

Friends

• GET /api/friends - List friends
• GET /api/friends/search - Search users
• POST /api/friends/request - Send friend request
• POST /api/friends/respond - Accept/reject request
• GET /api/friends/requests - Pending requests

Leaderboard

• GET /api/leaderboard/challenge/:id - Challenge leaderboard
• GET /api/leaderboard/global - Global leaderboard
• GET /api/leaderboard/profile/:id? - User profile stats

TMDB

• GET /api/tmdb/search?q=query - Search shows/movies

Database Schema

• users - User accounts
• challenges - TV/movie challenges
• challenge_participants - Challenge memberships
• predictions - User predictions
• friendships - Friend relationships
• tmdb_cache - Cached TMDB API responses

License

MIT