Project: MovieDice

1. Project Overview

MovieDice is a mobile-first web app that helps friend groups collaboratively build a shared movie watchlist and — when nobody can agree on what to watch — randomly select one using an animated "Roll the Dice" mechanic. Groups join via a short invite code, add movies from a live TMDB search, and mark films as watched together. The app removes the friction of the "what should we watch?" problem by making both curation and random selection fast and fun.

A public landing page lets visitors try the dice mechanic against the TMDB database before signing up, lowering the barrier to entry. The landing page features a slot-machine-style reel animation on roll — distinct from the in-app scatter/eliminate animation — to create a visually striking first impression.

2. Target Users

Primary: Friend groups, couples, roommates, or families who watch movies together and maintain an informal "we should watch this" list that currently lives in text threads or notes apps.

Secondary: Remote groups (long-distance friends, online communities) who watch movies synchronously or asynchronously and want a shared queue.

Key traits:

Mobile-first users — majority of interaction happens on phones
Low tolerance for signup friction — will abandon if auth is annoying
Motivated by the social/playful aspect as much as the utility

3. Core Value Proposition

One shared list. One button to decide. No arguments.

MovieDice solves group decision paralysis by combining collaborative curation (everyone adds what they want to watch) with a delightful randomizer that removes the burden of choosing. The invite-code group model means zero signup friction while still keeping lists private to the group.

4. Scope of Work

In Scope (MVP)

Feature	Description	Priority
Landing page	Centered logo, splash text, slot-machine reel animation on Roll the Dice (3 reels spinning through ~20 automatically fetched posters from TMDB popular/top-rated, replaced on each periodic refresh), Genre Roll against TMDB (no login required), Login button, scrolling About section, 3-step how-it-works demo with alternating left-right-left alignment	Must Have
Anonymous auth with display name	User picks a display name and optional avatar color; a UUID-based account is created and persisted on device	Must Have
Recovery code	A longer alphanumeric code shown once after account creation that lets users reclaim their identity on a new device	Must Have
Group creation with invite code	Creator gets a short human-readable code (e.g., WOLF-42) to share; creator becomes List Admin	Must Have
Group join via invite code	Enter code to join a group and access its shared list; regular member role assigned	Must Have
List Admin permissions	Creator can rename the list, initiate list deletion or ownership transfer (on self-removal), remove members, and regenerate the invite code	Must Have
Regular user permissions	Members can add/remove movies, mark movies as watched, and leave the list	Must Have
Movie search (TMDB integration)	Search bar queries TMDB with debounce (~300ms); results show below a separator from in-list results	Must Have
Add/remove movie	Tap a TMDB result to add it; poster, genres, title, year, and trailer URL auto-populate (trailer URL stored in DB and refreshed periodically); added-by attribution stored	Must Have
Poster-forward grid view	2-column evenly-scaling grid; each card shows movie poster (full bleed) with title below; added-by avatar overlaid top-right; binoculars emoji overlaid top-left when watched; infinite scroll loading 12 movies initially	Must Have
Expanded movie card (inline panel)	Tapping a poster expands a full-page-width panel downward, inserted below that row in the grid — not a modal or popup. Panel order (top to bottom): full-size poster → title → "Added by [username]" → genre tags → Watched It + Trailer (side by side) → Delete (centered below). Delete uses two-tap shake-and-confirm. Watched It toggles watched state. Trailer opens in new tab. Panel collapses on tap outside.	Must Have
Genre filter	Tapping a genre tag in the expanded panel filters the grid to that genre	Must Have
Roll the Dice	Large button pinned above the list; triggers an animated randomizer that lands on one unwatched movie from the group list	Must Have
Re-roll	Tapping Roll again re-rolls from the same eligible pool	Must Have
Genre + Emotion Roll	Secondary button accepting comma-separated genres and/or emotion keywords; maps emotions to genre IDs, filters pool, then rolls	Must Have
Watched state (per group, toggle)	Marking a movie watched moves it to a collapsed "Watched" section; marking again moves it back. Binoculars overlay and button color update in real time across all members.	Must Have
Real-time list sync	Add, remove, and watched-status changes appear live on all connected group members' screens (Supabase real-time)	Must Have
Logged-in home page	Upon login or return visit (stored user ID detected), user lands on a home page that mirrors the landing page layout but shows their lists as cards and replaces Login with Create List; Roll the Dice and Genre Roll roll across all user lists combined and display the result as a standalone teaser card on the home page (no navigation into a specific list)	Must Have
Multi-group support	A user can belong to more than one group; all their lists appear as cards on the home page	Should Have
Invite code rotation	List Admin can regenerate the invite code to revoke access for anyone with the old code	Should Have
Trailer URL periodic refresh	Background job on a bi-weekly cadence refreshes stored trailer URLs only for movies where trailer_url is currently null. Note: this behavior should be reassessed post-launch to also refresh stale URLs after a certain age.	Should Have
Master Admin panel	Site-owner-only admin page with TOTP 2FA; can search and delete any list or user; credentials set via environment variables	Must Have

