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, TMDB attribution footer, privacy policy link. Roll result card emerges in the carousel center and stays settled until next user action. Result card has an "i" info button that opens a MoreInfoModal (plot, Add to list → /login, Watch Trailer).	Must Have
Anonymous auth via Supabase	User picks a display name and optional avatar color; account created via `supabase.auth.signInAnonymously()` which issues a JWT for RLS-compatible sessions; persisted on device via `@supabase/ssr` cookie-based session handling	Must Have
Recovery code	A 24-character alphanumeric code (128-bit entropy) shown once after account creation that lets users reclaim their identity on a new device; hashed with Argon2id (memory=19456 KiB, iterations=2, parallelism=1, output=32 bytes) before storage; single-use (invalidated after successful claim); claim endpoint rate-limited (5 failed attempts per IP per 15-minute window)	Must Have
Group creation with invite code	Creator gets a short human-readable code in WORD-WORD format (e.g., WOLF-MOON; word list: 2,000+ words, 3-8 characters each, offensive/confusing terms filtered, uppercase display, case-insensitive comparison, collision check on generation) 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; join endpoint rate-limited (5-10 failed attempts per IP per 15-minute window); group join is a server-side operation via service role key (not client-side INSERT)	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 via server-side API proxy (`/api/tmdb/*`) with debounce (~300ms); all calls set `include_adult=false`; 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, using TMDB native sized URLs) with title below and meaningful `alt` text; 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; announce filter state change via `aria-live="polite"` region	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; announce result via `aria-live="polite"` region	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. Announce state change via `aria-live="polite"` region.	Must Have
Real-time list sync	Add, remove, and watched-status changes appear live on all connected group members' screens (Supabase real-time); subscribe only to the currently-viewed list, unsubscribe on navigation away	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 via Node.js cron container 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 (deletion must remove both `public.users` row and `auth.users` record via `supabase.auth.admin.deleteUser()`); credentials set via environment variables; session managed via iron-session v8 (HttpOnly, Secure, SameSite=Strict cookie, 8-hour expiry)	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
   NOTE: src/app/page.tsx was a duplicate stub that shadowed (public)/page.tsx; removed (2026-05-02).
   The canonical landing is src/app/(public)/page.tsx; TMDBFooter is mounted in (public)/layout.tsx.
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 poster images sourced from the landing_reel_posters table
      (populated by seed.sql; cron refresh is a pending TODO — see 5.2).
      The /api/tmdb/reel-posters route currently fetches TMDB live on each request and ignores the
      table; PINNED_REEL_POSTERS constant always prepends hard-coded entries (e.g., tmdb_id 615).
      Reel posters use aria-hidden (decorative during animation).
      TWO DISTINCT POOLS — do not conflate:
        - Carousel/reel posters: landing_reel_posters table + PINNED_REEL_POSTERS fallback (curated)
        - Roll the Dice result: live /api/tmdb/popular?page=N, random page 1–50 (~1000-movie pool)
   b. Reels decelerate and snap so the midpoint of a gap between two posters lands at viewport center.
      Result is a single movie drawn from /api/tmdb/popular?page=N (random page 1–50; pool ~1000 movies).
      The result is NOT constrained to the reel poster set.
      KNOWN BUG (U9): modulo wrap missing in spinning branch causes scroll offset to drift on
      repeated rolls; fix tracked in research/PHASE5_UI_FIXES_PLAN.md U9.
   c. Result TeaserCard (~1.3x reel poster size) emerges with an animate-emerge keyframe
      (scale 0 → 1.08 → 1, ~500ms, bouncy easing) in the carousel center — posters spread ±110px
      at viewport center on settle. Card remains in settled state until the user re-rolls or refreshes
      (no auto-resume timer). Card shows poster (with alt text), title, genres, and an "i" info button.
      Respects prefers-reduced-motion: animation skipped, card appears instantly.
   d. Tapping "i" opens <MoreInfoModal> (src/components/landing/more-info-modal.tsx):
      - Side-by-side layout at sm+ (poster left, content right), stacks on mobile, max-w-5xl/lg:max-w-6xl
      - Shows: title + year, genres, plot (movie.overview)
      - "Add to list" button → navigates to /login (no save-intent flow; user adds manually post-auth)
      - "Watch Trailer" button → lazy-fetches /api/tmdb/movie/[id]/videos, opens trailer
      - a11y: ESC closes, click-outside closes, focus trap, focus restoration on close
      - Uses createPortal to document.body to escape the animate-emerge transformed ancestor
      NOTE: this is a LANDING-ONLY modal for unauthenticated visitors. It is separate from the
      in-app "More Info" button (U5 in research/PHASE5_UI_FIXES_PLAN.md) which targets
      src/components/movies/expanded-panel.tsx and is still TODO.
   e. Animation is user-triggered only and completes within 5 seconds (WCAG 2.2.2)
