petfeed/CLAUDE.md

Project

PawFeed

PawFeed is a social platform where pets are the stars. Dogs, cats, and birds get their own profiles — owners manage them, but the pet is the identity. Think Instagram built from the ground up for animals: pets follow each other, post photos and videos, celebrate milestones, and track their health, all within a community that actually cares about animals.

Core Value: Pets are first-class social identities — not just content on a human's feed — so every feature is built around the pet's life, not the owner's.

Constraints

• Platform: Web-first (mobile-responsive) for v1 — fastest path to launch; React Native is a future milestone
• Pet types: Dogs, cats, birds only in v1
• Media storage: Requires cloud storage solution for photos/videos (S3-compatible)
• Video: Short-form only — no long-form video to keep storage/bandwidth manageable at launch

Technology Stack

Recommended Stack

Core Framework

Technology	Version	Purpose	Why
Next.js	15.x (stable)	Full-stack React framework	App Router gives co-located server components + API routes in one repo. SSR for SEO on pet/explore pages. Turbopack dev server is now stable. React 19 support. Confirmed stable per official release blog.
React	19.x	UI rendering	Ships with Next.js 15. React Server Components reduce JS bundle for feed pages. Concurrent features matter for infinite scroll.
TypeScript	5.x	Type safety	Next.js 15 ships next.config.ts with first-class TS support. Non-negotiable for a team codebase; catches data-shape bugs early (pet profiles, post types).

Styling

Technology	Version	Purpose	Why
Tailwind CSS	4.x	Utility-first styling	Fastest path to a polished, consistent UI. No CSS-in-JS runtime cost. v4 (released early 2025) uses a new CSS-native engine — faster builds, no config file needed. Standard choice for Next.js apps in 2025.
shadcn/ui	Latest	Component primitives	Radix UI primitives + Tailwind. Copy-into-repo model means no dependency lock-in. Accessible by default — critical for input forms (onboarding, post upload, DM composer). Not a library to install — a component source strategy.

Backend / API

Technology	Version	Purpose	Why
Next.js Route Handlers	15.x	API layer	For most endpoints (CRUD on pets, posts, follows, reactions) Next.js Route Handlers eliminate a separate API server entirely. Server Actions for form mutations (post creation, profile edits) keep the round-trip minimal.
tRPC	11.x	Type-safe API client-server bridge	Where you need client-side data fetching with full type safety (feed, DM polling, notifications), tRPC with React Query eliminates manual API typing. Pairs well with Next.js App Router via the @trpc/server/adapters/fetch adapter. Use for internal browser-to-server calls; use plain Route Handlers for webhooks and external service callbacks.
Zod	3.x	Schema validation	Input validation on all API boundaries. tRPC uses Zod natively. Also use for validating Mux/Cloudinary webhook payloads.

Database

Technology	Version	Purpose	Why
PostgreSQL	16.x	Primary data store	The correct choice for a social graph. Supports relational integrity (pet→owner, post→pet, follow→pet), JSONB for flexible milestone metadata, full-text search for hashtag/breed discovery, and row-level security (RLS) when using Supabase.
Supabase	Latest (hosted)	Managed Postgres + realtime + auth option	Supabase provides managed Postgres 15/16, built-in Realtime (websocket pub/sub on DB changes), Storage (S3-compatible for photos), and optional Auth. Dramatically reduces infrastructure work for a v1. The free tier covers early-stage traffic. Critical: Supabase Realtime handles feed updates and DM delivery — replaces the need for a separate WebSocket server.
Prisma	5.x	ORM / schema management	Type-safe DB client generated from schema. Migrations are declarative. Integrates with Supabase Postgres directly. Prisma Accelerate (edge-compatible connection pooling) solves the serverless connection limit problem that hits Postgres hard on Vercel.
Redis (Upstash)	Serverless	Cache + rate limiting + ephemeral state	Stories TTL management (24h expiry), feed caching for hot users, rate limiting on post upload and DM endpoints. Upstash is serverless Redis — pay-per-request, no always-on instance. Critical: do NOT use Supabase as a cache layer; Redis is the right tool for ephemeral/fast-expiry data.

Media Storage & Delivery