Out of Scope (Future)

Compact list/grid toggle — user unfamiliar with it at scoping; deferred post-MVP
Per-user watched status — MVP uses per-group status only
Push notifications — adds native app complexity
In-app chat or comments on movies — scope creep risk
Rating or ranking movies — adds complexity to the watched flow
Native iOS/Android apps — PWA covers MVP use case
Social discovery (public lists, find groups) — contradicts the private group model
Streaming availability data (where to watch)
Movie recommendations engine — randomizer covers this need for MVP

5. Feature Flows

Landing Page (Pre-Login)

1. Visitor lands on the root URL — no login required
2. Centered "Movie Dice" header/logo displayed
3. Splash text describes the site briefly (1-2 sentences)
4. "Roll the Dice" button is visible — tapping it triggers the slot-machine reel animation:
   a. Three side-by-side reels spin through ~20 movie poster images pulled automatically
      from TMDB popular/top-rated endpoints (no manual curation; replaced on each periodic refresh)
   b. Reels decelerate and land on a single movie result
      (the final result can be any TMDB movie, not constrained to the reel poster set)
   c. Result is displayed as a static teaser card showing the movie poster, title, and genres.
      No link, no tap action.
5. "Genre Roll" button visible — accepts comma-separated genres/emotions, no reel animation;
   result displayed as a static teaser card (poster, title, genres). No link, no tap action.
6. "Login / Get Started" button below the roll buttons
7. User scrolls down to reveal:
   a. About section — fuller description of how MovieDice works
   b. 3-step how-it-works demo (Create a list → Add movies → Roll the dice)
      - Step 1: left-aligned
      - Step 2: right-aligned
      - Step 3: left-aligned (zigzag visual rhythm)

Onboarding (New User)

1. User taps "Login / Get Started" on landing page
2. User enters display name, optionally picks an avatar color
3. UUID-based account created; persisted in local storage
4. Recovery code shown once — user prompted to save it
5. User selects: "Create a Group" or "Join with a Code"
   A. Create → enter group name → group created, invite code shown (e.g., WOLF-42)
      → creator assigned List Admin role → lands on home page (with their new list card shown)
   B. Join → enter invite code → validated → member role assigned → lands on home page
         (with the joined list card shown)

Logged-In Home Page (Returning or Newly Onboarded User)

1. App reads stored user ID from browser (local storage or cookie)
2. If user ID found → navigate directly to the home page (skip landing page)
3. If user ID not found → show landing page (pre-login)
4. Home page layout mirrors the landing page layout, with these differences:
   a. The Login button is replaced by a "Create List" button
   b. The About / how-it-works section is replaced by the user's list cards
5. Each list card shows:
   - List name (left-aligned)
   - Number of movies with a 🎬 film emoji (right-aligned)
   - Below: "Created by: [username]"
6. Tapping a list card navigates into that list view
7. "Roll the Dice" and "Genre Roll" buttons at the top roll across ALL unwatched movies
   from ALL of the user's lists combined (cross-list roll)
8. The roll result is displayed as a standalone teaser card directly on the home page.
   The result does NOT navigate the user into any specific list.
9. If user ID not found (new device) → prompt for recovery code or start fresh

Adding a Movie

1. User taps search bar at top of list view
2. User types a movie title; TMDB is queried with ~300ms debounce
3. Results appear in two sections:
   - Top: movies already in the group's list (labeled "In Your List")
   - Below separator: TMDB search results
4. User taps a TMDB result → movie inserted into DB with poster, genres, title, year,
   trailer URL (fetched from TMDB and stored at add-time), and added-by attribution