5. "Genre Roll" button visible — accepts comma-separated genres/emotions, no reel animation;
   result displayed as a static teaser card (poster with alt text, 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)
8. Footer on all pages (mounted in (public)/layout.tsx): TMDB attribution (logo + link + disclaimer),
   privacy policy link

Onboarding (New User)

1. User taps "Login / Get Started" on landing page
2. User enters display name, optionally picks an avatar color
3. Account created via Supabase Anonymous Sign-In (supabase.auth.signInAnonymously());
   JWT issued and managed by Supabase GoTrue; session persisted via @supabase/ssr
   cookie-based handling (createBrowserClient / createServerClient)
4. Recovery code (24 alphanumeric characters, 128-bit entropy) 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-MOON)
      → creator assigned List Admin role → lands on home page (with their new list card shown)
   B. Join → enter invite code → validated (rate-limited, server-side via service role key)
      → member role assigned → lands on home page (with the joined list card shown)

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

1. App checks for valid Supabase Auth session
2. If valid session found → navigate directly to the home page (skip landing page)
3. If no session → 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 no session (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 via server-side proxy (/api/tmdb/search)
   with ~300ms debounce; include_adult=false on all calls
3. Results appear in two sections:
   - Top: movies already in the group's list (labeled "In Your List")
   - Below separator: TMDB search results (server-side filtered by adult field)
4. User taps a TMDB result → movie inserted into DB with poster, genres, title, year,
   trailer URL (fetched from TMDB via server proxy at add-time;
   validated against allowlist: youtube.com, themoviedb.org, imdb.com),
   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, using TMDB native sized URL: w342 for mobile grid)
     with meaningful alt text (e.g., "Movie Title (Year) poster")
   - 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
5. All poster images use native loading="lazy" attribute

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 (TMDB native sized URL: w500) with alt text
   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 (with rel="noopener noreferrer")
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)
   Respects prefers-reduced-motion: if enabled, use a simple fade-in on the winner instead
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. Result announced via aria-live="polite" region for screen readers
6. Tapping Roll again re-rolls from the same eligible pool
7. Tapping "Genre Roll!" opens a text input
8. User enters genres and/or emotions (e.g., "action, excited")
9. App normalizes input, maps emotion keywords to TMDB genre IDs, filters the unwatched pool
10. Same scatter/eliminate animation plays on filtered results
11. If no matches found: "No matches — showing full list" shown, roll proceeds unfiltered
12. 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 → iron-session v8 issues encrypted HttpOnly cookie (8-hour expiry)
   → 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)
     Deletion must remove both public.users row AND auth.users record
     (via supabase.auth.admin.deleteUser() using service role key)
