Files
petfeed/CLAUDE.md
T
admin 6a61bbcc81 feat(docker): zero-downtime rolling deploy for the 3 replicas
Adds a dependency-free liveness endpoint (GET /api/health), a Docker
healthcheck against it, and docker/rolling-deploy.sh which rebuilds
the shared image once and restarts pawfeed-1/2/3 sequentially, gated
on each becoming healthy before moving to the next. Verified
zero-downtime via continuous curl monitoring through a full run
against production.
2026-08-16 13:17:04 +02:00

119 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project
**PawFeed** — a social platform where pets are the stars. Domestic/companion animals get their own profiles; owners manage them, but the pet is the identity (profile URL, posts, follows — all pet-scoped, not owner-scoped). Photos, short-form video, stories, milestones, DMs, and health tracking, all within a single pet-first social graph.
**Core value:** Pets are first-class social identities, not content on a human's feed. Every feature is built around the pet's life.
**Constraints:** Web-first (mobile-responsive); short-form video only (no long-form).
**Species scope:** Dogs, cats, birds, horses, rabbits, guinea pigs, hamsters, mice, rats, chinchillas, snakes, lizards, turtles, geckos, spiders, and aquariums (the Species is the tank/aquarium as a whole, not one profile per fish — Breed is the predominant fish species kept, e.g. Betta, Guppy, Discus) — see `Species`/`Breed` in `prisma/schema.prisma` and the taxonomy in `prisma/seed.ts`. The species/breed system is fully data-driven (i18n translation tables, dynamic `pets.listSpecies`/`pets.listBreeds` queries) — every consumer (pet creation, onboarding, ad targeting) already reads from these tables, so adding a new species is a seed-data change, not a code change. The one exception: **spiders** are treated specially — an owner-level "Arachnophobie-Helfer" preference (`Owner.hideSpiders`, toggled during onboarding via `ArachnophobiaOptIn` or later on `/pets` via `HideSpidersToggle`) fully excludes Species="Spider" pets/posts from feed/explore/search when enabled (`src/lib/spider-exclusion.ts`). This exclusion is applied per-query at each read site (feed.ts, explore.ts, search.ts) — there is no central chokepoint, so a new pet/post-listing query must add the same `getSpiderExclusionId()` check to stay consistent.
## Commands
```bash
npm run dev # next dev (Turbopack)
npm run build # next build (output: "standalone")
npm run start # next start
npm run lint # eslint (flat config, eslint.config.mjs)
npx tsc --noEmit # type check (no separate package.json script)
npx vitest run # run full test suite
npx vitest run src/__tests__/posts.test.ts # run a single test file
npx vitest # watch mode
npx prisma generate # regenerate Prisma client after schema.prisma changes
npx prisma migrate dev # create + apply a migration locally
npx prisma db seed # runs prisma/seed.ts via tsx (breed/species taxonomy)
```
There is no `npm test` script — invoke `vitest` directly via `npx`.
## Architecture
### Two-layer identity (the load-bearing invariant)
Clerk manages **Owner** accounts (auth only — `Owner.id` is literally the Clerk `userId`). Pets are app-domain entities, not auth principals. Every social action — posts, follows, reactions, comments, DMs — is scoped by `petId`, never by `ownerId`. The social graph (`Follow`, `Block`, `Reaction`, etc.) has no owner columns at all. When adding a feature, figure out which pet is acting, not which owner is logged in; ownership checks (`pet.ownerId === ctx.userId`) happen in the tRPC procedure, not in the schema.
The client-side "which pet is currently active" state lives in `src/context/ActivePetContext.tsx` (React Context + `localStorage`, initialized server-side by `ActivePetInitializer` with the owner's first pet). The `localStorage`/SSR mismatch on first paint is expected, not a bug.
### tRPC layer
- `src/trpc/init.ts` — context is `{ userId, prisma }` (userId from Clerk `auth()`); `protectedProcedure` throws `UNAUTHORIZED` if `userId` is null and narrows it to non-null in `ctx` for everything downstream.
- `src/trpc/routers/_app.ts` — aggregates ~20 domain routers (pets, posts, stories, milestones, follows, blocks, reports, feed, reactions, comments, reposts, explore, search, notifications, videos, conversations/messages, health, admin, invites, ads). One router file per domain in `src/trpc/routers/`.
- `src/trpc/server.ts` exposes a server-side caller (`createTRPCCaller()`) used inside Server Components/layouts to prefetch without an HTTP round-trip (see `src/app/(app)/layout.tsx`). `src/trpc/client.tsx` + `query-client.ts` wire up the browser-side TanStack Query client.
- Pet-ownership checks go through the shared `assertPetOwnership(prisma, petId, userId)` helper in `src/lib/assert-pet-ownership.ts` — don't reintroduce a local copy of this check in a new router.
### Denormalized engagement counters
`Post.reactionCount/commentCount/repostCount` and `Advertisement.adReactionCount/adCommentCount/adRepostCount` are maintained transactionally at every create/delete site (reactions, comments, reposts, ads routers, and `admin.ts` moderation deletes) instead of computed via live `_count`/`count()` on read. Feed/explore/posts/admin reads use these columns directly. If you add a new mutation that creates or deletes a reaction/comment/repost, you must increment/decrement the matching counter in the same transaction — there is no background reconciliation job.
### Routing structure
- `(auth)` route group — sign-up/log-in/password reset, unauthenticated.
- `(app)` route group — the authenticated shell (`layout.tsx` does a belt-and-suspenders `auth()` check, redirects to onboarding if the owner has zero pets, redirects banned owners to `/banned`, and consumes a pending invite cookie).
- `/p/[secret]/...` — the admin/moderation panel. The path segment itself is the secret (`ADMIN_SECRET` env var); wrong or missing secret returns a bare `404`, not `403`, so the panel's existence isn't revealed.
- `/health-card/[token]` — public, tokenized, no auth (shareable vet record).
- Root-level `/impressum`, `/datenschutz`, `/nutzungsbedingungen` — German legal pages, not under `(app)`, not localized (this is a `next-intl` project but these three routes are fixed-language).
### `src/proxy.ts` (not `middleware.ts`)
Next.js 16 renamed `middleware.ts` to `proxy.ts` — this **is** the middleware; don't go looking for a `middleware.ts` that doesn't exist. It layers three concerns in one Clerk middleware: (1) invite gate — blocks `/sign-up` unless a `pf_invite` cookie is present, unless `INVITE_REQUIRED=false`; (2) admin secret gate — 404s `/p/*` unless the path segment matches `ADMIN_SECRET`; (3) `auth.protect()` for everything else not in the public route matcher.
### Media & storage — code has diverged from the original stack plan
The actual, current image/avatar storage path is **Supabase Storage** (`src/lib/supabase-storage.ts`, bucket `pet-avatars`, `createSignedUploadUrl` + `getPublicUrl`), used by `posts`, `stories`, `media`, and `admin` routers. `src/lib/r2.ts` (Cloudflare R2 via presigned S3 PUT) was dead code and has been **deleted** (2026-07-12), along with the `@aws-sdk/*` dependencies — Supabase Storage is the only storage path now.
All uploads are presigned/direct-to-storage — media bytes never pass through the Next.js server.
### Video (Mux)
`src/lib/mux.ts` is a thin singleton client. Video is async: a `VideoPost` row is created in `PROCESSING` state with a `muxUploadId`; the `/api/webhooks/mux` route handler advances it to `READY` (with `muxAssetId`, `muxPlaybackId`, duration, aspect ratio) or `ERROR` as Mux webhooks arrive. Never assume a video is playable synchronously after upload.
### Redis — self-hosted, not Upstash
`src/lib/redis.ts` is a plain `ioredis` client (`lazyConnect: true` so module evaluation during build doesn't attempt a TCP connect) pointed at `REDIS_URL`. In production this is the `redis` service in `docker-compose.yml`, not Upstash serverless — despite what older planning docs in `.planning/` say.
### i18n
`next-intl`, config at `src/i18n/request.ts`, message catalogs at `messages/en.json` and `messages/de.json`. No locale-prefixed routing — check `request.ts` before assuming a routing scheme when adding a new locale.
### Admin / moderation panel
Gated by path secret (see `proxy.ts` above) *and* by role at the tRPC layer: `src/trpc/routers/admin.ts`'s `assertAdmin()` allows either `ADMIN_OWNER_ID` (env-configured super-admin bootstrap) or an `AdminRole` row (`SUPER_ADMIN` / `MODERATOR`). Actions are written to `ModerationLog`. Pages live under `src/app/p/[secret]/{users,moderators,posts,reports,ads,invites}`.
### Invite system
`InviteCode` model (word-prefix + 4-char code, e.g. `PAWS-7K3M`, generated in `src/lib/invite-codes.ts`) gates sign-up via a `pf_invite` cookie set by `/join` and consumed by `/api/auth/consume-invite` right after sign-up (the `(app)` layout redirects there if the cookie is still present). `INVITE_REQUIRED=false` turns the whole gate off for post-beta public launch.
### Testing
Vitest + `jsdom`. Prisma is fully mocked per-model via `createMockPrisma()` in `src/__tests__/helpers/prisma-mock.ts` — unit tests never touch a real database; when a router gains a new Prisma call, add the corresponding mock method there. Tests are organized one file per domain router in `src/__tests__/` (e.g. `posts.test.ts`, `stories.test.ts`, `follows.test.ts`), not colocated with source.
### Deployment — self-hosted Docker, not Vercel
Despite `next.config.ts`'s `output: "standalone"` and the original stack research recommending Vercel, this app is deployed to a self-hosted OpenMediaVault NAS via Docker (`docker/Dockerfile`, `docker/docker-compose.yml`, `docker/start.sh`). **There is no `git pull` on the server** — deploys are manual FTP uploads of changed files followed by `./start.sh`. Don't suggest Vercel-specific features (ISR revalidation webhooks, Vercel KV, edge config) without checking this still holds.
**Runs as 3 load-balanced replicas, not a single container (since 2026-08-16, Gitea #26).** `docker/docker-compose.yml` defines `pawfeed-1`/`pawfeed-2`/`pawfeed-3` (via the `x-pawfeed-common` YAML anchor) instead of one `pawfeed` service — Next.js standalone output is single-process (`node server.js`), so one container only ever used one CPU core regardless of how many the NAS has. A load test on 2026-08-15 hit a hard ceiling at ~60–65 req/sec with one core pegged at 133% while 3 cores sat idle; splitting into 3 replicas fixed it (confirmed via a follow-up load test showing ~100% CPU spread evenly across all three). Nginx Proxy Manager (container `nginx-app-1` on this NAS, admin UI at `192.168.1.222:81`) load-balances across them via a `least_conn` upstream block — that block lives in `/Docker-Data/nginxproxymanager/data/nginx/custom/http_top.conf` on the NAS host (an nginx `upstream {}` is only valid in the `http{}` context, which NPM's per-host "Custom Nginx Configuration" field can't reach — that field only writes into the `server{}`/`location{}` context, and holds the `proxy_pass http://pawfeed_upstream;` override for the `pawfeed.org` Proxy Host instead). Full runbook, decisions, and risk notes: `docker/SCALING-ROADMAP.md`. **Deploying a config or code change means rebuilding all 3 replicas** — there is no separate single-container path anymore, and NPM's proxy target is `pawfeed_upstream`, not a bare `pawfeed:3000` hostname. Use `./docker/rolling-deploy.sh` for deploys against the live site — it rebuilds the shared `pawfeed:latest` image once, then restarts `pawfeed-1`/`2`/`3` one at a time, gated on each becoming `healthy` per the Docker `healthcheck` (`GET /api/health`, a dependency-free liveness check — see `src/app/api/health/route.ts`) before moving to the next, so at least 2 replicas always serve traffic. Verified zero-downtime on 2026-08-16 (continuous curl monitoring showed unbroken HTTP 200 through a full rolling deploy). `docker compose up -d --build` (`start.sh`) still works but restarts all 3 at once — only use it for first-time setup or when a brief outage is acceptable. `src/lib/prisma.ts`'s Prisma pg pool size is capped per-replica via `DB_POOL_MAX` (compose sets `10`) so 3 replicas stay well under the Supabase pooler's client-connection limit.
`src/app/api/cron/trim-feeds/route.ts` trims each pet's Redis feed sorted set to the 90-day retention window and expects a `CRON_SECRET` bearer token. `vercel.json`'s `crons` array that points at it is **inert** on this self-hosted deployment — nothing calls this route yet. It needs an external trigger (e.g. a NAS-side cron job hitting the route with the secret header) before it actually runs.
### Directories that are not app code
- `pentest-ai-agents/` — a separately-cloned plugin repo (has its own `.git`) sitting inside this project root. Unrelated to PawFeed; don't treat its `agents/`, `commands/`, `db/` as part of the app.
- `scaffold-tmp/` — leftover `create-next-app` scaffold from initial bootstrap (has its own `package.json`, `node_modules`, generic starter page). Not part of the running app, which lives under `src/`.
<!-- BEGIN:nextjs-agent-rules -->
# 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/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
<!-- END:nextjs-agent-rules -->