setup features

README.md

@@ -3,34 +3,125 @@
 A web app for tracking predictions and points in TV/movie challenges with friends.
 
 ## Features
-- Register/login with email and password
-- Create and join challenges for shows/movies
-- Make and approve predictions
-- Mobile-first, modern UI
+- 🔐 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 (Vite)
-- Backend: Node.js (Express)
-- Database: PostgreSQL
-- Auth: JWT (email/password)
-- Dockerized, self-hosted
+- **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)
 
-### Setup
-1. Copy `.env.example` to `.env` and fill in secrets.
-2. Build and start all services:
-   ```sh
+### 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
    ```
-3. Access the frontend at http://localhost:5173
-4. API runs at http://localhost:4000
 
-## Deployment
-- See `prod-compose.yml` for production deployment.
+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