6. Master Admin session is separate from regular user sessions
7. All /admin routes redirect to login if no valid admin session
8. TOTP secret rotation requires redeployment (documented operational constraint)

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.
Inline panel keyboard navigation: Panel must be operable via keyboard: Enter to open, Escape to close, focus moves into panel on open and returns to trigger on close. Use aria-expanded on trigger and role="region" on panel.
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.
Reduced motion: Both animations must respect prefers-reduced-motion. Landing page reel: instant reveal or simple fade-in. In-app roll: fade to winner instead of scatter animation. Full animation remains the default.
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 (via TanStack Query persistence), disable write actions with an explanatory message. Do not queue offline writes.
Accessibility: Sufficient color contrast on poster overlays; tap targets minimum 44x44px; screen reader labels on icon buttons; meaningful alt text on all poster images; aria-live="polite" regions for dynamic status messages (roll results, filter changes, watched state toggles, action confirmations).
TMDB API: All TMDB calls routed through server-side proxy (/api/tmdb/*) with include_adult=false. Cache recent search results via TanStack Query with explicit staleTime configuration.

7. Technical Considerations

Tech Stack

Layer	Choice	Notes
Frontend	Next.js (React, App Router)	PWA support; `output: 'standalone'` for Docker
Styling	Tailwind CSS	Mobile-first, fast iteration
Backend / Database	Supabase (self-hosted)	Postgres + real-time subscriptions + GoTrue auth; full Docker stack
Auth	Supabase Anonymous Sign-In via `@supabase/ssr`	`signInAnonymously()` — no email, instant account, JWT for RLS; cookie-based session via `createBrowserClient`/`createServerClient`
Movie Data	TMDB API	Posters, genres, metadata, trailer URLs; all calls via server-side proxy with `include_adult=false`
State Management	TanStack Query (React Query)	Server state sync, caching with explicit `staleTime`, loading states
Admin Sessions	iron-session v8	Encrypted HttpOnly cookie for Master Admin TOTP sessions (use v8 README directly — v7 patterns are incompatible)
2FA (Master Admin)	TOTP via otplib (or equivalent)	Authenticator-app compatible; TOTP secret never exposed client-side
PWA	@serwist/next	App Router compatible, Workbox 7; requires authoring `app/sw.ts` and `tsconfig.worker.json`
Image Optimization	sharp (local assets only)	TMDB posters use native sized URLs from TMDB CDN directly (not next/image)
Background Jobs	Node.js cron container (`node:22-alpine` + `node-cron`)	Runs alongside app in docker-compose; writes to Postgres via service role key
Reverse Proxy	Caddy	HTTPS termination (required for PWA, wss://, secure cookies); persistent volume for TLS certificates
Linting / Formatting	ESLint + Prettier + TypeScript strict	next/core-web-vitals + next/typescript presets; husky + lint-staged pre-commit
Testing	Vitest (unit) + Playwright (E2E)	Unit tests for pure logic and Client Components only (Vitest cannot render RSC); Playwright runs against Docker production stack
Env Validation	t3-env (`@t3-oss/env-nextjs`) with zod	Structural enforcement of server/client env var split at build time
Runtime	Node.js 22 LTS	node:22-slim Docker base image

TMDB Image Strategy

TMDB posters are served directly from TMDB's CDN using native sized URLs — not processed through next/image optimization (which would run sharp in-container and create CPU/memory pressure in Docker). Use these TMDB size variants:

w342 — grid thumbnails (mobile)
w185 — reel animation posters
w500 — expanded inline panel
Add loading="lazy" attribute on all poster <img> tags
Add meaningful alt text on all poster images (e.g., "Movie Title (Year) poster"); spinning reel posters use aria-hidden (decorative)
Reserve next/image for locally-served assets only (logo, icons)
Install sharp as an explicit production dependency for local asset optimization

TMDB Attribution

TMDB Terms of Service require visible attribution on every page: the TMDB logo, a link to themoviedb.org, and the disclaimer "This product uses the TMDB API but is not endorsed or certified by TMDB." Implement as a site-wide footer component. Non-compliance risks API key revocation.

TMDB API Proxy

All TMDB API calls must be routed through Next.js API Route Handlers (/api/tmdb/*). The TMDB_API_KEY environment variable must NEVER use the NEXT_PUBLIC_ prefix — it must remain server-side only. This is a TMDB Terms of Service requirement. The proxy also enables server-side response caching via Cache-Control headers. All calls must set include_adult=false and server-side filter results by the adult field as defense in depth.

Data Model

users

id (UUID, primary key — maps to Supabase Auth UID from signInAnonymously())
display_name (text, CHECK: 1-30 characters, no HTML angle brackets or control characters, Unicode letters allowed)
avatar_color (text, hex)
recovery_code (text, hashed with Argon2id — memory=19456 KiB, iterations=2, parallelism=1, output=32 bytes; 24 alphanumeric characters / 128-bit entropy; single-use)
last_active_at (timestamp — updated on write operations, throttled to once per 24 hours per user; used for 12-month retention policy)
created_at

groups

id (UUID, primary key)
name (text, CHECK: 1-50 characters, no HTML angle brackets or control characters, Unicode letters allowed)
invite_code (text, unique, WORD-WORD human-readable format; word list: 2,000+ words, 3-8 chars each, offensive/confusing terms filtered, uppercase display, case-insensitive comparison, collision check on generation)
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 using TMDB native sizes)
genres (text[], TMDB genre labels)
trailer_url (text, nullable — fetched from TMDB at add-time via server proxy and stored; validated against domain allowlist: youtube.com, themoviedb.org, imdb.com; 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)
metadata_refreshed_at (timestamp, nullable — tracks when title/poster/genres/year were last refreshed from TMDB; used by the monthly metadata refresh job post-MVP)
added_by (FK → users.id, ON DELETE SET NULL)
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

Managed via iron-session v8 encrypted HttpOnly cookies; no database table required. Session expiry: 8 hours. Cookies set with Secure and SameSite=Strict flags.

Row Level Security (RLS)

RLS must be enabled on ALL tables with explicit policies — no permissive catch-all. Supabase's anon key is public by design; RLS is the authorization mechanism. Policies use auth.uid() from the JWT issued by Supabase Anonymous Sign-In. Define policies alongside the schema in Phase 1.2. Key rules:

users: Users can read/update only their own row
groups: Readable by members of the group only
group_members: Readable by members of the same group; joining is a server-side operation via service role key (not client INSERT); deletable by admins or self (leave); UPDATE must prevent role escalation (member cannot set own role to admin)
movies: Full CRUD for members of the owning group only; INSERT WITH CHECK must enforce added_by = auth.uid() (prevent attribution spoofing); UPDATE must prevent changing added_by
landing_reel_posters: Readable by anyone (public); writable only by service role (cron job)

Supabase Realtime also respects RLS — subscriptions are authorized by the same policies.

Database Migrations

Use supabase migration new via the Supabase CLI. All migrations stored in version control. Migrations must be the sole mechanism for schema changes — no ad-hoc SQL in production.

Privacy

No email addresses collected in MVP
Display names only — no real identity data
Recovery codes hashed with Argon2id before storage
Invite codes are the primary access control mechanism for regular users; join endpoint rate-limited
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
Privacy policy page required with the following sections: controller identity, lawful basis per processing activity, data inventory with retention periods (anonymous UUID, display name, group membership, movie preferences, server/container logs with IPs), third-party recipients (TMDB API, Sentry), international transfer basis (Sentry — US servers), full user rights with exercise instructions (access, erasure, portability, objection), children's disclaimer (under-13/under-16), cookie/localStorage disclosure, change notification procedure
Data retention: Inactive accounts (no activity for 12 months) are automatically deleted. Auto-deletion must handle orphaned groups: auto-transfer admin to longest-tenured member; cascade-delete group if last member. added_by FK uses ON DELETE SET NULL to prevent FK violations. Deletion wrapped in a transaction per user. Account deletion must also call supabase.auth.admin.deleteUser(userId) to remove the auth.users record. Users cannot be notified before deletion due to anonymous auth (no email). This is documented in the privacy policy.
TMDB attribution displayed on all pages per Terms of Service
Sentry data sanitization: Configure beforeSend callback to strip UUID path segments from error events; do not call Sentry.setUser() with user identifiers. Disclose Sentry as a third-party processor in the privacy policy.
Container logs: Supabase containers (Kong, GoTrue, PostgREST, Realtime) produce logs containing IP addresses and JWTs. Docker log rotation configured on all containers (max-size: 10m, max-file: 5) to bound retention to ~30 days.

Security Headers

Configure HTTP security headers at the Caddy reverse proxy level (not in next.config.js):

Content-Security-Policy — restrict img-src to image.tmdb.org, connect-src to 'self' for API calls and wss://[deployment-domain] for Supabase Realtime WebSocket (not *.supabase.co — self-hosted routes through own domain)
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Strict-Transport-Security (HSTS) — configured in Caddyfile; start with short max-age (86400) during testing, increase to 2-year production value before launch; do not submit to HSTS preload list until confident
Permissions-Policy
Use Content-Security-Policy-Report-Only during development to identify violations without blocking

Deployment

Self-hosted Docker deployment orchestrated via docker-compose
Next.js app container: multi-stage Dockerfile with node:22-slim, output: 'standalone', non-root user, tini for PID 1 signal handling, .dockerignore; builder stage must install python3 make g++ for argon2 native build (alternative: @node-rs/argon2 with pre-compiled NAPI binaries eliminates node-gyp requirement)
Supabase self-hosted: full Docker stack (Postgres, GoTrue, Realtime, PostgREST, Kong, Studio) using Supabase's official docker-compose configuration adapted for this project
Supabase secret replacement (MANDATORY before first deployment): ALL default secrets must be replaced before the first docker compose up. Defaults are published on GitHub — a default JWT_SECRET allows forging JWTs that bypass all RLS. Replace these as a lockstep set: JWT_SECRET → regenerate both ANON_KEY and SERVICE_ROLE_KEY (they derive from JWT_SECRET); also replace POSTGRES_PASSWORD, DASHBOARD_USERNAME, DASHBOARD_PASSWORD. Consider adding a startup check that refuses to start if default values are detected.
GoTrue configuration: Set GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=true (disabled by default — without it, signInAnonymously() returns 400); disable all other auth methods: GOTRUE_EXTERNAL_EMAIL_ENABLED=false, GOTRUE_EXTERNAL_PHONE_ENABLED=false, all OAuth providers disabled
Network security: Kong ports (8000, 8443) and Postgres port (5432) must be internal to the Docker network only — no host port mapping. Supabase Studio must not be publicly accessible — restrict to 127.0.0.1:3000 or remove from production docker-compose; access via SSH tunnel only. Only Caddy is exposed to the internet.
Reverse proxy: Caddy for HTTPS termination (required for PWA service workers, wss:// Supabase Realtime, and secure cookies); Caddy /data and /config directories must be mounted as persistent named Docker volumes (certificate loss + Let's Encrypt rate limits = up to 1 week downtime); use Let's Encrypt staging endpoint for initial testing
Health check: /api/health endpoint checking Supabase connectivity; used by Docker HEALTHCHECK
Background jobs: Node.js cron container (node:22-alpine + node-cron) running alongside the app in docker-compose; connects to Postgres via SUPABASE_SERVICE_ROLE_KEY; handles landing reel refresh and trailer URL refresh
Database backups: pg_dump backup container in docker-compose running daily with 7-day retention; document restore procedure; test restore before launch
Docker log rotation: All containers must configure Docker logging with max-size: 10m, max-file: 5 to prevent disk exhaustion and bound GDPR log retention
Disk encryption recommendation: Enable full-disk encryption on the Docker host (LUKS or cloud provider equivalent) to protect Postgres volume data at rest
Environment variables required:
- TMDB_API_KEY (server-side only — never NEXT_PUBLIC_)
- NEXT_PUBLIC_SUPABASE_URL — the public Supabase URL (browser client uses this)
- NEXT_PUBLIC_SUPABASE_ANON_KEY — the public anon key (browser client uses this; public by design in Supabase's security model)
- SUPABASE_INTERNAL_URL — Docker internal Kong URL (e.g., http://supabase_kong:8000; server-side Next.js code uses this to avoid routing through Caddy)
- SUPABASE_SERVICE_ROLE_KEY (for server-side admin operations; never exposed client-side)
- 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
- IRON_SESSION_SECRET — 32+ character secret for iron-session cookie encryption
- GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=true — required for anonymous sign-in
All environment variables validated at startup via t3-env (@t3-oss/env-nextjs) with zod; server vars in server block, public vars in client block; missing or malformed variables produce a clear build/startup failure
No first-run setup UI exists; the master admin account is fully configured via environment variables before deployment
CI: Linting, type-checking, and build validation enforced via husky pre-push hook (no external CI platform required)

8. Implementation Plan

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

Phase 1: Foundation (April 6-10, 2026) — MVP

1.1 — Initialize Next.js project with Tailwind CSS, App Router, and output: 'standalone' in next.config.ts; configure TypeScript strict mode, ESLint (next/core-web-vitals + next/typescript), Prettier; set up husky + lint-staged (pre-commit: lint/format, pre-push: lint + typecheck + build); install sharp as production dependency; add Vitest for unit testing (scope: pure logic and Client Components only — Vitest cannot render RSC)
1.2 — Set up self-hosted Supabase Docker stack; replace ALL default secrets before first docker compose up (JWT_SECRET → regenerate ANON_KEY + SERVICE_ROLE_KEY together; replace POSTGRES_PASSWORD, DASHBOARD_USERNAME, DASHBOARD_PASSWORD); configure GoTrue: set GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=true, disable email/phone/OAuth auth methods; create schema (users, groups, group_members, movies, landing_reel_posters tables) with CHECK constraints on display_name and group name; define and enable RLS policies on all tables with WITH CHECK clauses (see RLS section); initialize Supabase CLI migrations workflow — all schema changes via supabase migration new
1.3 — Configure Supabase client in Next.js using @supabase/ssr (createBrowserClient for browser, createServerClient for server-side with SUPABASE_INTERNAL_URL); implement env var validation at startup via t3-env (@t3-oss/env-nextjs) with zod — server vars in server block, client vars in client block; create TMDB API proxy route (/api/tmdb/*) to keep API key server-side; set include_adult=false on all TMDB calls
1.4 — Implement anonymous auth via supabase.auth.signInAnonymously(); display name input and optional avatar color picker; session managed by Supabase GoTrue via @supabase/ssr cookie-based handling (JWT issued automatically); verify GoTrue returns 200 (not 400) — confirm GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=true is set
1.5 — Implement recovery code generation (24 alphanumeric characters, 128-bit entropy), Argon2id hashing (explicit OWASP parameters: memory=19456 KiB, iterations=2, parallelism=1, output=32 bytes — do not use library defaults), and show-once display screen
1.6 — Implement recovery code claim flow (enter code → verify against Argon2id hash → restore identity on new device); rate-limit claim endpoint (5 failed attempts per IP per 15-minute window); invalidate code after successful claim
1.7 — Build Docker infrastructure: multi-stage Dockerfile (node:22-slim, non-root user, tini; builder stage installs python3 make g++ for argon2 native build), docker-compose.yml orchestrating Next.js app + self-hosted Supabase stack + Caddy reverse proxy + Node.js cron container + pg_dump backup container (daily, 7-day retention), .dockerignore, /api/health endpoint; network security: Kong/Postgres ports internal only, Studio restricted to 127.0.0.1; Caddy persistent volumes for /data and /config (TLS certificates); Docker log rotation on all containers (max-size: 10m, max-file: 5); use Let's Encrypt staging for initial testing; deploy and confirm Supabase connection works in production
1.8 — Add Sentry error monitoring (free tier); configure beforeSend to strip UUID path segments from error events; do not call Sentry.setUser() with user identifiers

Phase 2: Groups and Permissions (April 10-14, 2026) — MVP

2.1 — Build "Create a Group" flow: name input (validated: 1-50 chars), invite code generation (WORD-WORD format; word list: 2,000+ words, 3-8 chars, offensive terms filtered, collision check), store in DB, assign creator as List Admin; document API routes in markdown
2.2 — Build "Join with a Code" flow: code entry, validation via server-side route handler using service role key (not client-side INSERT), group_members record with role: 'member'; rate-limit join endpoint (5-10 failed attempts per IP per 15-minute window); document API routes in markdown
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 + film emoji 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); use polling (not real-time subscriptions) for home page movie counts
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 14-20, 2026) — MVP

3.1 — Integrate TMDB API via server-side proxy (/api/tmdb/*): search endpoint with include_adult=false and server-side adult field filtering, poster URL construction using TMDB native sizes (w342 grid, w185 reel, w500 expanded), trailer URL fetch at add-time; implement TanStack Query caching with explicit staleTime configuration; document API routes in markdown
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 via server proxy at add-time; validated against domain allowlist: youtube.com, themoviedb.org, imdb.com), trailer_url_refreshed_at, and added_by attribution; document API routes in markdown
3.4 — Build 2-column poster grid: full-bleed poster using TMDB native sized URLs (w342) with loading="lazy" and meaningful alt text (e.g., "Movie Title (Year) 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 at w500 with alt text → 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 with rel="noopener noreferrer"; collapse on tap outside
3.7 — Implement genre filter: tapping a genre tag in the inline panel filters the grid to that genre; announce filter state change via aria-live="polite" region
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; announce state change via aria-live="polite" region
3.9 — Enable Supabase real-time subscriptions on movies table for live add, remove, and watched-status updates; subscribe only to the currently-viewed list (subscribe on mount, unsubscribe on unmount via useEffect cleanup); implement exponential backoff on reconnection

Phase 4: Randomizer (April 20-23, 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; announce result via aria-live="polite" region
[~] 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; respect prefers-reduced-motion (use simple fade-in on winner when enabled)
[~] 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 mapping as a static TypeScript constant (see Section 10 reference table); translate genre labels to TMDB numeric genre IDs
[~] 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. NOTE: home-view Genre Roll swapped to filterByGenresAndEmotionsStructured (2026-04-14) — fixes genre-only rolls silently discarding the filter when movies.genres stores TMDB names, not numeric IDs.
[~] 4.8 — Apply roll animation to genre-filtered results; document API routes in markdown

Phase 5: Landing Page and MVP Polish (April 23-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); add site-wide footer with TMDB attribution (logo + link + disclaimer) and privacy policy link; build privacy policy page with required sections (controller identity, lawful basis, data inventory, third-party recipients including Sentry, international transfers, user rights, children's disclaimer, cookie/localStorage disclosure, change notification procedure). NOTE (2026-05-02): Hero, Carousel, About, HowItWorks, Login link, and TMDBFooter all present in src/app/(public)/page.tsx + (public)/layout.tsx. Duplicate stub src/app/page.tsx removed so (public)/page.tsx is no longer shadowed.
[~] 5.2 — Build and seed landing_reel_posters table; implement periodic refresh job in the Node.js cron container on bi-weekly cadence that automatically fetches ~20 posters from TMDB popular or top-rated endpoints (with include_adult=false) and replaces the full set in the DB on each run. NOTE (2026-05-02): Table exists and is populated by seed.sql. PINNED_REEL_POSTERS constant in the API route always prepends hard-coded entries (e.g., tmdb_id 615 "The Passion of the Christ"). OUTSTANDING: cron/index.ts reel-refresh handler is still a TODO — the /api/tmdb/reel-posters route currently fetches TMDB live on each request and ignores the DB table. Cron wiring is the remaining gap for this task.
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 (using w185 size, aria-hidden on spinning posters), decelerate, and land on a single TMDB movie result with alt text (the final result is fetched live from TMDB via server proxy — not constrained to the reel poster set); animation is user-triggered only and completes within 5 seconds (WCAG 2.2.2); respect prefers-reduced-motion (instant reveal or simple fade-in when enabled). NOTE (2026-05-02): Continuous carousel and slot-machine spin on roll are implemented. KNOWN BUG (U9): modulo wrap missing in spinning branch causes scroll offset to drift on repeated rolls; fix tracked in research/PHASE5_UI_FIXES_PLAN.md. NOTE (2026-05-02 dea71d9/0061375): Roll result card now emerges inside the carousel center via animate-emerge keyframe (scale 0→1.08→1, ~500ms, bouncy, skipped under prefers-reduced-motion); snap math positions midpoint of a gap at viewport center so card sits in a symmetric slot; posters spread ±110px on settle. Card stays settled until user re-rolls or refreshes (RESUME_DELAY auto-resume timer removed). TeaserCard reduced to ~1.3x reel poster size. "i" info button on TeaserCard opens (src/components/landing/more-info-modal.tsx) with title+year, genres, plot, Add to list (→ /login, no save-intent), Watch Trailer (lazy-fetches /api/tmdb/movie/[id]/videos); mirrors GenreRollModal a11y pattern; uses createPortal to escape the transformed ancestor. IMPORTANT: this landing MoreInfoModal is distinct from the in-app U5 "More Info" button targeting src/components/movies/expanded-panel.tsx — U5 is still TODO.
5.3a — Wire landing page Roll the Dice to TMDB via /api/tmdb/popular?page=N (random page 1–50, pool ~1000 movies). Result displayed as a static teaser card (poster with alt text, title, genres) — no link, no tap action. NOTE: this is a distinct pool from the carousel reel — see Feature Flow section 5 for the two-pool distinction.
5.4 — Wire landing page Genre Roll to TMDB via server proxy (no login required); display result as a static teaser card showing poster (with alt text), 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 — Configure HTTP security headers in Caddyfile: CSP (with self-hosted URLs, not *.supabase.co), X-Frame-Options, X-Content-Type-Options, Referrer-Policy, HSTS (start with max-age=86400, increase before launch), Permissions-Policy; use Report-Only mode during testing
5.8 — Final MVP smoke test and Docker production deployment
5.9 — Implement user-facing sign-out. SHIPPED (2026-05-02, commits 44ff76c→582a7fd→add8745): POST /api/auth/signout calls supabase.auth.signOut() server-side and returns Set-Cookie clears; GET/POST /logout is a redirect-to-/ alias for manual/debug links. <SignOutButton /> (src/components/auth/sign-out-button.tsx) placed in the (app) layout header — no avatar/menu. On click: calls API, clears TanStack Query cache, hard-navigates to /. No confirmation dialog (decided: anonymous-account warning is deliberately omitted; click = signed out). Distinct from /api/admin/logout (iron-session). No Clear-Site-Data header (no service worker yet). persistQueryClient cleanup deferred to Phase 8.

DEV-ENV QUIRK — cookie-name pinning: SUPABASE_INTERNAL_URL and NEXT_PUBLIC_SUPABASE_URL may differ in dev (different hostnames). The Supabase SDK derives the session cookie name from the URL, so each side silently derived a different name, making signOut/getUser no-ops. Fixed by pinning cookieOptions.name to a value derived from NEXT_PUBLIC_SUPABASE_URL in src/lib/supabase/cookie-name.ts. Any new createServerClient call must include this cookieOptions.name — see also CLAUDE.md.

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

6.1 — Implement background trailer URL refresh job in Node.js cron container: query movies where trailer_url IS NULL (bi-weekly cadence); fetch trailer URL from TMDB via server proxy for each; validate against domain allowlist; 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 — Configure Node.js cron container scheduling; confirm jobs run reliably in production
6.3 — Add monitoring/logging for refresh failures (e.g., TMDB returned no trailer) so missing URLs can be investigated
6.4 — Implement monthly TMDB metadata refresh job: query movies where metadata_refreshed_at is older than 30 days (or NULL); refresh title, poster_path, genres, year from TMDB; update metadata_refreshed_at. Ensures TMDB ToS compliance for cached data freshness.

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; document that TOTP secret rotation requires redeployment
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 via iron-session v8 (encrypted HttpOnly cookie, Secure, SameSite=Strict, 8-hour expiry); use v8 README directly — v7 patterns are incompatible
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); deletion must remove both public.users row AND auth.users record (via supabase.auth.admin.deleteUser() using service role key)
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 via @serwist/next for home screen installation; requires authoring app/sw.ts, tsconfig.worker.json (WebWorker lib), and public/manifest.json with required fields and icon sizes (192x192, 512x512, maskable variants); budget a half-day
8.2 — Implement offline graceful degradation: cached list data via TanStack Query persistQueryClient (IndexedDB; requires @tanstack/react-query-persist-client, @tanstack/query-async-storage-persister, idb-keyval), disable write actions with message; do not queue offline writes; budget 2-4 hours including serialization testing
8.3 — Accessibility pass: contrast ratios, tap target sizes (min 44x44px), aria labels on icon buttons; inline panel keyboard navigation and focus management (Enter to open, Escape to close, focus trap on open, focus return on close, aria-expanded on trigger, role="region" on panel); verify alt text and aria-live regions added in Phases 3-5 are correct
8.4 — Performance tuning: poster lazy loading verification, infinite scroll performance, search debounce, animation on low-end devices; consider virtualized scrolling (@tanstack/react-virtual) if grid performance degrades with large lists

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; verify subscription cleanup on navigation
9.4 — Recovery code test: create account, simulate new device, recover identity; verify rate limiting on claim endpoint; verify code invalidation after use
9.5 — List Admin permissions test: confirm admin-only actions are blocked for regular members via RLS
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, iron-session v8 cookie validation, list/user search and deletion (verify both public.users and auth.users records removed), session protection and expiry
9.8 — TMDB rate limit check: confirm debounce and TanStack Query caching stay within rate limits; verify TMDB API key is not exposed in client-side code or network requests; verify include_adult=false on all calls
9.9 — Landing page test: slot-machine reel animation plays using automatically fetched TMDB posters and lands on a valid movie result; result TeaserCard emerges in carousel center and stays settled until re-roll; "i" button opens MoreInfoModal with plot, Add to list (→ /login), and Watch Trailer; roll buttons work without login; 3-step demo alignment renders correctly on all screen sizes; TMDB attribution footer visible; privacy policy accessible and contains all required sections
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; keyboard navigation works (Enter/Escape, focus management)
9.12 — Background job test: confirm Node.js cron container runs trailer URL refresh (null-only) and metadata refresh correctly; verify URL domain validation; verify no adult content in reel posters
9.13 — Security headers test: verify CSP, HSTS, X-Frame-Options are correctly applied on all routes; verify CSP uses self-hosted URLs (not *.supabase.co)
9.14 — RLS test: verify unauthorized access attempts are blocked at the database level (attempt direct Supabase queries outside group membership); verify WITH CHECK prevents added_by spoofing and role escalation
9.15 — Invite code rate limiting test: verify brute-force protection on join endpoint
9.16 — Run Playwright E2E tests against Docker production stack for critical paths: onboarding flow, add movie + real-time sync, roll the dice
9.17 — Data retention test: verify inactive account cleanup job correctly identifies and deletes accounts inactive for 12+ months; verify orphan group handling (admin transfer or cascade delete); verify auth.users record removal
9.18 — Docker security test: verify Kong/Postgres ports not accessible from host; verify Studio not publicly accessible; verify all default Supabase secrets have been replaced; verify Caddy TLS certificates persist across container restart
9.19 — Backup test: verify pg_dump backup runs daily; test restore procedure
9.20 — Sign-out test: verify sign-out clears the Supabase session cookie and redirects to landing page; verify signed-out user cannot access authenticated routes; verify sign-out control is distinct from /api/admin/logout; confirm no anonymous-account warning dialog appears (per 5.9 decision). NOTE: manual click-through verification was performed against the dev server in the 5.9 implementation round; no automated Playwright e2e test was added. This task remains open until automated coverage is in place.

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

10.1 — Final Docker production deployment and full smoke test
10.2 — Confirm PWA install flows work on iOS and Android
10.3 — Verify Sentry error monitoring is capturing errors correctly (with UUID sanitization); review and resolve any outstanding issues
10.4 — Soft launch: share with initial test group, gather feedback
10.5 — Address any launch-blocking bugs found during soft launch
10.6 — Promote HSTS max-age to production value (2 years)
10.7 — 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
Recovery code claim endpoint blocks after 5 failed attempts per IP
Returning users land on their home page (not the landing page) when a valid Supabase session exists
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 (both public.users and auth.users records); session expires after 8 hours
Trailer URL refresh job processes only movies where trailer_url is null (bi-weekly cadence)
Monthly metadata refresh job keeps cached TMDB data current (TMDB ToS compliance)
Landing page roll result TeaserCard emerges in the carousel center, stays settled until re-roll, and the "i" info button opens a MoreInfoModal with plot, Add to list (→ /login), and Watch Trailer
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
Inline panel is fully operable via keyboard (Enter/Escape, focus management)
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
TMDB API key is not exposed in any client-side code or network request
TMDB attribution is visible on all pages
RLS policies prevent unauthorized data access at the database level; WITH CHECK prevents column spoofing
All animations respect prefers-reduced-motion preference
Inactive accounts are automatically deleted after 12 months with correct orphan group handling
Security headers (CSP with self-hosted URLs, HSTS, X-Frame-Options) are correctly applied
Invite code join endpoint is rate-limited against brute force
Docker deployment runs with non-root user, health check, and no exposed internal ports
All default Supabase secrets have been replaced before production deployment
Supabase Studio is not publicly accessible
Database backups run daily with successful restore verification
Sentry error events do not contain user UUIDs
Privacy policy contains all required GDPR/CCPA sections
User-facing sign-out clears the session cookie and redirects to the landing page; signed-out users cannot access authenticated routes

10. Reference: Emotion-to-Genre Mapping

Static mapping used by Genre Roll to translate emotion keywords into TMDB genre IDs. Implemented as a static TypeScript constant. 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
Self-service account deletion	User-facing account deletion flow with cascading deletes (wrapped in transaction), ownership transfer for administered groups (auto-transfer to longest-tenured member), anonymization of added_by references (ON DELETE SET NULL), and removal of auth.users record via `supabase.auth.admin.deleteUser()`	2026-04-06	GDPR Article 17 (Right to Erasure); MVP relies on Master Admin deletion on request as interim

PROJECT_SCOPE.md 78 KB Histórico Raw