MovieRec-NeuMF: Architectural Practice of a Movie Recommendation System Based on Neural Matrix Factorization

Source: GitHub by Tomatos32 (2026-05-30)

MovieRec-NeuMF is a movie recommendation system combining GMF and MLP dual channels (NeuMF algorithm) with a hybrid Java Spring WebFlux + Python FastAPI architecture. Key features include auto-switch between cold start and personalized modes, multi-level caching, circuit breaking, and real-time data feedback, addressing core recommendation challenges while ensuring production stability.

Two major issues plague movie recommendation systems:

1. Cold start: New users/films lack historical data, rendering traditional collaborative filtering ineffective.
2. Real-time: User interests change dynamically, requiring quick recommendation adjustments.

MovieRec-NeuMF solves these via elastic architecture, auto mode switching, and real-time learning.

The system uses a layered design:

• Business layer: Java 17 + Spring WebFlux (non-blocking I/O), R2DBC (async DB), Reactive Redis, Spring Kafka, Resilience4j (stability).
• Model layer: Python + FastAPI + PyTorch (deep learning inference).
• Frontend: Vue3 + Vite + Element Plus + Pinia + Tailwind CSS.

This separation lets Java handle concurrency/stability and Python focus on ML inference.

NeuMF merges GMF and MLP:

• GMF: Generalized Matrix Factorization, captures linear user-item interactions via element-wise embedding multiplication.
• MLP: Multi-Layer Perceptron, learns non-linear interactions via concatenated embeddings and FC layers.
• Fusion: Concatenate GMF/MLP outputs, pass through FC layer then sigmoid for prediction scores.

Balances memory (GMF) and generalization (MLP) capabilities.

Auto-switch based on user interaction data:

• Cold start: For new users/little data, uses hot lists, content similarity (Redis data).
• Personalized: For users with enough data, uses PyTorch model inference (user profile + real-time computation).
• Switch logic: Threshold-based (below → cold start, above → personalized).

Stability: Resilience4j (150ms timeout → circuit break, fallback to hot lists), multi-level cache (Redis short-term, local, MySQL). Data loop: Kafka collects user behavior (online → Redis, offline → MySQL). Uses MovieLens 32M dataset with 1:4 sampling and Leave-One-Out split. Supports incremental training for model evolution.

Deployment:

1. Start infra via docker-compose.
2. Initialize DB with schema.sql.
3. Process data with data_processor.py.
4. Train model to get model.pth.
5. Start backend (mvn spring-boot:run) and frontend (npm run dev).

Takeaways: Demonstrates engineering best practices for production recommendation systems—architecture decoupling, cold start handling, stability mechanisms, and data closed loop. A valuable reference for developers.