5. All group members see the new movie appear in real time

Movie Card Grid View

1. Default view: 2-column evenly-scaling poster grid (3-4 columns on tablet/desktop)
2. Each card shows:
   - Movie poster (full bleed)
   - Movie title below the poster
   - Added-by user avatar overlaid top-right corner
   - Binoculars emoji overlaid top-left corner — only when movie is watched
3. Grid loads 12 movies initially; additional movies load automatically on scroll to bottom
4. No action buttons on collapsed grid cards — cards are tap-only

Expanded Movie Card (Inline Panel)

1. User taps any movie poster in the grid
2. A full-page-width panel expands downward, inserted inline below that row in the grid
   (mirrors Google Image Search inline expansion — not a modal, popup, or slide-up sheet)
3. Panel contents, top to bottom:
   a. Full-size movie poster
   b. Movie title
   c. "Added by [username]"
   d. Genre tags — tappable; each filters the grid to that genre
   e. "Watched It" + "Trailer" buttons — displayed side by side
   f. Delete button — centered below, separated to prevent accidental taps
4. Delete behavior:
   - Tap 1: button shakes, text changes to "Click to confirm delete"
   - Tap 2: movie removed from list for all group members in real time
   - Tapping elsewhere after Tap 1 resets button to default state
5. Watched It (toggle):
   - If unwatched: button color changes to watched state, binoculars overlay appears on grid
     poster (top-left), movie moves to "Watched" section
   - If watched: button color reverts, binoculars overlay removed, movie returns to main list
   - Both indicators update simultaneously on all group members' screens
6. Trailer: opens stored trailer URL in a new tab
7. Tapping outside the panel or a close affordance collapses it

Rolling the Dice (In-App)

1. User taps "Roll the Dice!" (pinned above the movie grid or on the home page)
2. Animated randomizer plays — scatter/flip/spin elimination sequence, 2-3 seconds
   (this is distinct from the landing page slot-machine reel animation)
3. Animation settles on one random unwatched movie from the eligible pool
   - On a list page: pool is that list's unwatched movies
   - On the home page: pool is all unwatched movies across all of the user's lists combined
4. On the home page, the result is shown as a standalone teaser card in place on the home page.
   The user is NOT navigated into any specific list.
5. Tapping Roll again re-rolls from the same eligible pool
6. Tapping "Genre Roll!" opens a text input
7. User enters genres and/or emotions (e.g., "action, excited")
8. App normalizes input, maps emotion keywords to TMDB genre IDs, filters the unwatched pool
9. Same scatter/eliminate animation plays on filtered results
10. If no matches found: "No matches — showing full list" shown, roll proceeds unfiltered
11. On a list page, the result movie is displayed prominently; tapping it opens the inline
    expanded panel

List Admin Actions

1. List Admin opens group settings (gear icon or settings menu)
2. Available actions:
   - Rename the list
   - Delete the list (see deletion flow below)
   - View member list with option to remove individual members
   - Regenerate invite code (revokes old code)
   - Display current invite code with copy-to-clipboard
3. Regular members see a settings menu with only: "Leave this list" option

Admin Self-Removal / Ownership Transfer flow:
   a. List Admin taps "Leave this list" (or equivalent self-removal action)
   b. If other members exist:
      - "Transfer Ownership" popup appears before the admin can leave
      - Popup shows the current member list; admin selects one member to become the new admin
      - "Cancel" button at the bottom dismisses the popup with no changes
      - Once a new admin is selected and confirmed, ownership transfers and the original admin
        is removed from the list (they leave; the list is NOT deleted)
   c. If the admin is the last remaining member (no one else to transfer to):
      - The list is deleted automatically (with a standard confirmation prompt)
      - Confirmed deletion removes the list and all its movies permanently

List Deletion flow (separate from self-removal):
   a. List Admin taps "Delete the list" in settings
   b. Standard delete confirmation prompt shown
   c. Confirmed deletion removes the list and all its movies permanently
   d. This action does NOT trigger the Transfer Ownership popup

Master Admin Flow

1. Master Admin navigates to /admin
2. Login prompt: username + TOTP authenticator code (no password-only fallback)
3. Credentials (username and TOTP secret) are set via environment variables — no first-run UI
4. On successful auth → Master Admin dashboard
5. Available tools:
   - Search any list by name or ID → view details → delete (with confirmation)
   - Search any user by display name or ID → view details → delete (with confirmation)
