🎬 Movie Recommendation System with TensorFlow.js & pgvector

A production-inspired movie recommendation platform built with Node.js, TensorFlow.js, PostgreSQL, and pgvector.

This project demonstrates how Machine Learning can be integrated into a modern backend architecture to deliver personalized movie recommendations for both:

• New users using profile-based prediction
• Existing users using learned embedding similarity search

The system combines:

• Neural network training with TensorFlow.js
• Feature engineering pipelines
• Vector embeddings
• Vector similarity search with pgvector
• REST APIs with Express.js
• Interactive frontend visualization

---

📌 Project Overview

This application implements a hybrid recommendation architecture composed of two complementary recommendation strategies:

1. New User Recommendations (Cold Start Problem)

For users without historical interactions, the system predicts movie ratings using:

• User demographic information
• Movie metadata
• Engineered numerical features
• A trained TensorFlow.js neural network

The model estimates which movies the user is likely to enjoy even before they rate any content.

---

2. Existing User Recommendations (Collaborative Filtering)

For users with historical ratings, the system:

• Learns dense vector embeddings for users and movies
• Stores embeddings in PostgreSQL using pgvector
• Uses vector similarity search to find the most relevant movies
• Excludes already watched/rated movies

This creates a scalable recommendation pipeline similar to real-world ML recommendation systems.

---

🧠 Machine Learning Architecture

Neural Network Recommendation Model

The training pipeline uses TensorFlow.js with a dense neural network architecture:

• Dense Layers
• Batch Normalization
• Dropout Regularization
• Adam Optimizer
• Early Stopping

Model Characteristics

Component	Description
Framework	TensorFlow.js (Node.js)
Task	Regression
Loss Function	Mean Squared Error
Optimizer	Adam
Validation	Validation Split + Early Stopping
Output	Predicted Movie Rating

---

Embedding-Based Recommendation Engine

The project also trains embedding vectors for:

• Users
• Movies

Those embeddings are persisted in PostgreSQL using the pgvector extension.

Benefits

• Fast similarity search
• Scalable recommendation retrieval
• Collaborative filtering behavior
• Real-world vector database integration

---

⚙️ Tech Stack

Backend

• Node.js
• Express.js
• TensorFlow.js
• PostgreSQL
• pgvector
• JavaScript (ES Modules)

Frontend

• HTML
• CSS
• Vanilla JavaScript

Machine Learning

• TensorFlow.js
• Feature Engineering
• Embedding Learning
• Neural Networks
• Vector Similarity Search

Infrastructure

• Docker Compose
• PostgreSQL Container

---

✨ Features

Recommendation Features

• Personalized movie recommendations
• Cold-start recommendation pipeline
• Existing-user collaborative filtering
• Vector similarity recommendations
• Exclusion of already-rated movies

Machine Learning Features

• TensorFlow.js neural network training
• User/movie embeddings
• Feature normalization
• Feature engineering pipeline
• Batch normalization
• Dropout regularization
• Early stopping
• Embedding persistence

Backend Features

• RESTful API architecture
• Modular service layer
• Recommendation caching structure
• Database initialization scripts
• Dataset loading utilities
• Vector database integration

Frontend Features

• Interactive recommendation UI
• Existing/new user modes
• Real-time recommendation visualization
• One-click environment setup

---

🗂️ Project Structure

movies-recommender/
│
├── backend/
│   ├── src/
│   │   ├── db/
│   │   │   ├── initDb.js
│   │   │   └── postgres.js
│   │   │
│   │   ├── routes/
│   │   │   ├── recommendations.js
│   │   │   ├── trainModel.js
│   │   │   ├── seedDb.js
│   │   │   └── users.js
│   │   │
│   │   ├── services/
│   │   │   ├── trainingService.js
│   │   │   ├── recommendationService.js
│   │   │   ├── existingUserRecommendationService.js
│   │   │   ├── vectorDBService.js
│   │   │   └── modelPersistenceService.js
│   │   │
│   │   ├── utils/
│   │   │   ├── datasetLoader.js
│   │   │   ├── datasetJoiner.js
│   │   │   └── featureEngineering.js
│   │   │
│   │   └── server.js
│   │
│   ├── package.json
│   └── .env
│
├── frontend/
│   ├── index.html
│   ├── app.js
│   └── style.css
│
├── db/
│   └── db-init.sql
│
├── docker-compose.yml
└── README.md

