Live Production App: https://cinematch-friends.netlify.app
Netlify Site ID:aee7ff78-0002-48f6-951c-f95eb8c84174
Repository Ready: Full-stack serverless deployment package with Netlify Blobs & local development server.
- Project Overview
- Key Features
- Architecture & Tech Stack
- Streaming Provider Integration (Movy.sx)
- Real-Time Sync & Netlify Blobs Database
- Optimistic UI & Anti-Flicker State Lock
- API Specification
- Theme System (Light & Dark Mode)
- Local Development & Wi-Fi Sharing
- Production Deployment (Netlify)
- Developer & LLM Handover Guide
Geddi's Rec (originally CineMatch) is a mobile-first, zero-friction social movie curation platform built for friend groups. Rather than generic algorithm recommendations, users share direct movie recommendations with personal reviews, vote across emotional reaction tiers, engage in dedicated comment threads, and launch one-click streaming via Movy.sx using verified TMDB IDs.
All recommendations, reactions, and comments sync live across users via Netlify Serverless Functions backed by Netlify Blobs cloud storage.
- User Identity & Color Coding:
- First-time visitors enter their name (persisted in
localStorage). - Every user is assigned a deterministic, high-contrast color avatar and username accent dynamically derived from a hash of their name.
- First-time visitors enter their name (persisted in
- Central "Stream it NOW!" Watch Button:
- Every recommendation card features a prominent, centered "โถ Stream it NOW!" CTA button.
- Automatically links to
https://www.movy.sx/movie/<tmdbId>?play=trueusing TMDB metadata resolved upon adding the movie. - Compact list view features an inline "Stream NOW!" button.
- YouTube trailer modal includes an integrated direct stream button in the footer.
- Sentiment Reactions with Friend Attribution:
- ๐ I beg you to watch this (High-priority fire banner)
- ๐ฅ Hyped to watch
- โค๏ธ Loved it
- ๐ Liked
- ๐ Didn't like
- ๐คฎ Hate it
- User names are displayed inside colored chips on each reaction. Votes are mutually exclusive per user.
- Scoring algorithm:
totalLoved = begCount + lovedCount.
- Per-Movie Comment Threads:
- Comment counter badge on every card.
- Expandable drawer/accordion to read and post comments with real-time sync.
- Author-Only Deletion Protection:
- Only the friend who originally recommended a movie has the permission to delete it. Other users cannot see or trigger the delete action.
- Dual Layout Views:
- ๐ด Cards View: Full cards with high-res posters, IMDb rating badges, expandable plot synopsis, reaction breakdown, and streaming CTA.
- ๐ Compact List View: Minimalist list for quick scanning with title, recommender, and stream action.
- Curated Starter Library:
- Pre-loaded with 31 acclaimed movies (
curated-movies.js) with pre-mapped TMDB IDs for instant streaming.
- Pre-loaded with 31 acclaimed movies (
- Dark / Light Mode:
- Header toggle switch with persistent theme state in
localStorage. - Tuned contrast tokens ensuring notes, badges, and banners are crisp in both modes.
- Header toggle switch with persistent theme state in
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Client (Browser) โ
โ index.html ยท app.js ยท styles.css ยท curated-movies.js โ
โ - Vanilla ES6+ (No bundler required) โ
โ - Optimistic UI Lock (6s cooldown against poll overrides) โ
โ - Live Polling (10s interval) โ
โ - CSS Custom Properties for Light/Dark themes โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Streaming & Metadata โ โ Netlify Serverless โ
โ - Movy.sx (TMDB-based) โ โ netlify/functions/ โ
โ - Cinemeta / TMDB API โ โ api.js, reactions.js โ
โ - YouTube Embeds โ โ recommendations.js โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Netlify Blobs Store โ
โ "geddis_recommendations" โ
โ Key: recommendations_dataโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- Frontend: Plain HTML5, CSS3, Modern JavaScript (ES6+ Modules). Zero Webpack/Vite complexity for instant debugging.
- Backend: Netlify Serverless Functions (Node.js 18+) accessing
@netlify/blobs. - Local Fallback: Python 3 HTTP server (
server.py) with built-in REST API and Wi-Fi QR/IP announcer writing torecommendations.json. - Routing & CDN:
netlify.tomlwith wildcard proxy rewrite (/api/*โ/.netlify/functions/api) and strict cache-busting headers (Cache-Control: private, no-store).
To provide one-click streaming without external searching:
- Base URL Pattern:
https://www.movy.sx/movie/{tmdbId}?play=true - Resolution Strategy (
app.js):- If
item.tmdbIdis already stored, directly generate the link. - For curated classics,
curated-movies.jsholds verified TMDB IDs. - When a user adds a new movie,
resolveTmdbId(title, year)queries Cinemeta/TMDB API to capture the exact integeridbefore persisting to Netlify Blobs. - Fallback: If no TMDB ID is resolved, links to
https://www.movy.sx/search?q={title}.
- If
- Store Name:
geddis_recommendations - Key:
recommendations_data - Data Model:
[ { "id": "rec-1727771234567", "movieId": "tt0816692", "tmdbId": 157336, "title": "Interstellar", "year": "2014", "imdbRating": "8.7", "poster": "https://m.media-amazon.com/...", "genres": ["Adventure", "Drama", "Sci-Fi"], "director": "Christopher Nolan", "synopsis": "When Earth becomes uninhabitable...", "trailerId": "zSWdZVtXT7E", "recommendedBy": "Geddi", "note": "Mind-bending visual masterpiece. Must watch in 4K!", "timestamp": "Oct 1, 2026", "reactions": { "beg": ["Geddi"], "hyped": ["Sarah"], "loved": ["Alex"], "liked": [], "disliked": [], "hated": [] }, "comments": [ { "id": "c-1727771299999", "author": "Sarah", "text": "The docking scene soundtrack gave me chills!", "timestamp": "Oct 1, 2026" } ] } ]
With background polling every 10 seconds, clicking a reaction button or posting a comment could trigger an annoying UI flicker: the count increases by 1 locally, but an in-flight GET request returning older server state flashes the count back to 0 before the POST completes.
let isMutating = false;
let lastMutationTime = 0;
// When user votes or comments:
isMutating = true;
lastMutationTime = Date.now();
// 1. Immediately mutate local data model & re-render DOM
// 2. Dispatch async POST to /api/reactions or /api/comments
// 3. In the 10-second polling loop:
function pollFeed() {
if (isMutating || (Date.now() - lastMutationTime < 6000)) {
return; // Skip poll override during cooldown
}
fetchFeed();
}This guarantees snappy, native-app feel with zero flicker.
All endpoints are hosted at /api/* and redirected to netlify/functions/api.js.
Returns JSON array of all saved recommendations, sorted newest first.
Adds a new recommendation.
- Payload:
{ "id": "rec-123456", "title": "Inception", "year": "2010", "imdbRating": "8.8", "tmdbId": 27205, "poster": "https://...", "director": "Christopher Nolan", "synopsis": "A thief who steals corporate secrets...", "recommendedBy": "Geddi", "note": "Amazing concept!", "initialVerdict": "loved" }
Toggles a user's reaction for a movie.
- Payload:
{ "id": "rec-123456", "reaction": "hyped", "userName": "Alex" } - Response:
{ "success": true, "reactions": { ... } }
Adds or deletes a comment on a recommendation.
- Payload (Add):
{ "id": "rec-123456", "comment": { "author": "Sarah", "text": "Great suggestion!" } } - Payload (Delete):
{ "id": "rec-123456", "deleteCommentId": "c-987654" }
Deletes a recommendation (enforces author verification).
- Payload:
{ "id": "rec-123456", "userName": "Geddi" }
The interface utilizes CSS Custom Properties declared in :root and [data-theme="light"]:
- Dark mode: deep cinematic slate
#0d1117, card surfaces#161b22, neon gold accents#ffd700. - Light mode: crisp off-white
#f6f8fa, card surfaces#ffffff, high-contrast text#1a202c. - User colors: generated by
getUserColor(userName)using golden-angle HSL distribution for optimal readability on both dark and light surfaces.
python server.pyOutputs:
๐ป On this computer:
๐ http://localhost:3000
๐ฑ On your phone & friends' phones (Same Wi-Fi):
๐ http://192.168.1.X:3000
npm install
npx netlify devThe project is configured for one-click continuous deployment on Netlify:
- Push this repository to GitHub.
- Link your repository in Netlify (app.netlify.com).
- Build Settings:
- Build command: (leave empty)
- Publish directory:
. - Functions directory:
netlify/functions
- Netlify automatically provides Blobs storage for the site.
- Production URL:
https://cinematch-friends.netlify.app
If you are an AI assistant or human developer continuing work on this project:
- Keep it lightweight: Do NOT introduce heavyweight bundlers (Webpack, Vite, Tailwind CLI) unless requested. The app runs directly in any modern browser without a build step.
- Preserve Optimistic Locking: Any changes to reaction or comment interactions must respect
isMutatingandlastMutationTimeto prevent background poll overwrites. - Movy.sx URLs: Maintain the
https://www.movy.sx/movie/<tmdbId>?play=trueformat. Ensure any new movie recommendation resolvestmdbIdcorrectly. - Data Consistency: In
netlify/functions/api.js, every recommendation must pass throughnormalizeItemReactions()to guarantee all reaction keys (beg,hyped,loved,liked,disliked,hated) andcommentsarray exist. - Netlify Functions Layout: Both monolithic
/api/*routing and individual function entry points (recommendations.js,reactions.js,comments.js) are kept in sync.
Made with โค๏ธ for movie nights with friends.