6. Master Admin session is separate from regular user sessions
7. All /admin routes redirect to login if no valid admin session

6. Usability Concerns

Mobile-first: All layouts designed for 375px+ screens first; desktop is a bonus. Grid expands to 3-4 columns on tablet/desktop.
PWA: App should be installable to home screen and behave like a native app in browser.
Inline expansion: The expanded movie panel is a full-page-width inline expansion inserted below the tapped card's row — never a modal, popup, slide-up sheet, or centered dialogue. Mirrors Google Image Search inline expansion behavior.
Two distinct roll animations: The landing page uses a slot-machine reel animation (3 spinning reels of poster images). The in-app roll uses a scatter/flip/spin elimination animation. These must feel visually distinct — the landing animation is attention-grabbing and cinematic; the in-app animation is fast and satisfying but not distracting from repeat use.
Roll animation (in-app): Target 2-3 seconds max — visually impactful but not so long it frustrates repeat use.
Search responsiveness: Debounce TMDB queries at ~300ms; show loading state during fetch.
Real-time updates: New movies and watched status changes appear without a page refresh via Supabase subscriptions.
Offline tolerance: If connection drops, the app should degrade gracefully — show cached list, disable write actions with an explanatory message.
Accessibility: Sufficient color contrast on poster overlays; tap targets minimum 44x44px; screen reader labels on icon buttons.
TMDB API: Cache recent search results client-side to reduce API calls and stay within free tier rate limits.

7. Technical Considerations

Tech Stack

Layer	Choice	Notes
Frontend	Next.js (React, App Router)	PWA support, Vercel deployment
Styling	Tailwind CSS	Mobile-first, fast iteration
Backend / Database	Supabase	Postgres + real-time subscriptions
Movie Data	TMDB API (free tier)	Posters, genres, metadata, trailer URLs
State Management	TanStack Query (React Query)	Server state sync, caching, loading states
2FA (Master Admin)	TOTP via otplib (or equivalent)	Authenticator-app compatible; TOTP secret never exposed client-side
Deployment	Vercel (frontend) + Supabase (hosted)	Both free tiers sufficient for MVP scale

Data Model

users

id (UUID, primary key)
display_name (text)
avatar_color (text, hex)
recovery_code (text, hashed)
is_master_admin (boolean, default false)
created_at

groups

id (UUID, primary key)
name (text)
invite_code (text, unique, short human-readable)
created_by (FK → users.id)
created_at

group_members

group_id (FK → groups.id)
user_id (FK → users.id)
role (text: 'admin' | 'member')
joined_at

movies

id (UUID, primary key)
group_id (FK → groups.id)
tmdb_id (integer)
title (text)
year (integer)
poster_path (text, TMDB relative path — full URL constructed at render time)
genres (text[], TMDB genre labels)
trailer_url (text, nullable — fetched from TMDB at add-time and stored; background job refreshes only null entries on a bi-weekly cadence)
trailer_url_refreshed_at (timestamp — tracks when the trailer URL was last fetched, used by the refresh job)
added_by (FK → users.id)
watched (boolean, default false)
watched_at (timestamp, nullable)
added_at

landing_reel_posters

id (integer, primary key)
tmdb_id (integer)
poster_path (text)
title (text)
refreshed_at (timestamp — set by the periodic reel refresh job)
(Table holds ~20 rows; entire set replaced on each refresh from TMDB popular/top-rated)

admin_sessions

Secure server-side token store for Master Admin TOTP-authenticated sessions; separate from regular user sessions

Privacy

No email addresses collected in MVP
Display names only — no real identity data
Recovery codes hashed before storage
Invite codes are the sole access control mechanism for regular users
Master Admin credentials (username) and TOTP secret are stored as environment variables server-side only; never exposed client-side
TMDB data is public — no privacy concern

Deployment

Vercel auto-deploys from main branch
Supabase on free tier; upgrade path available if scale demands
Environment variables required:
- TMDB_API_KEY
- SUPABASE_URL
- SUPABASE_ANON_KEY
- MASTER_ADMIN_USERNAME — the master admin login username
- MASTER_ADMIN_TOTP_SECRET — the TOTP secret (base32); configure this in your authenticator app (e.g., Google Authenticator, Authy) before first use
No first-run setup UI exists; the master admin account is fully configured via environment variables before deployment

