Fellow Owners

Startupathon challenge: Operating System for Fanbases (Persist Ventures). Goal: move a creator's audience from Followers -> Organized communities -> Ideas -> Collaboration -> Action.

One link in a creator's bio that gathers followers into communities, surfaces the best ideas and people, and lets the creator put their reach behind what the community builds.

Part	What	Runs on
web/	Next.js 16 app: bio pages, fan pages, creator dashboard	Vercel
api/	Express 5 API: business logic, auth (Better Auth), AI, Drizzle + Postgres	Railway
shared/	zod schemas, enums and limits used by both	built into both
docs/	The build docs (below)

Run it locally

Needs Node 24, pnpm (version from package.json) and Docker.

pnpm install
docker compose up db            # Postgres with pgvector on :5432
cp api/.env.example api/.env    # defaults work for development
pnpm db:migrate                 # apply the SQL migrations
pnpm dev                        # web and api through Turborepo; api on :4000

The web app rewrites /api/* and /r/* to the API (API_URL, http://localhost:4000 in development). Without OPENROUTER_API_KEY a deterministic fake AI answers, so every screen works with no keys. docker compose up --build runs the database and the API in containers instead.

Scripts (root package.json): pnpm dev, build, typecheck, lint (Biome), test:unit, test:integration (needs the Postgres from Docker), test:e2e (Playwright smoke test), db:generate, db:migrate, db:embed (backfill embeddings, needs an AI key), db:studio.

Deploy

Production is one Railway project plus one Vercel project. Details and every variable are in docs/02-trd.md, sections 2 and 3.

Railway (API, data, cron)

Service	Setup
api	Build from api/Dockerfile (context: repo root; .railwayignore trims the upload). Pre-deploy command: node dist/db/migrate.js, so migrations run before traffic moves. Health check: GET /api/health (503 when the database is down). Set RAILWAY_DEPLOYMENT_DRAINING_SECONDS so open requests finish on a deploy. Per-IP limits use Railway's X-Real-IP, or the visitor IP that web/proxy.ts sends as x-edge-client-ip when the request also carries x-edge-key = INTERNAL_API_KEY, so set the same INTERNAL_API_KEY on both services
pgvector	Postgres with the vector extension. DATABASE_URL on api points at it
Redis	REDIS_URL on api: rate-limit counters, daily caps, code throttle and live notifications across replicas. Optional
cron	Schedule 0 * * * *. Its start command calls POST /api/cron/tick on api with Authorization: Bearer $CRON_SECRET. The tick runs the hourly jobs (sweep, question grouping, challenge closing, email digests) and the daily and weekly ones (follower refresh 06:00 UTC, retention purge 09:00 UTC, community digests Mondays 13:00 UTC). A missed hour catches up on the next tick. GET /api/cron/status shows recent runs; POST /api/cron/tick?job=<name> runs one job now
media bucket	S3-compatible bucket for image uploads. Give api its BUCKET_ENDPOINT, BUCKET_NAME, BUCKET_ACCESS_KEY_ID and BUCKET_SECRET_ACCESS_KEY (all four, or uploads stay off). Set the bucket's CORS once so browsers can PUT and GET from the web origins (production, previews, localhost)

Rows written while AI was off have no embeddings: run pnpm db:embed against the database with an AI key to backfill them.

Vercel (web)

Project fellow-owners-web (the Next.js app in web/). Environment variables:

Variable	What
API_URL	Origin of the Railway api service. The rewrites and server-side reads use it
NEXT_PUBLIC_APP_URL	The public web origin, for links people copy or scan. Optional
INTERNAL_API_KEY	Server-only, 32+ characters, the same value as on api; lets the web server's reads skip the API's per-IP rate limits, and proxy.ts (which rewrites /api/* to API_URL) sends it as x-edge-key with the visitor's IP as x-edge-client-ip, so the API counts the visitor's IP, not Vercel's
NEXT_PUBLIC_GA_ID	Google Analytics 4 measurement id (G-…). Optional; loads only after a visitor accepts analytics cookies. Set before building
GOOGLE_SITE_VERIFICATION	Google Search Console HTML-tag token (the content value only). Optional
BING_SITE_VERIFICATION	Bing Webmaster Tools msvalidate.01 token. Optional; Bing's index also feeds ChatGPT search and Copilot

On api, set WEB_ORIGIN and BETTER_AUTH_URL to the web origin (auth is reached through the web rewrite), and TRUSTED_ORIGINS for preview deployments.

Where secrets live

Only in the Railway and Vercel environment variables. api/.env.example lists names, never values; api/src/config/env.ts checks them on boot and stops the process with the full list of problems. In production the API requires DATABASE_URL, BETTER_AUTH_SECRET (32+ characters), RESEND_API_KEY with EMAIL_FROM, CRON_SECRET and CLICK_SALT. Optional keys switch features on: OPENROUTER_API_KEY (live AI), GOOGLE_*, APPLE_*, FACEBOOK_* (sign-in), APIFY_TOKEN (profile lookups), YOUTUBE_API_KEY (comment import), FAL_KEY (media generation), ADMIN_EMAILS (admin allowlist).

The build docs

These docs follow the "Six Documents Before Vibe Coding" template. Give them to the coding agent together.

#	Document	Answers
01	PRD	What we build, for whom, how we know it worked, what is built
02	TRD	Stack, hosting, environment, API, jobs, AI design, security, decisions
03	App Flow	Every screen, journey, action, empty state
04	UI and UX Design Brief	Visual language, tokens, components
05	Backend Schema	Tables, relationships, authorization, validation, retention, seed
07	File Structure	The repo tree and naming rules

If two documents disagree, do not guess. Flag it, and resolve in this order: PRD (what) > App Flow (behavior) > Backend Schema (data rules) > TRD (how) > UI brief (look). Then update the losing document. The glossary is in docs/README.md.