Nimina

Turns app screenshots into animated promo videos, rendered on a canvas in the browser. Next.js on Vercel, Supabase (auth + Postgres), Cloudflare R2 (files), Paddle (billing). Architecture, conventions and every dashboard setting live in CLAUDE.md; this file covers running it and operating it.

Development

cp .env.example .env.local   # fill in values (see comments in the file)
npm install
npm run dev                  # http://localhost:3000
npm run visual-regression    # after any rendering change (see CLAUDE.md rule 6)

Storage limits

Free accounts can store 200 MB of files (screenshots, icons, music), Pro accounts 5 GB (maxStorageBytes in src/lib/plan.ts). The limit is enforced on the server when an upload is approved (/api/storage/upload → public.reserve_storage, migration 0019), so it can't be bypassed from the browser. Usage shows on /account, on /projects and in the editor's slide rail. Deleting a project frees its space immediately; files a project no longer uses (replaced screenshots, deleted slides) are cleaned up an hour after they stop being used, whenever the user's usage is recounted.

After running migration 0019 once, record files that already existed: node --env-file=.env.local scripts/backfill-storage-usage.mjs.

Database backups

Every Sunday at 03:17 UTC, .github/workflows/db-backup.yml:

1. Backs up production with pg_dump (scripts/backup/backup-db.mjs) to the private R2 bucket nimina-backups, under weekly/<YYYY-MM-DD>/:

   • data.sql.gz: every row of every table in public and auth (users, sign-in identities, projects, billing records, …);
   • public-schema.sql.gz: our schema exactly as it was in production;
   • supabase-schemas.sql.gz: Supabase's own auth/storage schemas, used only by the restore check below;
   • manifest.json: row count and content checksum of every table, taken in the same database snapshot as the dump.

   It keeps the newest 8 backups and deletes older ones.

2. Proves the backup restores (scripts/backup/verify-backup.mjs). It downloads the backup it just uploaded, runs the restore procedure below into a throwaway Postgres 17, and compares every table's row count and contents with the manifest. Any difference fails the run, and GitHub emails the repo owner. The result is saved next to the backup as verify.json. It also reports drift, meaning any difference between production's schema and what supabase/migrations/ builds.

Run it on demand: GitHub → Actions → Database backup → Run workflow. See what you have: node --env-file=.env.local scripts/backup/fetch-backup.mjs --list.

Not in the backup: uploaded files (they're in R2, not the database), and Supabase dashboard settings (auth providers, email templates, SMTP, URL configuration; see CLAUDE.md "Accounts & sign-in").

Restoring a backup

Restoring means loading the data into a new Supabase project and pointing the app at it. You need the PostgreSQL 17 client tools (psql) and the Supabase CLI.

1. Download the backup. This checks the files' checksums:

   node --env-file=.env.local scripts/backup/fetch-backup.mjs --date=2026-10-04 --out=./restore
   

   Leave out --date to get the newest. You can also download the files from Cloudflare (R2 → nimina-backups → weekly/<date>/).
2. Create a new Supabase project in the same region. Copy its connection string from Connect → Session pooler (port 5432) into a variable:

   export NEW_DB_URL='postgresql://postgres.<new-ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres'
   

3. Build the schema from the migrations:

   supabase link --project-ref <new-ref>
   supabase db push
   

4. Empty the tables the migrations seeded, so the backup's rows don't collide with them:

   psql "$NEW_DB_URL" -v ON_ERROR_STOP=1 -c "do \$\$ declare t text; begin for t in select format('%I.%I', schemaname, tablename) from pg_tables where schemaname = 'public' loop execute 'truncate ' || t || ' cascade'; end loop; end \$\$;"
   

5. Load the data. Triggers and foreign-key checks are switched off while loading, so rows can arrive in any order and the signup trigger doesn't create duplicate profiles:

   gunzip -c restore/data.sql.gz | PGOPTIONS='-c session_replication_role=replica' psql "$NEW_DB_URL" -v ON_ERROR_STOP=1 --quiet
   

6. Check the restore against the backup. Every table should print ok:

   node scripts/backup/check-restore.mjs --manifest=restore/manifest.json --db="$NEW_DB_URL"
   

7. Point the app at the new project:
   • Set NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY and SUPABASE_SERVICE_ROLE_KEY to the new project's values, both in Vercel and in .env.local, then redeploy.
   • Set SUPABASE_DB_URL (GitHub secret) to the new project.
   • Redo the dashboard settings in CLAUDE.md "Supabase setup" and "Accounts & sign-in": auth providers, Google OAuth redirect, email templates, SMTP, URL configuration, manual linking.
   • Users keep their accounts and passwords. Everyone has to sign in again, because sessions don't carry over to a new project.

The weekly check runs steps 3–6 against a stand-in project, so a green run means this exact procedure works on that week's data.

One-time setup

1. Cloudflare R2: create a bucket nimina-backups (private, no public URL). Then create an API token with Object Read & Write limited to that one bucket. Don't reuse the app's token: the app should never be able to read the backups.
2. Supabase: Connect → Session pooler connection string, using the database password. The direct db.<ref>.supabase.co host is IPv6-only, and GitHub's runners can't reach it.
3. GitHub → repo → Settings → Secrets and variables → Actions → New repository secret:
   • SUPABASE_DB_URL (the session pooler string)
   • R2_ACCOUNT_ID
   • R2_BACKUP_ACCESS_KEY_ID
   • R2_BACKUP_SECRET_ACCESS_KEY
4. Run the workflow once by hand (Actions → Database backup → Run workflow) and check that it's green.

Keeping Supabase awake

Free Supabase projects pause after 7 days without activity. A daily Vercel Cron (vercel.json → /api/cron/keepalive) runs one real query. It needs CRON_SECRET set in Vercel (any long random string); Vercel sends it automatically, and the route refuses every other caller. The weekly backup is a second, independent source of activity.