8. Implementation Plan

MVP Deadline: April 26, 2026 Full Feature Complete: July 5, 2026

Phase 1: Foundation (April 5-9, 2026) — MVP

1.1 — Initialize Next.js project with Tailwind CSS and App Router
1.2 — Set up Supabase project; create schema (users, groups, group_members, movies, landing_reel_posters tables)
1.3 — Configure Supabase client in Next.js with environment variables
1.4 — Implement anonymous user creation: display name input, UUID generation, local storage persistence
1.5 — Implement recovery code generation and show-once display screen
1.6 — Implement recovery code claim flow (enter code → restore identity on new device)
1.7 — Deploy skeleton to Vercel; confirm Supabase connection works in production

Phase 2: Groups and Permissions (April 9-13, 2026) — MVP

2.1 — Build "Create a Group" flow: name input, invite code generation (short human-readable format, e.g., WOLF-42), store in DB, assign creator as List Admin
2.2 — Build "Join with a Code" flow: code entry, validation, group_members record with role: 'member'
2.3 — Build logged-in home page: mirrors landing page layout; replaces Login with "Create List" button; shows user's list cards (list name left, movie count + 🎬 right, "Created by: [username]" below); tapping a card navigates to that list; Roll the Dice and Genre Roll on the home page roll across all lists combined and display the result as a standalone teaser card on the home page (no navigation into a specific list)
2.4 — Implement List Admin settings: rename list, regenerate invite code, display + copy invite code, view + remove members; implement "Leave this list" self-removal for admin — if other members exist, show "Transfer Ownership" popup (member list + Cancel button); on confirm, transfer ownership and remove original admin from the list; if admin is last member, delete the list with confirmation
2.5 — Implement List Admin direct deletion: "Delete the list" action in settings shows a standard confirmation prompt and permanently deletes the list; does NOT trigger the Transfer Ownership popup
2.6 — Implement regular user settings: leave list option only

Phase 3: Movie List Core (April 13-19, 2026) — MVP

3.1 — Integrate TMDB API: search endpoint, poster URL construction, trailer URL fetch at add-time; implement client-side result caching to stay within free tier rate limits
3.2 — Build search bar with ~300ms debounce, loading state, and two-section results ("In Your List" above separator, TMDB results below)
3.3 — Implement add-movie flow: tap result → insert into movies table with TMDB metadata, stored trailer_url (fetched at add-time), trailer_url_refreshed_at, and added_by attribution
3.4 — Build 2-column poster grid: full-bleed poster, title below, added-by avatar overlaid top-right, binoculars emoji overlaid top-left (watched only), no action buttons on cards, tap-only interaction
3.5 — Implement infinite scroll: load 12 movies initially, fetch and append next batch automatically on scroll to bottom
3.6 — Build expanded movie inline panel: full-page-width expansion inserted below the tapped row (not a modal); fixed element order (poster → title → Added by → genre tags → Watched It + Trailer side-by-side → Delete centered below); delete two-tap shake-and-confirm; Watched It toggle; Trailer opens stored trailer_url in new tab; collapse on tap outside
3.7 — Implement genre filter: tapping a genre tag in the inline panel filters the grid to that genre
3.8 — Implement Watched state: toggle marks/unmarks movie as watched for the group; watched movies move to collapsed "Watched" section; binoculars overlay and button color update simultaneously across all members
3.9 — Enable Supabase real-time subscriptions on movies table for live add, remove, and watched-status updates

Phase 4: Randomizer (April 19-22, 2026) — MVP

4.1 — Build "Roll the Dice!" and "Genre Roll!" button layout pinned above the movie grid
4.2 — Implement randomizer logic: select a random unwatched movie from the eligible pool (single list when in a list view; all user lists combined when on the home page); on the home page, render result as a standalone teaser card in place — do not navigate into any list
4.3 — Build in-app roll animation: scatter/flip/spin elimination sequence landing on winner (target 2-3 seconds); test performance on low-end mobile devices
4.4 — Implement re-roll on second tap of Roll button
4.5 — Build Genre Roll text input UI
4.6 — Implement emotion-to-genre static mapping (see Section 10 reference table)
4.7 — Implement genre + emotion filter logic: normalize input (lowercase, tokenize on spaces/commas), map emotions to TMDB genre IDs, filter unwatched pool; if no matches, show "No matches — showing full list" and proceed unfiltered
4.8 — Apply roll animation to genre-filtered results

