Onboarding Checklist

A structured first week. Tick things off; each step builds on the last.

Day 1 — Get it running

• [ ] Repository access to cryptixcoder/playpals
• [ ] Install prerequisites: Node 22, pnpm 9.0.0 via corepack, Docker
• [ ] git clone and pnpm install
• [ ] Copy every .env.example to .env (Local Setup)
• [ ] docker compose up -d db redis
• [ ] cd packages/database && pnpm db:generate && pnpm db:migrate
• [ ] pnpm build
• [ ] pnpm db:seed
• [ ] pnpm dev — API and esu start cleanly
• [ ] curl localhost:4000/health → {"status":"ok"}
• [ ] curl localhost:4010/health → {"ok":true}

Blocked? Troubleshooting covers the common failures. The two that catch almost everyone: the Redis password (redis://:playpalz@localhost:6379) and esu's API_BASE_URL pointing at port 3000 instead of 4000.

Day 1–2 — Run the app

• [ ] Get a development build from a teammate (Expo Go will not work)
• [ ] Install it on the iOS Simulator
• [ ] Create apps/mobile/.env with EXPO_PUBLIC_API_URL and EXPO_PUBLIC_REALTIME_URL
• [ ] pnpm --filter @playpals/mobile ios
• [ ] Register an account, complete onboarding
• [ ] Post something with a photo — confirm thumbnails appear (that is ogun working)
• [ ] Send yourself a DM from a seeded account

You now have the whole stack exercised end to end.

Day 2 — Understand the shape

Read in this order:

• [ ] Introduction — what the product is
• [ ] System Overview — the seven services
• [ ] Monorepo Layout — where things live
• [ ] Service Topology — who calls whom
• [ ] Coding Standards — how to write code that fits

Then trace one request yourself, in the code:

apps/mobile/hooks/useFeed.ts
  → apps/mobile/api/feed.ts
  → apps/api/src/router/feedRoutes.ts
  → apps/api/src/controllers/feed.ts
  → apps/api/src/services/feed.ts
  → packages/database

That path is the shape of every feature in the codebase.

Day 3 — Your domain

Read the pages for whatever you have been assigned:

Area	Read
Backend	api, API Conventions, Database
Realtime	Realtime, esu, Socket Events
Media	Media Pipeline, ogun
Payments	Monetization, anansi, Webhooks
Mobile	Mobile Overview, Data Layer, Design System
Infrastructure	Infrastructure, Kubernetes, Deploying

Day 4–5 — Ship something

Pick something small and real. Good first tasks, because each touches one layer end to end without much blast radius:

• Add a field to a profile endpoint and surface it in the app
• Add a notification type for an event that does not have one
• Write a test for lib/roomAccess.ts (see Testing)
• Fix one of the documented defects — the ogun /admin prefix bug is contained and valuable

Then:

• [ ] pnpm check-types and pnpm lint pass
• [ ] pnpm format
• [ ] Docs updated if you changed an endpoint, an env var, or a contract
• [ ] Open a PR

Week 2 — Production access

Only when you need it:

• [ ] DigitalOcean team access
• [ ] doctl auth init and make kubeconfig from infra/terraform
• [ ] kubectl get pods works
• [ ] Grafana access at grafana.playpalz.gg
• [ ] Read Deploying and Runbooks before your first deploy

Understand what deploying means here

There is no CI/CD and no staging environment. A deploy goes from your laptop straight to production, with nothing verifying it first. Read Deploying properly before you run a build script.

Things it helps to know early

The naming. Backend services are named after West African deities: esu is realtime, ogun is media, anansi is payouts. The repo and git remote say playpals; the product and domain say playpalz.

dev-notes/ is git-ignored. It holds the design system specification and a lot of planning material, and a fresh clone does not include it. Ask someone for a copy.

These docs mark what is incomplete. Partial and Planned badges, plus warning and danger callouts, flag things that do not work the way you would expect. They are not decoration — read them.

The docs live in the repo. apps/docs/. When you change a route, an env var, or a contract, update the matching page in the same PR.

Ask about

Things not derivable from the code, worth asking a teammate:

• Which features are actively being built right now
• Who owns which area
• The release cadence for mobile
• Whether the RevenueCat integration is live or still partly mocked
• What the priority order is on the known defects listed throughout these docs