MOVIENIGHT

Challenge 01

Real-time rooms over a single WebSocket

Multiple users in a pick event need to see each other join, watch nominations land, see ready states flip, and watch a winning movie reveal at the same instant. Polling would be wasteful and would still feel laggy. Long-lived connections needed careful lifecycle handling for joins, leaves, reconnects, and the moment a result is decided.

Solution

One WebSocket connection per pick event. Server validates every C2S message, applies the state change against Postgres, and broadcasts the updated snapshot to everyone in the room. Engine-specific messages (battle rounds, ranked submissions, rolling random finalize) live alongside core room messages without leaking through the type system.

Challenge 02

Endless decider engines, one room

The room had to support more than one way to decide. A single random draw is fast but flat. A bracket battle is more fun but takes longer. Ranked voting reads everyone's preference order. Two-player rolling random changes the pool every round. Each mode has its own rules, its own messages, and its own UI state.

Solution

Each engine is its own module behind a shared interface. Engine-specific WebSocket messages live in separate type files so the core room never has to know what "rolling_random:finalize" means. Engine config is stored as opaque JSON on the event row and only read by the engine that owns it.

Challenge 03

Long-running AI agent over HTTP

The recommender service runs a ReAct agent that chains many tool calls — catalog searches, local library lookups, viewing-history scans. Single runs can legitimately take several minutes. Node's default fetch caps both headers and body at five minutes, which surfaces as 502s or 504s right when the agent is about to land an answer.

Solution

A dedicated undici Agent with a ten-minute headers and body timeout, mirrored on the Node HTTP server. The Recommender call is wrapped in a helper that surfaces useful cause information (ECONNREFUSED, DNS, AggregateError walking) instead of the generic "fetch failed" error you get from undici by default.

Challenge 04

Catalog hydration cost vs. freshness

Hitting the upstream catalog on every page render would burn quota fast and add latency for the user. But cached entries go stale: posters get updated, ratings drift, a movie gets a new tagline. The catalog needed to feel canonical without paying the upstream cost on every request.

Solution

Stale-while-revalidate caching keyed on a canonical id, with a one-day TTL and a seven-day stale window. The cache serves the last-known-good response immediately and revalidates in the background. Hot endpoints get wrapped in a cache helper; long-tail endpoints fall back to direct fetches with a shorter TTL.