Phase 5: Landing Page and MVP Polish (April 22-26, 2026) — MVP CUTOFF

5.1 — Build landing page structure: centered logo, splash text, Roll + Genre Roll buttons, Login button, scrolling About section, 3-step how-it-works demo (Step 1 left, Step 2 right, Step 3 left)
5.2 — Build and seed landing_reel_posters table: implement periodic refresh job (suggested cadence: bi-weekly) that automatically fetches ~20 posters from TMDB popular or top-rated endpoints (no manual curation) and replaces the full set in the DB on each run
5.3 — Build slot-machine reel animation for the landing page Roll the Dice button: 3 side-by-side reels that spin through the automatically fetched poster set, decelerate, and land on a single TMDB movie result (the final result is fetched live from TMDB — not constrained to the reel poster set)
5.4 — Wire landing page Roll the Dice and Genre Roll to TMDB directly (no login required); display result as a static teaser card showing poster, title, and genres — no link, no tap action
5.5 — Loading and empty states for all major views (empty list, no search results, no genre matches, empty home page for new users)
5.6 — Error handling: invalid invite code, TMDB API failure, network errors
5.7 — Final MVP smoke test and Vercel production deployment

Phase 6: Trailer URL Refresh (April 27 - May 3, 2026) — Post-MVP

6.1 — Implement background trailer URL refresh job: query movies where trailer_url IS NULL (bi-weekly cadence); fetch trailer URL from TMDB for each; update trailer_url and trailer_url_refreshed_at in DB. NOTE: this scope (null-only) should be reassessed post-launch to also refresh stale/aging URLs after a certain age threshold.
6.2 — Set up job scheduling (Vercel Cron or Supabase scheduled function); confirm job runs reliably in production
6.3 — Add monitoring/logging for refresh failures (e.g., TMDB returned no trailer) so missing URLs can be investigated

Phase 7: Master Admin (May 4-17, 2026) — Post-MVP

7.1 — Document Master Admin setup: MASTER_ADMIN_USERNAME and MASTER_ADMIN_TOTP_SECRET must be set as environment variables before first use; provide instructions for generating and enrolling the TOTP secret in an authenticator app
7.2 — Build /admin login route: username + TOTP code input, no password-only fallback; reads credentials from environment variables
7.3 — Implement server-side TOTP verification (otplib); issue admin session token on success
7.4 — Build Master Admin dashboard UI
7.5 — Implement list search and deletion (by name or ID, with confirmation)
7.6 — Implement user search and deletion (by display name or ID, with confirmation)
7.7 — Protect all /admin routes; redirect to login if no valid admin session
7.8 — End-to-end TOTP test with a real authenticator app (Google Authenticator, Authy)

Phase 8: PWA and Accessibility (May 18-31, 2026) — Post-MVP

8.1 — Add PWA manifest and service worker for home screen installation
8.2 — Implement offline graceful degradation (show cached list, disable write actions with message)
8.3 — Accessibility pass: contrast ratios, tap target sizes (min 44x44px), aria labels on icon buttons
8.4 — Performance tuning: poster lazy loading, infinite scroll, search debounce, animation on low-end devices

Phase 9: QA and Cross-Device Testing (June 1-21, 2026) — Post-MVP

