🎬 Scene It All - System Architecture

← Back to Home

System Architecture & Data Flow

GitHub - Source Control & Auto-Deploy FRONTEND Scene It All Web App Browse • Rate • Track • Chat • Recommend Cloudflare Pages / trumpsbigly.com User requests (genres, movies, ratings, tracking) Movie data + recommendations (cached, enriched) BACKEND API Express.js Server Fetches • Caches • Enriches • Generates Recommendations • Handles Sessions Railway.app (Node.js) Store/Fetch: movies, ratings, user lists, sessions Cached movies, user preferences, recommendations DATABASE MongoDB Atlas Movies • User Lists • Ratings • Sessions Recommendations • Embeddings • Cache MongoDB Atlas (AWS) EXTERNAL APIS Scene It All • Mailgun/TMDB/OMDb/OpenAI Pool Tracker • YoLink TMDB API Movie data, ratings, genres, posters, release dates Requests movie data OMDb API Rotten Tomatoes scores, reviews, viewer ratings Enrich with RT scores OpenAI API Text embeddings for similarity scoring Generate embeddings Mailgun API Email delivery for invite codes (Scene It All) Send invite emails YoLink API IoT devices Temperature, sensors (Pool) Query IoT data DATA FLOW DETAILS 0. User Authentication: Signup: Email + password → bcryptjs hashes password → stores User in MongoDB → generates JWT token. Login: Email + password → bcryptjs verifies against hash → returns JWT token. All protected endpoints require valid JWT bearer token in header. 1. User Browses: Frontend (authenticated) → GET /api/genres with JWT token → Backend verifies token → fetches from TMDB & caches → Returns genre list + movie count 2. Backend Enriches Data: For each movie: fetch title, poster, TMDB rating → call OMDb for Rotten Tomatoes score → store in MongoDB for caching 3. User Tracks Movies: Frontend → POST /api/movies/{id}/seen with JWT → Backend verifies user from token → stores in UserMovieList with userId → Database returns confirmation 4. AI Recommendations: Weekly cron: Get user's rated movies (filtered by userId) → OpenAI generates embeddings → Compare against all unwatched movies → Score by similarity → Store top 30 in MongoDB for this userId → Frontend displays when user clicks "Recommendations"

Component Breakdown

🐙 GitHub - Version Control & CI/CD

Role:

  • Central repository for all source code (frontend, backend, configs)
  • Git version control with full commit history and branching
  • Integrates with Railway for automatic deployments
  • Tracks all changes made to the codebase

Deployment Flow:

  • Developer pushes code to main branch on GitHub
  • GitHub webhook triggers Railway deployment
  • Railway pulls latest code and rebuilds application
  • New version goes live automatically (continuous deployment)

What It Stores:

  • server.js — Express backend code
  • movies/movie-tracker.html — Frontend app
  • db/models.js — MongoDB schemas
  • package.json — Dependencies and build config
  • All other apps (Pool Tracker, City Bomber, etc.)

🌐 Cloudflare Pages - Frontend Hosting

Role:

  • Serves your entire user-facing web application globally via CDN
  • Acts as the "browser-facing" layer—everything users interact with
  • Handles routing and serves static HTML/CSS/JavaScript files
  • Automatically deploys whenever you push to GitHub

What It Serves:

  • Scene It All app (movie-tracker.html) — browse, rate, track, chat about movies
  • Landing page (index.html) — shows links to all apps
  • Architecture documentation — the page you're reading now
  • All UI elements, buttons, tabs, and forms the user sees
  • CSS styling and JavaScript interactivity (no server-side rendering)

⚙️ Railway.app - Backend API Server

Role:

  • Runs your Node.js Express server—the "brain" of your app
  • Handles all business logic: what to return, when to cache, when to fetch external data
  • Gateway between frontend (browser) and backend services (databases, APIs)
  • Executes scheduled tasks (cron jobs) like weekly recommendation generation

Key Responsibilities:

  • Authenticate users — Verify email/password with bcryptjs, issue JWT tokens, validate tokens on all protected endpoints
  • Manage invites — Create 30-day invite codes for new users, verify invite codes during signup
  • Multi-user isolation — Filter all data queries by userId from JWT token (each user sees only their own data)
  • Fetch data from TMDB API when user searches
  • Enrich movies with Rotten Tomatoes scores from OMDb
  • Cache popular movies in MongoDB to avoid repeated API calls

🗄️ MongoDB Atlas - Database

Role:

  • Persistent data storage for everything—movies, user data, history
  • Survives server restarts and deploys (unlike memory)
  • Accessible from Railway backend via connection string
  • Scales automatically as you add more movies/users

Collections Stored:

  • Users — User accounts with email, bcrypt password hash, registration date, last login
  • Invites — Invite codes (30-day expiration), created by admin, email they're sent to, use status
  • Movies — ~5,000+ movie records with title, TMDB rating, OMDb RT score, poster URL, release date, genres
  • UserMovieLists — Which movies each user has marked as "Seen", "Watch Later", or "Enjoyed"
  • MovieRatings — Thumbs up/down ratings from each user (used to train recommendation algorithm)
  • Recommendations — Pre-computed AI suggestions per user with reasons (top 30 per user, updated weekly)

🔌 External APIs - Third-Party Services

TMDB API (The Movie Database)

What it provides (Scene It All):

  • Movie titles, descriptions, poster artwork
  • TMDB ratings (audience ratings out of 10)
  • Release dates, genres, runtime, director and cast
  • 8 million+ movies in their database

OMDb API (Open Movie Database)

What it provides (Scene It All):

  • Rotten Tomatoes critics score (0-100)
  • Rotten Tomatoes audience score
  • IMDb ratings and votes

OpenAI API (AI/Chat & Embeddings)

What it provides (Scene It All):

  • Text Embeddings: Convert movie descriptions → numerical vectors for similarity matching
  • Chat Completions: Conversational AI for "ask the movie assistant"

Mailgun API (Email Service)

What it provides (Scene It All):

  • Sends invite code emails to new users
  • Reliable email delivery with tracking
  • Sender verification and authentication (SPF/DKIM)

When it's called:

  • Admin generates invite code → Mailgun sends email with 30-day code to recipient
  • Recipient uses code during signup to join the app

YoLink API (IoT Smart Home Devices)

What it provides (Pool Tracker):

  • Access to smart IoT devices (pool thermometers, sensors, etc.)
  • Real-time temperature and sensor readings
  • Device discovery and management
  • Connection authentication with OAuth tokens

When it's called:

  • User clicks "Find My Devices" → Backend requests YoLink API for list of user's devices
  • User selects device → Backend queries current temperature from YoLink
  • Pool Tracker displays real-time data from IoT sensors

Data Lifecycle Example

1. User browses horror movies: Frontend sends request to Railway → Railway calls TMDB API → Caches results in MongoDB → Returns to frontend with OMDb RT scores.

2. User marks "The Shining" as seen: Frontend sends rating to Railway → Railway stores in MongoDB under user's account → Updates recommendation algorithm state.

3. Weekly recommendation job runs: Railway cron pulls user's rated movies → Calls OpenAI to generate embeddings → Compares against 5000+ horror movies → Scores by similarity → Saves top 30 to MongoDB → User sees them in Recommendations tab next login.

4. User asks chat "What's a good horror movie?": Frontend sends message to Railway → Railway calls OpenAI chat API with user's preferences context → Returns suggestion → User sees in chat sidebar.