Imported from PostCredits/postcredits-web (AGENTS.md). Install upstream with npx skills add PostCredits/postcredits-web. Copyright stays with the author.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Product Concept

PostCredits is a social app for movie "book clubs": a group picks a movie, everyone watches it within a set window, then rates/reviews it and reacts/comments on each other's reviews.

Terminology mapping — the concept doc below uses product language; the API uses different nouns:

• "Group" → Studio
• "Session" → Feature
• Everything else (reviews, comments, reactions) maps 1:1.

Auth

• Sign up with email + unique username + password; log in with username/password.
• Forgot-password flow sends a new password to the account's email. Not yet built — no endpoint exists for this (see API gotchas below).

Joining a Group

• Public groups: join freely.
• Private groups: request to join (approval flow — not yet built, no join-requests endpoint).
• Search public groups by name, member, or description keywords.
• Private/unlisted groups: join via invite code from an existing member.

Group Creation / Admin Privileges

Creator becomes admin. Admins can, at any time:

• Set name and description.
• Toggle privacy: public / private / unlisted.
• Invite members via code.
• Set selection method: rotation vs. voting.
• Set session length and movie-selection-phase length.
• Kick members. Not yet built — no endpoint exists for this yet (see MVP punch list below).

Movie Selection — General

Search movies by title, director, or starring actor. Before submitting/nominating, users can preview title, poster, IMDB rating, genre, director, starring actors, trailer link.

Movie Selection — Rotation

• Fixed member order, defaulting to join order; admin can reorder.
• At the end of a session, the next member in line submits the movie for the following session.

Movie Selection — Voting

• Two phases after a session ends: nomination (each member submits exactly one movie, including themselves) then voting (ranked-choice; top 3 get 5/3/1 points).
• During voting, members can view each nominee's details but not who submitted it.
• Highest point total wins; results and per-movie point values are viewable after the vote closes.

Submitting a Review

• Rating: 0–5 stars in 0.5 increments. A guiding phrase appears above the star picker to anchor the scale:
  • 0.5 "I had to turn it off" · 1.0 "Genuinely awful" · 1.5 "It had a few redeeming qualities… I guess" · 2.0 "Not for me" · 2.5 "Just plain okay" · 3.0 "I liked it, but wouldn't rewatch" · 3.5 "It was pretty good" · 4.0 "I loved it!" · 4.5 "Near perfection" · 5.0 "One of my favorite movies ever"
• Optionally pick 0–5 liked tags and 0–5 disliked tags (no overlap) from the fixed reviewTag enum (plot, beginning, middle, end, writing, characters, performances, cinematography, costume_design, set_design, score, soundtrack, sound_design, editing, visual_effects).
• Optional free-form written review.
• Reviews can only be submitted/edited while the session window is open.

Interacting with Reviews

• During the session, members view each other's reviews, comment, react with emoji, and can @-tag users in comments.
• Comments remain possible after the session ends, even though reviews themselves lock.

Viewing Groups

• Group page shows name + description; clicking a group opens its current session by default.
• Past sessions are browsable by date range + movie selected, and their reviews remain viewable/interactive.
• Each group also has a standing group chat, independent of session state, always available. Not yet built — no chat endpoint exists.

MVP Punch List

What's left before opening to production. Enhancements (mentions, voting-method studios, rotation reordering, editing studio settings post-creation, forgot-password, private-studio join-requests, chat, notifications) are explicitly deferred — not blockers.

• Leave studio — backend endpoint POST /studios/:studioId/leave already exists; no frontend UI calls it yet. In progress (backend work).
• Kick members — no backend endpoint yet. Plan: unify with leave under a single DELETE /studios/:studioId/members/:userId route — if userId matches the caller it's a self-leave (no special permission needed), otherwise the caller must be admin. Same "can't remove the last admin" guard applies either way. Once built, add frontend UI (admin-only kick action on the members list) and retire/redirect the old POST /studios/:studioId/leave route if replaced.

Design / Styling

Color scheme is dark mode: blacks and greys as the base palette, white text, red as the accent color. The CSS is already set up to accommodate this — match new components/styles to it rather than introducing other palettes.

Backend API Reference

Express app. All routes mounted at /studios except authRouter (/auth). Auth is a JWT Bearer token in the Authorization header, populating req.user. All routes require auth except: GET /health, POST /auth/register, POST /auth/login.

Error shape: { message: string } for 400/403/404/409/500, or { message: "Invalid request", errors: ZodIssue[] } for validation failures (400). 401 { message: "Unauthorized" } for missing/bad auth.

Gotchas:

• rating comes back as a string (Postgres numeric), e.g. "3.5", not a JS number — parse before doing math/comparisons.
• Private studios return 404 (not 403) to non-members on GET /studios/:studioId — deliberate, avoids leaking existence.
• POST /studios/:studioId/join only works for privacy: "public" studios; private/unlisted studios are joined via POST /studios/join with an invite code instead.
• No endpoints exist yet for: nominations, voting, vote-choices, chat, join-requests, notifications, kick-member — even though the DB tables exist for some of these. Don't build frontend against these until they ship.
• Movie search now exists (GET /movies?q=) and is wired up in the select-movie flow — the note above only applies to the remaining list.

Misc

Auth (/auth)

PublicUser = { id, username, email, firstName, lastName, createdAt }

Studios (/studios)

Features

Status enum: nomination \| voting \| selecting \| reviewing \| completed

Reviews

reviewTag enum: plot, beginning, middle, end, writing, characters, performances, cinematography, costume_design, set_design, score, soundtrack, sound_design, editing, visual_effects

Comments

Reactions

reactionType enum: thumbs_up, thumbs_down, heart, fire, shocked, hundred, laugh, cry, clap, heartbreak