128 lines
3.9 KiB
Markdown
128 lines
3.9 KiB
Markdown
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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
|