They were in that movie. You saw them. Now you can log them.
whererat.com — a spoiler-aware community catalog of rat and rodent cameos in film and TV. Submit sightings, browse by genre or rodent type, and help build the definitive archive of cinema's most underrated cast members.
(\(\
( -.-) whererat.com
o_(")(") spot a rat. log a rat.
- 🎬 Catalog with genre, rodent type, and sort filters
- 🐁 Per-movie pages with sighting carousels and rat-presence visuals
- 🖼️ Spoiler mode — hides title, description, and images until the viewer opts in
- 📝 Public submission flow with image uploads
- 🛡️ Moderator queue with edits, approvals, and audit log
- 📰 News/updates page
- 📱 Native mobile app (Expo Router,
apps/mobile/)
| Layer | Choice | Notes |
|---|---|---|
| Framework | Next.js 16 App Router | Server components by default; "use client" only where interaction requires it |
| UI | React 19 + Tailwind CSS 4 | PostCSS-based; utility classes differ from v3 in some areas |
| Language | TypeScript 5 strict mode | Path alias @/* → src/* |
| Database | Postgres via pg |
Raw SQL only — no ORM. Hosted on Neon |
| Storage | S3 / Vercel Blob / local disk | Controlled by env vars in src/lib/storage.ts |
| Deploy | Vercel via GitHub integration | Auto-deploys from main |
| Package manager | Yarn 4 | Use yarn add, not npm install |
src/app/ Routes, layouts, server actions
src/components/ Shared UI components
src/lib/ Domain helpers, DB, auth, stores
db/ schema.sql + seed data
scripts/ One-off DB/media scripts (run with tsx)
apps/mobile/ Expo Router native app
public/brand/ Logo SVGs
- Node.js LTS
- Access to the Vercel project — all secrets (including
DATABASE_URL) live there
Full environment variable reference: ENVIRONMENT.md.
The app uses a single Neon Postgres database for all environments. There's no local database — pull the connection string from Vercel. Sanity check: GET /api/health/db should return { ok: true } when Postgres is reachable.
# 1. Install dependencies
yarn install
# 2. Pull secrets from Vercel (gives you DATABASE_URL + all other env vars)
vercel env pull .env.local --environment=development
# 3. Start the dev server
yarn dev
# 4. Verify DB connectivity
curl http://localhost:3000/api/health/dbAll environments share the same Neon database — there is no local Postgres instance.
More database notes: db/README.md.
| Script | Purpose |
|---|---|
yarn dev |
Development server |
yarn build |
Production build |
yarn lint |
ESLint (includes jsx-a11y WCAG AA rules) |
yarn typecheck |
TypeScript check (no emit) |
yarn db:schema:apply |
Apply db/schema.sql to DATABASE_URL |
All production deploys are gated by CI.
PR opened
└─ CI runs (lint + typecheck + build)
├─ ❌ fails → merge blocked
└─ ✅ passes → merge to main
└─ Vercel auto-deploys via GitHub integration
Never push directly to main — open a PR and let CI gate the deploy.
- Confirm all env vars are set in Vercel for Production and Preview scopes (see
ENVIRONMENT.md). - Run
yarn db:schema:applyagainst Neon if the schema has changed. - Confirm
BLOB_READ_WRITE_TOKENis set — without it, images are written to ephemeral disk and lost on deploy. - Confirm
GET /api/health/dbreturns{ ok: true }after deploy.
- OMDb (
OMDB_API_KEY) improves movie title search when set. - TMDB (
TMDB_*) improves backdrop/lightbox stills on movie pages.
WhereRat is an open project. Contributions of all kinds are welcome.
Reporting a bug or suggesting a feature
Open an issue at github.com/kuzin/whererat/issues. Please include:
- What you expected vs. what actually happened (for bugs)
- A clear description and motivation (for feature requests)
Submitting a pull request
- Fork the repo and create a branch from
main. - Follow the existing conventions — no ORM, server components by default, raw SQL with parameterized queries.
- Run
yarn lint && yarn typecheckbefore pushing — CI will block merges that don't pass. - Open a PR against
maindescribing what changed and why.
For anything bigger (new features, refactors), open an issue first so we can align before you invest time writing code.
MIT © Mike Kuzin