---

🚀 Running the Project Locally

Prerequisites

Before running the project, make sure you have:

• Node.js 18+
• Docker Desktop
• npm

---

1️⃣ Start PostgreSQL + pgvector

Run the database container:

docker compose up -d

This starts PostgreSQL with the pgvector extension enabled.

Default database configuration:

Variable	Value
Database	movies
User	postgres
Password	postgres
Port	5432

---

2️⃣ Install Backend Dependencies

Navigate to the backend folder:

cd backend

Install dependencies:

npm install

---

3️⃣ Configure Environment Variables

The project already includes a default .env file:

PORT=3000

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=movies

Update values if your local environment differs.

---

4️⃣ Start the Backend Server

Run the development server:

npm run dev

Backend API:

http://localhost:3000

---

5️⃣ Run the Frontend

Open the frontend directly in your browser:

frontend/index.html

Or use a lightweight local server extension such as:

• VSCode Live Server
• Python HTTP Server
• Any static file server

---

6️⃣ Seed the Database

Populate the database with movies, users, and ratings:

POST /seed-db

Example using curl:

curl -X POST http://localhost:3000/seed-db

---

7️⃣ Train the Recommendation Models

Train both:

• Neural network recommendation model
• Embedding generation pipeline

POST /train-model

Example:

curl -X POST http://localhost:3000/train-model

This step:

• Trains the TensorFlow.js model
• Generates user embeddings
• Generates movie embeddings
• Persists vectors to PostgreSQL

---

📡 API Endpoints

Train Recommendation Models

POST /train-model

Triggers:

• Neural network training
• Embedding generation
• Vector persistence

---

Seed Database

POST /seed-db

Seeds:

• Users
• Movies
• Ratings

---

Get Recommendations for a New User

POST /recommendations

Request Body

{
  "age": 25,
  "gender": "M",
  "occupation": "engineer"
}

---

Get Recommendations for Existing User

GET /recommendations/:userId

Example:

GET /recommendations/10

---

List Available Users

GET /users

---

🔬 ML Pipeline Details

Feature Engineering

The system performs feature engineering to transform raw data into numerical tensors used by the neural network.

Examples include:

• Rating normalization
• User demographic encoding
• Movie statistics aggregation
• Numerical scaling
• Feature vector construction

---

Training Flow

Dataset Loading
        ↓
Feature Engineering
        ↓
Tensor Conversion
        ↓
Model Training
        ↓
Validation
        ↓
Embedding Generation
        ↓
Vector Persistence (pgvector)
        ↓
Recommendation Serving

---

🧱 Architectural Highlights

Modular Service Architecture

The backend is organized into:

• Routes
• Services
• Utilities
• Database Layer

This separation improves:

• Scalability
• Maintainability
• Testability
• Extensibility

---

Vector Database Integration

The project uses pgvector to:

• Persist embeddings
• Execute cosine similarity search
• Retrieve semantically similar movies

This demonstrates modern AI infrastructure patterns increasingly used in:

• Recommendation systems
• Retrieval systems
• Generative AI applications
• Semantic search platforms

---

📈 Portfolio Highlights

This project demonstrates practical experience with:

Software Engineering

• Backend API architecture
• Modular service design
• Database integration
• Docker-based local infrastructure
• RESTful APIs

Machine Learning Engineering

• TensorFlow.js training pipelines
• Feature engineering
• Neural network design
• Embedding systems
• Recommendation systems
• Vector databases

AI Infrastructure

• pgvector integration
• Similarity search
• Embedding persistence
• ML inference pipelines

---

🔮 Future Improvements

Potential next steps for the platform:

• Model persistence to disk
• Automated retraining pipeline
• GPU acceleration
• Top-K ANN indexing
• Hybrid recommendation scoring
• User authentication
• Streaming recommendations
• Kubernetes deployment
• CI/CD integration
• Monitoring & observability

---

📷 Suggested Portfolio Screenshots

For portfolio presentation, consider including:

• Recommendation UI screenshots
• Training logs
• Embedding similarity examples
• Database vector examples
• API response samples
• Architecture diagrams

---

🧑‍💻 Author

Built as a Machine Learning + Backend Engineering portfolio project focused on recommendation systems, neural networks, and vector databases.

---

📄 License

This project is available for educational and portfolio purposes.