Movie Watchlist Backend API

A Node.js/Express backend application for managing movies and user watchlists. Built with PostgreSQL, Prisma ORM, JWT authentication, and comprehensive validation.

Project Overview

This backend API provides a complete authentication and movie management system with user watchlist functionality. Users can register, log in, manage movie collections, and maintain personal watchlists with status tracking.

Tech Stack

• Runtime: Node.js with ES Modules
• Framework: Express.js 5.x
• Database: PostgreSQL with Prisma ORM
• Authentication: JWT (JSON Web Tokens) with bcryptjs password hashing
• Validation: Zod for request validation
• Development: Nodemon for hot reloading
• Additional: Cookie Parser for secure session handling

Project Setup

Prerequisites

• Node.js (v18+)
• PostgreSQL database
• Environment variables configured

Installation

1. Clone/Navigate to the project

   git clone https://github.com/ESE-MONDAY/backend.git
   cd backend

2. Install dependencies

   npm install

3. Configure environment variables Create a .env file in the root directory with:

   DATABASE_URL=postgresql://user:password@localhost:5432/database_name
   JWT_SECRET=your_secret_key
   PORT=5001
   

4. Set up the database

   npx prisma migrate dev

5. Seed initial data (optional)

   npm run seedmovies

6. Start the server

   npm run dev          # Development with hot reload
   npm start            # Production mode

Docker Setup (Alternative)

If you prefer to run the app in Docker, use one of these options.

Build and run the app with Docker

docker build -t movie-watchlist-backend .
docker run -p 5001:5001 --env-file .env movie-watchlist-backend

Use Docker Compose

docker-compose up --build -d

The app will be exposed at http://localhost:5001 inside the container.

If you use Docker with a local .env file, Docker Compose will load environment variables from .env automatically.

The server will run on http://localhost:5001

API Routes

All routes are prefixed with /api/v1

Authentication Routes (/api/v1/auth)

Method	Endpoint	Description	Auth Required
POST	/register	Register a new user	✗
POST	/login	Authenticate user and receive JWT tokens	✗
POST	/refresh-token	Refresh access token using refresh token	✓
POST	/logout	Logout user (invalidate session)	✓

Register/Login Request Body:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Movie Routes (/api/v1/movies)

All movie endpoints require authentication

Method	Endpoint	Description
GET	/	Get all movies with pagination
GET	/:id	Get a specific movie by ID
POST	/	Add a new movie (admin/creator only)
DELETE	/:id	Delete a movie

Add Movie Request Body:

{
  "title": "Movie Title",
  "overview": "Movie description",
  "releaseYear": 2024,
  "genres": ["Drama", "Thriller"],
  "runtime": 120,
  "posterUrl": "https://image.url/poster.jpg"
}

Watchlist Routes (/api/v1/watchlist)

All watchlist endpoints require authentication

Method	Endpoint	Description
GET	/	Get user's watchlist
POST	/	Add movie to watchlist
PUT	/:id	Update watchlist item status
DELETE	/:id	Remove movie from watchlist

Add to Watchlist Request Body:

{
  "movieId": "movie-uuid",
  "status": "watching"  // Options: "watching", "completed", "dropped"
}

Update Watchlist Item Request Body:

{
  "status": "completed",
  "rating": 8.5
}

Database Schema

User

• id (UUID) - Primary key
• name - User's full name
• email (Unique) - User's email address
• password - Hashed password
• createdAt - Account creation timestamp

Movie

• id (UUID) - Primary key
• title (Unique) - Movie title
• overview - Plot summary
• releaseYear - Release year
• genres - Array of genre tags
• runtime - Duration in minutes
• posterUrl - Movie poster image URL
• createdBy - Creator user ID (FK)
• createdAt - Creation timestamp

WatchlistItem

• id (UUID) - Primary key
• userId - User ID (FK)
• movieId - Movie ID (FK)
• status - Watching/Completed/Dropped
• rating - User's rating
• addedAt - Date added to watchlist

AuthTransaction

• id (UUID) - Primary key
• userId - User ID (FK)
• refreshToken - JWT refresh token
• expiresAt - Token expiration timestamp

API Documentation (Swagger/OpenAPI)

This project includes interactive API documentation using Swagger UI. After starting the server, you can access the documentation at:

URL via Nginx: http://localhost:8080/api/docs Direct app URL: http://localhost:5001/api/docs

Features

• Interactive API explorer
• Try out endpoints directly in the browser
• Detailed request/response schemas
• Authentication support with JWT tokens
• Real-time API specifications

Accessing Swagger UI

1. Start the development server: npm run dev
2. Open your browser and navigate to: http://localhost:8080/api/docs
3. You'll see all available endpoints organized by tags (Authentication, Movies, Watchlist)
4. Click on any endpoint to see details and try it out
5. For protected endpoints, click "Authorize" and paste your JWT token

Adding Documentation to New Routes

When adding new endpoints, include JSDoc comments with Swagger annotations:

/**
 * @swagger
 * /api/v1/example:
 *   get:
 *     summary: Brief description
 *     tags:
 *       - Category
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: Success response
 */

Available Scripts

npm run dev          # Start development server with nodemon
npm start            # Start production server
npm run seedmovies   # Seed database with movie data
npm test            # Run tests (not configured yet)

Project Structure

src/
├── server.js                 # Express app setup and entry point
├── config/
│   └── db.js                # Database connection logic
├── controller/
│   ├── authController.js    # Authentication handlers
│   ├── movieController.js   # Movie management handlers
│   └── watchlistController.js # Watchlist handlers
├── middleware/
│   ├── auth-middleware.js   # JWT verification middleware
│   └── validateRequest.js   # Request validation middleware
├── routes/
│   ├── authRoutes.js        # Auth endpoint definitions
│   ├── movieRoutes.js       # Movie endpoint definitions
│   ├── watchlistRoutes.js   # Watchlist endpoint definitions
│   └── v1/
│       └── index.js         # API v1 router aggregator
├── utils/
│   └── generateToken.js     # JWT token generation
└── validators/
    ├── movieValidator.js    # Movie request schemas (Zod)
    └── watchlistValidator.js # Watchlist request schemas (Zod)

prisma/
├── schema.prisma            # Database schema definition
├── seed.js                  # Database seed script
└── migrations/              # Migration history

Features

✅ User Authentication with JWT tokens
✅ Secure password hashing with bcryptjs
✅ Movie database management
✅ Personal watchlist with status tracking
✅ Request validation with Zod
✅ PostgreSQL with Prisma ORM
✅ Graceful server shutdown handling
✅ Cookie-based session management
✅ Error handling and validation middleware

Authentication Flow

1. User registers with email and password
2. Password is hashed and stored in database
3. User logs in with credentials
4. Server returns accessToken (short-lived) and refreshToken (long-lived)
5. Access token used in Authorization header: Bearer <accessToken>
6. When access token expires, use refresh token to obtain new one
7. Tokens are validated via authMiddleware on protected routes

Error Handling

The API returns standard HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (validation error)
• 401 - Unauthorized (missing/invalid token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 500 - Server Error

Development Notes

• API is versioned at /api/v1/
• All protected routes use JWT bearer tokens
• Watchlist items track user preferences and ratings
• Movie titles are unique in the system
• User emails are unique identifiers

Author: Ese Monday
License: ISC