Project Overview

ShowTrackr

A private TV show tracker: search TMDB, build a personal library, track watched episodes, resume what you opened most recently, and jump straight to the likely Reddit discussion thread.

Purpose

ShowTrackr is a private TV show tracker built with Next.js 14, TypeScript, and Tailwind CSS, backed by TMDB for metadata, Supabase for auth and Postgres sync, and Upstash Redis for rate limiting.

Features

Core capabilities as described in the project README.

Library & Progress

  • Personal show library with Watching, Up next, Finished, and New statuses
  • Continue Watching section sorted by last-viewed time
  • Per-episode watched state plus a "Mark season watched" action

Metadata & Discovery

  • TMDB-powered search, show details, seasons, episode metadata, posters, and stills
  • Reddit discussion shortcuts that search the likely subreddit, with manual per-episode thread URL overrides

Auth & Sync

  • Supabase Google OAuth sign-in with owner email/password fallback for cross-device sync
  • Browser localStorage fallback when Supabase is not configured or the user is signed out

Access Control & Ops

  • Optional site-wide passcode gate backed by an HTTP-only HMAC cookie
  • Upstash-backed rate limiting for passcode attempts and TMDB proxy routes
  • Vercel Analytics

Architecture

How search, auth, and sync fit together.

Search & TMDB proxy

Search requires a signed-in Supabase user. The browser passes the Supabase access token to /api/tmdb/search, which verifies it server-side before calling TMDB. Show detail and season routes are also proxied through server routes so the TMDB API key stays server-only.

Local-first sync

Library, progress, and Reddit override hooks in lib/store.ts read and write localStorage. Signed-in users sync the same data to Supabase; if remote tables are empty but local data exists, the local data is imported into Supabase on first sync.

Passcode gate

Optional. When SITE_PASSWORD is set, middleware.ts redirects unauthenticated visitors to /gate. Successful entry sets an HTTP-only st_gate cookie containing an HMAC token, not the passcode itself.

Tech Stack

From package.json dependencies.

Layer Technology
Framework Next.js 14.2, React 18.3, TypeScript
Styling Tailwind CSS 3.4, PostCSS, Autoprefixer
Auth & Data Supabase (Auth + Postgres), @supabase/supabase-js
Rate Limiting Upstash Redis + @upstash/ratelimit
Metadata Source TMDB API (server-proxied)
Analytics Vercel Analytics
Deployment Vercel

Main Commands

From package.json scripts.

npm run dev      # Start the local Next.js dev server
npm run build    # Build and run Next.js type/build checks
npm run start    # Serve a production build
npm run lint     # Run Next.js ESLint

There is no automated test runner configured yet. The README states npm run lint and npm run build are the current verification baseline.

Setup Notes

Key points from the README's setup and deployment sections.

Environment

  • Requires a TMDB v3 API key and a Supabase project (schema in supabase/schema.sql)
  • Google OAuth and email/password auth must be enabled in Supabase Auth settings; the app has no public signup
  • Copy .env.example to .env.local and fill in keys before running locally

Secrets Boundary

  • TMDB_API_KEY, SITE_PASSWORD, KV_REST_API_URL, and KV_REST_API_TOKEN are server-side only
  • NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY are browser-exposed by design
  • .env.local and any service-role keys must never be committed

Structure

Top-level layout, from the README's project structure.

app/
  page.tsx                    Home page: Continue Watching + library
  show/[id]/page.tsx          Show detail, season tabs, episode list
  gate/page.tsx                Passcode form
  api/gate/route.ts            Passcode verification + gate cookie
  api/tmdb/search/route.ts     Authenticated TMDB search proxy
  api/tmdb/show/[id]/route.ts  TMDB show-detail proxy
  layout.tsx                   Root layout, AuthProvider, analytics

components/                    AuthButton, NavBar, SearchModal, ShowCard,
                                ContinueWatchingSection, SeasonTabs,
                                EpisodeRow, RedditButton

lib/                           auth.tsx, supabase.ts, supabase-server.ts,
                                store.ts, tmdb.ts, reddit.ts, progress.ts,
                                gate.ts, rate-limit.ts, types.ts

supabase/
  schema.sql                   Sync tables, grants, and RLS policies

Deployment

Per the README's deployment notes.