9.1 — Cross-device testing: iOS Safari, Android Chrome, desktop Chrome/Firefox
9.2 — Group flow end-to-end: create group, join from second device, add movies, roll, mark watched
9.3 — Real-time sync test: verify live updates across two active sessions
9.4 — Recovery code test: create account, simulate new device, recover identity
9.5 — List Admin permissions test: confirm admin-only actions are blocked for regular members
9.6 — Admin self-removal test: trigger "Leave this list" as admin with other members present; confirm Transfer Ownership popup appears with member list and Cancel; confirm original admin is removed (not just demoted) after transfer; confirm list is NOT deleted; confirm that "Delete the list" action does NOT show the Transfer Ownership popup
9.7 — Master Admin test: TOTP login, list/user search and deletion, session protection
9.8 — TMDB rate limit check: confirm debounce and client-side caching stay within free tier limits
9.9 — Landing page test: slot-machine reel animation plays using automatically fetched TMDB posters and lands on a valid movie result; result displays as a static teaser card (poster, title, genres) with no tap/link action; roll buttons work without login; 3-step demo alignment renders correctly on all screen sizes
9.10 — Home page test: returning user lands on home page (not landing page); list cards display correctly; cross-list roll works and result appears as a standalone teaser card on the home page (no navigation into a list); new user with no lists sees empty state
9.11 — Inline panel test: expands below correct row, collapses cleanly, delete two-tap flow works, binoculars overlay and Watched It button update in real time
9.12 — Trailer URL refresh test: confirm background job processes only movies with null trailer_url and updates timestamps correctly; verify movies with existing trailer URLs are not re-processed

Phase 10: Launch (June 22 - July 5, 2026) — Full Feature Complete

10.1 — Final Vercel production deployment and full smoke test
10.2 — Confirm PWA install flows work on iOS and Android
10.3 — Set up basic error monitoring (Vercel logs + Sentry free tier)
10.4 — Soft launch: share with initial test group, gather feedback
10.5 — Address any launch-blocking bugs found during soft launch
10.6 — Full feature complete sign-off by July 5, 2026

9. Success Criteria

A group of 2+ people can go from zero to a shared movie list in under 2 minutes
Rolling the dice produces a result in under 5 seconds (including animation)
Real-time list updates appear on all connected devices within 3 seconds
Genre Roll correctly filters by at least 8 of 10 emotion categories
Recovery code flow successfully restores a user's identity on a new device
Returning users land on their home page (not the landing page) when their user ID is in the browser
Logged-in home page correctly shows all of the user's lists as cards with accurate movie counts
Cross-list roll on the home page draws from all user lists combined and displays the result as a standalone teaser card on the home page without navigating into any list
Admin "Leave this list" with other members present triggers the Transfer Ownership popup; original admin is removed after transfer; list is not deleted; direct "Delete the list" action does not trigger the transfer popup
Master Admin can log in with TOTP (credentials from environment variables) and delete any list or user
Trailer URL refresh job processes only movies where trailer_url is null (bi-weekly cadence)
Landing page slot-machine reel animation uses automatically fetched TMDB posters and lands on a valid movie result displayed as a static teaser card (poster, title, genres) with no tap/link action
Landing page roll buttons work without any login or account creation
App installs to mobile home screen and functions as a PWA
Inline panel expands below the correct grid row with no layout shift
Delete two-tap confirmation does not trigger on a single tap
Watched state toggle (binoculars overlay + button color) updates in real time across all group members' screens
No personal data beyond display name is stored or transmitted

10. Reference: Emotion-to-Genre Mapping

Static mapping used by Genre Roll to translate emotion keywords into TMDB genre IDs. Normalize input to lowercase and tokenize on spaces and commas before matching.

Emotion Keywords	Primary Genres	Secondary Genres
happy, cheerful, upbeat, fun	Comedy, Animation, Family	Adventure, Musical
sad, emotional, cry, tearjerker	Drama, Romance	War, Biography
excited, hyped, energetic, pumped	Action, Adventure	Science Fiction, Thriller
scared, tense, nervous, creepy	Horror, Thriller	Mystery
calm, relaxed, chill, cozy	Documentary, Drama	Animation
romantic, lovey, date night	Romance, Comedy	Drama
thoughtful, reflective, deep	Documentary, Drama	History, Biography
funny, silly, goofy, laugh	Comedy, Animation	Family
dark, gritty, intense, serious	Crime, Thriller	Drama, War
nostalgic, classic, retro	(any genre, filtered to release year < 2000)

Union all matched genre IDs from primary and secondary columns and filter the movie pool. If no tokens match any keyword, notify user with "No matches — showing full list" and proceed with the unfiltered pool.

11. Extra Features

Features added after initial scope. Complete current Implementation Plan progress before starting these.

Feature	Description	Added On	Rationale
Compact list/grid toggle	Toggle between poster grid and a compact list layout (title, year, metadata per row)	2026-04-05	Deferred from MVP — user unfamiliar with it at scoping; low priority relative to core flows

PROJECT_SCOPE.md 34 KB History Raw