Technology	Version	Purpose	Why
Cloudflare R2	—	Photo storage	S3-compatible object storage with zero egress fees. Photos are the dominant media type by volume. Egress costs on S3 accumulate fast on a social platform; R2 eliminates this. Pair with Cloudflare CDN for global image delivery.
Cloudflare Images	—	Image optimization & CDN	Resize, crop, and format-convert (WebP/AVIF) on the fly via URL parameters. Replaces the need for a custom image pipeline. Cost: ~$5/100k images served. Alternative is Next.js Image Optimization pointed at R2, but Cloudflare Images is more capable and decoupled from your Next.js server.
Mux	—	Video upload, transcoding, adaptive streaming	Short-form video (pet posts, stories) requires HLS adaptive streaming — raw MP4 upload is not acceptable for mobile networks. Mux handles: upload via signed URLs → auto-transcoding to multiple bitrates → HLS delivery → thumbnail extraction → webhooks on completion. The mux-player-react component embeds in 10 lines. Pricing is per-minute stored + per-minute delivered — fair for short-form video. Do not use Cloudinary for video at scale: Cloudinary's video pricing is expensive and less optimized for streaming than Mux.

Real-Time Features

Technology	Version	Purpose	Why
Supabase Realtime	—	Feed updates, DM delivery, notification toasts	Supabase Realtime uses PostgreSQL logical replication to broadcast DB changes over websockets. Subscribe to INSERT on messages table → DMs appear instantly. Subscribe to INSERT on posts from followed pets → live feed updates. No separate Socket.io or Ably subscription needed. Included in Supabase plan.
TanStack Query (React Query)	5.x	Client-side data fetching, caching, optimistic updates	Pairs with tRPC. Handles feed pagination (cursor-based infinite scroll), optimistic like/reaction updates, and background refetch. Do NOT use SWR — React Query v5 has superior cache invalidation and mutation handling for a social app's complexity.

Authentication

Technology	Version	Purpose	Why
Clerk	Latest	Authentication provider	Clerk is the standard choice for Next.js 15 App Router auth in 2025. Ships with: pre-built UI components (sign-in, sign-up, user profile), social OAuth (Google, Apple, Facebook — important for pet-owner onboarding friction), session management with edge-compatible JWT verification, webhooks for user lifecycle events. The @clerk/nextjs middleware integration is first-class. Note: PawFeed has a two-layer identity (owner account + pet profile). Clerk manages the owner account; your DB manages the pet-as-identity layer. Do NOT try to put pets as Clerk users — they are not auth entities, they are app-domain entities.

Infrastructure & Deployment

Technology	Version	Purpose	Why
Vercel	—	Hosting	Next.js is optimized for Vercel — zero-config deployment, edge middleware, ISR, image optimization. For a greenfield social app the operational overhead savings outweigh cost at v1 scale. Preview deployments per PR accelerate iteration.
Upstash	—	Serverless Redis	Rate limiting (post uploads, DM sends), story TTL tracking, hot-user feed cache. Serverless pricing eliminates idle cost.

Alternatives Considered

Category	Recommended	Alternative	Why Not
Frontend framework	Next.js 15	Remix v2	Remix has excellent data loading patterns but smaller ecosystem, less Vercel integration, and fewer community examples for social apps. Next.js App Router now covers Remix's main advantages (nested layouts, data co-location).
Frontend framework	Next.js 15	SvelteKit	Smaller ecosystem, fewer hire-able devs, React component ecosystem (shadcn, Mux player) is unavailable.
Database	PostgreSQL (Supabase)	MongoDB	No relational joins — social graph queries become application-level N+1 problems. MongoDB's flexible schema is a liability when you need FK constraints on pet→post→reaction.
Database	PostgreSQL (Supabase)	PlanetScale (MySQL)	PlanetScale removed its free tier in 2024; Vitess's lack of FK enforcement is a footgun for a social graph. Supabase offers more value (Realtime, Auth, Storage) in one platform.
ORM	Prisma	Drizzle ORM	Drizzle is faster and more lightweight, but Prisma's migration tooling and ecosystem maturity are better for a team starting greenfield. Revisit Drizzle in v2 if Prisma performance becomes an issue.
Video	Mux	Cloudinary Video	Cloudinary video pricing is significantly higher per GB and less optimized for HLS adaptive streaming. Mux is purpose-built for streaming video.
Video	Mux	AWS MediaConvert + S3	More control but enormous operational complexity for a v1. Requires Lambda triggers, MediaConvert job polling, CloudFront CDN setup. Mux abstracts all of this.
Photo storage	Cloudflare R2 + Images	AWS S3 + CloudFront	Equivalent capability but S3 egress costs accumulate. R2's zero-egress pricing is a direct advantage for a photo-heavy social platform.
Photo storage	Cloudflare R2 + Images	Supabase Storage	Supabase Storage lacks image transformation. Use Supabase Storage only for private files needing RLS (health records).
Auth	Clerk	NextAuth (Auth.js v5)	More setup, no pre-built UI, requires more custom code for social OAuth flows. Clerk's Next.js 15 App Router integration is tighter and more production-ready.
Real-time	Supabase Realtime	Ably / Pusher	Additional paid service when Supabase Realtime (included) covers the use cases. Supabase Realtime's DB-change subscription model is particularly clean for a feed driven by Postgres inserts.
Real-time	Supabase Realtime	Socket.io (self-hosted)	Requires a persistent server — incompatible with Vercel serverless. Supabase Realtime is managed and serverless-friendly.
Client fetching	TanStack Query v5	SWR	React Query v5 has richer mutation/optimistic update APIs. For a social app with likes, comments, and reposts all needing optimistic UI, React Query's useMutation is more capable than SWR's useSWRMutation.
Styling	Tailwind CSS v4	CSS Modules	CSS Modules don't scale as well for a design system approach; Tailwind + shadcn provides a cohesive component language out of the box.
Styling	Tailwind CSS v4	styled-components / Emotion	Runtime CSS-in-JS has a performance penalty in RSC environments and adds complexity. Tailwind generates static CSS — no runtime overhead.

