🎬 Movie Review Moderation System

An intelligent movie review moderation system built with Motia framework that analyzes sentiment, moderates content, and generates personalized movie recommendations.

✨ Features

• 🤖 AI-Powered Moderation - Automatically analyzes review sentiment and filters inappropriate content
• 🎯 Genre-Aware Recommendations - Intelligently recommends movies based on the same genre as the reviewed movie
• 📊 Real-time Analytics - Tracks review sentiment scores and approval rates with detailed genre information
• 🔄 Event-Driven Architecture - Uses Motia's event system for seamless data flow
• 🎭 Advanced TMDB Integration - Fetches rich movie data, genre information, and targeted recommendations
• 🚀 Multi-Strategy Recommendations - 4-tier fallback system ensuring quality recommendations
• 🧪 Comprehensive Testing - Includes automated test suite for genre-based recommendations

🏗️ Architecture

This system implements a genre-aware movie-moderation flow with four intelligent components:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  ModerateReview │───▶│ AnalyzeSentiment │───▶│ Genre-Aware Recom-  │───▶│NotifyRecommendations│
│     (API)       │    │     (Event)      │    │  mendations (Event)  │    │       (Event)       │
└─────────────────┘    └──────────────────┘    └─────────────────────┘    └─────────────────────┘
        │                       │                          │                          │
        ▼                       ▼                          ▼                          ▼
   Receives POST          Analyzes text           🎬 Identifies movie         Prepares notifications
   requests with          sentiment and           genre and finds            with genre-matched
   movie reviews          moderates content       same-genre movies          recommendations

🎯 Genre-Aware Intelligence

🎥 Horror Movie → Recommends other horror films
🎆 Action Movie → Recommends other action films
😂 Comedy Movie → Recommends other comedies
🚀 Sci-Fi Movie → Recommends other sci-fi films

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• TMDB API Key (free from themoviedb.org)

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd motioa-demo

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env

   Edit .env and add your TMDB API key:

   TMDB_API_KEY=your_tmdb_api_key_here
   PORT=3000
   NODE_ENV=development

4. Start the development server

   npm run dev

5. Start testing the API The system is now ready! You can test it using:

   • The automated test script (recommended)
   • Direct API calls
   • Motia Workbench at http://localhost:3000

📡 API Usage

Submit a Movie Review

Endpoint: POST /api/moderate-review

Request Body:

{
  "movieId": "1038392",
  "reviewText": "This movie was absolutely amazing! Great acting and plot.",
  "userId": "user123"
}

Response:

{
  "status": "success",
  "data": {
    "isApproved": true,
    "moderationReason": "Your review is being processed"
  }
}

🔧 Available Scripts

# Development
npm run dev              # Start development server with hot reload
npm run generate-types   # Generate TypeScript types from Motia config

# Production
npm run build           # Build the project for production
npm start              # Start production server

# Utilities
npm run clean          # Clean build artifacts and dependencies

🏗️ Project Structure

├── steps/                          # Motia step definitions
│   ├── moderate-review.step.ts     # API endpoint for review submission
│   ├── analyze-sentiment.step.ts   # Sentiment analysis and moderation
│   ├── generate-recommendations.step.ts  # Genre-aware TMDB recommendations
│   └── notify-recommendations.step.ts    # Enhanced notification handler
├── services/                       # External service integrations
│   ├── tmdb.service.ts            # Enhanced TMDB API client with genre support
│   └── types.ts                   # Shared type definitions
├── test-genre-recommendations.js  # Automated test suite for genre-based recommendations
├── .env                           # Environment variables (create from .env.example)
├── motia-workbench.json          # Motia workbench configuration
└── types.d.ts                    # Generated TypeScript types

📊 Step Details

1. ModerateReview (API Step)

• Type: API Route Handler
• Method: POST
• Path: /api/moderate-review
• Purpose: Receives movie review submissions and validates input
• Emits: review-moderated event

2. AnalyzeSentiment (Event Step)

• Type: Event Handler
• Subscribes to: review-moderated
• Purpose: Analyzes review sentiment and filters inappropriate content
• Features:
  • Simple keyword-based sentiment analysis
  • Inappropriate content filtering
  • Caching for performance optimization
• Emits: review-analyzed event

3. GenerateRecommendations (Event Step) 🎬

