📡 WatchRadar

WatchRadar is a full-featured, modern web application for tracking movies and TV series. It allows users to manage their watch history, create custom lists, and connect with friends to share their viewing activity.

✨ Core Features

• Comprehensive Tracking: Mark media with statuses like "Watching", "Plan to Watch", "Completed", or "Dropped".
• Detailed Progress: Track progress on a per-episode basis for TV series.
• Rewatch System: Log multiple viewings of your favorite movies and shows.
• TMDB Integration: Discover and search for any movie or TV series via The Movie Database API.
• Social Connectivity:
  • Friend System: Send, accept, and manage friend requests.
  • Activity Feed: See what your friends are watching, rating, and completing in real-time.
  • User Profiles: Public or private user profiles displaying watch stats and recent activity.
  • Commenting: Leave reviews and see comments from friends on media pages.
• Advanced Organization:
  • Custom Lists: Create and manage personalized lists for any purpose (e.g., "Horror Movie Marathon", "Best Sci-Fi of the 90s").
  • Powerful Filtering & Sorting: Easily find what you're looking for in your lists with extensive filter and sort options.
• Personalization & Gamification:
  • In-Depth Stats: View detailed statistics on your watching habits, including total hours watched and genre breakdowns.
  • Achievement System: Unlock achievements based on your viewing milestones.
  • Title Preferences: Choose to display titles in English, Japanese, or their original language.
• Data Portability:
  • Import: Easily import your watch history from MyAnimeList (XML) or Watcharr (JSON).
• Admin Panel: A protected section for administrators to manage users.
• SEO & Social Sharing: Server-Side Rendering (SSR) for meta tags ensures that links to media and user profiles look great when shared on social media.

🚀 Technology Stack

The project is structured as a monorepo with a separate client and server.

Frontend	Backend & Database
Framework: React 19	Framework: Express.js
Build Tool: Vite	Database ORM: Knex.js
Styling: Tailwind CSS	Database: SQLite3
Routing: React Router	Authentication: JWT (JSON Web Tokens) & bcrypt
Icons: Lucide React	API Communication: RESTful API
HTTP Client: Axios	Environment: Node.js
Linting: ESLint	Deployment: Docker-ready setup

📂 Project Structure

/
├── client/         # React Frontend SPA
├── server/         # Node.js/Express Backend API
├── database/       # (Created on host) For persistent SQLite DB
├── docker-compose.yml
├── Dockerfile
├── docker-entrypoint.sh
└── .env            # (Created by user) Environment variables

🐳 Production Deployment with Docker

This application is containerized for easy and consistent production deployment.

Prerequisites

• Docker
• Docker Compose

Setup Instructions

1. Clone the Repository

   git clone https://github.com/eidenz/watchradar.git
   cd watchradar

2. Create Environment File Create a .env file in the root of the project by copying the example file from the server directory.

   cp server/.env.example .env

   Now, edit the .env file and fill in your secrets. The PORT must be 5001 to match the Docker configuration.

   # .env
   PORT=5001
   JWT_SECRET=your_super_secret_jwt_key_here
   TMDB_API_KEY=your_tmdb_api_v3_key_here

3. Create Database Directory The Docker volume needs a directory on the host machine to store the persistent SQLite database.

   mkdir database

4. Build and Run the Container Use Docker Compose to build the image and start the container in the background.

   docker-compose up --build -d

   • --build: Forces a rebuild of the image if the Dockerfile or source code has changed.
   • -d: Runs the container in detached mode.

The application will now be running and accessible at http://localhost:8080.

Managing the Container

• View logs: docker-compose logs -f
• Stop the container: docker-compose down
• Restart the container: docker-compose restart

💻 Local Development Setup

Follow these instructions to get the project running on your local machine for development without Docker.

Prerequisites

• Node.js (v18 or newer recommended)
• npm (comes with Node.js)

1. Backend Setup

First, set up and run the server.

# Navigate to the server directory
cd server

# Install dependencies
npm install

# Create the environment file
cp ../.env.example .env

Next, open the newly created server/.env file and fill in the required variables. You will need a TMDB API Key.

# server/.env file
PORT=5001
JWT_SECRET=your_super_secret_jwt_key_here
TMDB_API_KEY=your_tmdb_api_v3_key_here

Finally, run the database migrations and start the server.

# Apply the latest database schema
npm run migrate

# Start the development server (with nodemon)
npm run dev

The backend API will now be running on http://localhost:5001.

2. Frontend Setup

In a new terminal, set up and run the client.

# Navigate to the client directory from the root
cd client

# Install dependencies
npm install

# Start the Vite development server
npm run dev

The frontend application will now be running on http://localhost:5173. It is configured to proxy API requests from /api to your backend server running on port 5001.

You can now access the application in your browser!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.