Installation

Bootstrap

Core dependencies

Dev dependencies

shadcn/ui (interactive CLI, installs component source into your repo)

Key Version Pinning Notes

Package	Version to pin	Reason
next	^15.0.0	Stable, confirmed. Avoid canary.
react / react-dom	^19.0.0	Required for Next.js 15 App Router.
@prisma/client	^5.0.0	v5 has improved query performance and better TS types.
@trpc/server	^11.0.0	v11 is the App Router-native version; v10 had compatibility issues.
@tanstack/react-query	^5.0.0	v5 has breaking API changes from v4; pin major.
tailwindcss	^4.0.0	v4 engine is not backward compatible with v3 config format.

Confidence Assessment

Area	Confidence	Notes
Next.js 15 as framework	HIGH	Confirmed via official release blog (fetched). Stable since Oct 2024.
React 19	HIGH	Ships with Next.js 15, confirmed in release blog.
TypeScript 5.x	HIGH	Industry standard; no uncertainty.
Tailwind CSS v4	MEDIUM	Released early 2025 per training data; could not verify current minor version with live docs.
shadcn/ui	MEDIUM	Well-established pattern as of August 2025 training cutoff.
tRPC v11	MEDIUM	v11 targeting App Router compatibility per training data; verify current release on npmjs.com.
Prisma v5	MEDIUM	Stable per training data; Prisma Accelerate for serverless connection pooling verified as an existing product.
Supabase (Postgres + Realtime)	MEDIUM	Core product is well-established; Realtime feature set stable per training data. Cannot confirm latest feature additions.
PostgreSQL 16	HIGH	Mature, stable; Supabase provides it managed.
Cloudflare R2 + Images	MEDIUM	R2 launched 2022, zero-egress pricing confirmed stable; Images product behavior from training data.
Mux for video	MEDIUM	Mux is the established standard for developer-facing video streaming; mux-player-react is the official component. Pricing model from training data — verify before committing.
Clerk	MEDIUM	Established Next.js auth provider as of training cutoff; Next.js 15 App Router compatibility from training data. Verify @clerk/nextjs supports Next.js 15 before starting.
Upstash Redis	MEDIUM	Serverless Redis product is well-established; pricing from training data.
Vercel	HIGH	Official Next.js hosting platform, no uncertainty.

Sources

• Next.js 15 official release blog: https://nextjs.org/blog/next-15 (fetched 2026-06-05) — HIGH confidence
• Remaining technology assessments based on training data (cutoff August 2025) — MEDIUM confidence
• Recommend verifying: Clerk @clerk/nextjs Next.js 15 compatibility, tRPC v11 stability, Tailwind v4 migration guide, Mux current pricing

Conventions

Conventions not yet established. Will populate as patterns emerge during development.

Architecture

Architecture not yet mapped. Follow existing patterns found in the codebase.

Project Skills

No project skills found. Add skills to any of: .claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/, or .codex/skills/ with a SKILL.md index file.

GSD Workflow Enforcement

Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:

• /gsd-quick for small fixes, doc updates, and ad-hoc tasks
• /gsd-debug for investigation and bug fixing
• /gsd-execute-phase for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.

Developer Profile

Profile not yet configured. Run /gsd-profile-user to generate your developer profile. This section is managed by generate-claude-profile -- do not edit manually.