• Subscribes to: review-analyzed
• Purpose: Intelligently generates genre-based movie recommendations
• Features:
  • 🎭 Genre Detection: Identifies movie genres from TMDB
  • 🎥 Smart Matching: Recommends movies from the same genre
  • 🔄 4-Tier Fallback System:
    1. Primary genre movies (same main genre)
    2. Multi-genre movies (multiple matching genres)
    3. TMDB recommendations (original algorithm)
    4. Popular movies (high-rated fallback)
  • 📈 Quality Scoring: Sorts by vote average and popularity
• Emits: recommendations-generated event with genre information

4. NotifyRecommendations (Event Step)

• Type: Event Handler
• Subscribes to: recommendations-generated
• Purpose: Prepares notification data for users
• Features:
  • Structured notification data
  • Ready for email/push notification services
  • Comprehensive logging

🎯 Sentiment Analysis Rules

The system uses a simple but effective sentiment analysis algorithm:

Inappropriate Content Filters:

• hate, terrible, awful, boring, worst
• Reviews containing these words are automatically rejected

Positive Keywords:

• great, amazing, love, excellent, best (+0.1 each)

Negative Keywords:

• bad, poor, disappointing, waste (-0.1 each)

Approval Threshold: Score > 0.3

🎬 Genre-Aware Recommendation Algorithm

The system uses an intelligent 4-tier recommendation strategy:

🎥 Tier 1: Primary Genre Matching

• Identifies the main genre of the reviewed movie
• Fetches highest-rated movies from the same genre
• Filters out the original movie
• Prioritizes movies with 100+ votes for quality

🎭 Tier 2: Multi-Genre Matching

• For movies with multiple genres (e.g., Action-Comedy)
• Finds movies that share multiple genres
• Broader selection while maintaining relevance

🔄 Tier 3: TMDB Recommendations

• Falls back to TMDB's native recommendation engine
• Uses collaborative filtering and user behavior data
• Provides diversity when genre-specific movies are limited

📈 Tier 4: Popular Movies

• Final fallback to ensure recommendations are always provided
• High-rated, popular movies across all genres
• Filtered to exclude the reviewed movie

🎯 Quality Assurance

• All recommendations sorted by vote average
• Limited to top 5 recommendations
• Includes recommendation strategy metadata

🔌 TMDB Integration

The system integrates with The Movie Database (TMDB) API to:

• Fetch detailed movie information
• Get movie-specific recommendations
• Retrieve popular movies as fallback
• Search for movies by query

Rate Limits: TMDB API allows 40 requests every 10 seconds

🚀 Deployment

Using Docker (Recommended)

# Build the image
docker build -t movie-moderation .

# Run the container
docker run -p 3000:3000 -e TMDB_API_KEY=your_key movie-moderation

Manual Deployment

1. Build the project:

   npm run build

2. Set production environment variables

3. Start the production server:

   npm start

🔍 Monitoring & Debugging

Using Motia Workbench

1. Open http://localhost:3000
2. Select the "movie-moderation" flow
3. Use the visual interface to:
   • Test individual steps
   • Monitor event flow
   • View execution logs
   • Debug issues in real-time

Log Levels

• INFO: General flow information
• DEBUG: Detailed execution data
• WARN: Non-critical issues
• ERROR: Critical failures

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

📋 TODO / Future Enhancements

• ✅ Genre-based recommendations - Completed! Now recommends movies by genre
• ✅ Comprehensive test suite - Completed! Automated testing script available
• ✅ Enhanced TMDB integration - Completed! Advanced genre detection and discovery
• Add machine learning-based sentiment analysis
• Implement user preference learning
• Add email notification service integration
• Create admin dashboard for moderation oversight
• Add Redis for distributed caching
• Implement rate limiting
• Docker containerization
• CI/CD pipeline setup
• Fix Motia Workbench UI issues
• Add genre-specific sentiment analysis (e.g., horror-specific keywords)

🐛 Troubleshooting

Common Issues

Issue: ERR_HTTP_INVALID_STATUS_CODE
Solution: Ensure all handlers return proper response objects with status and body properties.

Issue: [INVALID EMIT] errors
Solution: Make sure emit calls use the format: emit({ topic: 'event-name', data: {...} })

Issue: TMDB API failures
Solution: Check your API key in .env and verify network connectivity.

Issue: No genre-based recommendations
Solution: Ensure the movie ID exists in TMDB and has genre information. Check the logs for genre detection messages.

🙏 Acknowledgments

• Motia Framework - For the excellent workflow framework
• The Movie Database (TMDB) - For movie data and recommendations
• Axios - For HTTP client functionality
• Zod - For schema validation

---

Built with ❤️ using Motia Framework
GitHub • LinkedIn