Introduction
This is the engineering handbook for PlayPalz. It is written for someone who has just been handed repository access and needs to be productive today, and for the person who will be on call for this platform six months from now.
What PlayPalz is
PlayPalz is a mobile-first social platform where fans pay to spend time with creators. The product has four revenue-bearing loops:
| Loop | What the fan does | What the creator gets |
|---|---|---|
| Creator subscription | Pays a creator's monthly price to unlock their private channel | Recurring monthly revenue, minus platform fee |
| Play Coins | Buys coins, gifts them during a livestream | Gifted coin value, redeemable as USD |
| Sessions (e-dates) | Books a 1-on-1 time slot | Session fee, minus platform fee |
| Platform subscription | Buys a PlayPalz premium tier | — (platform revenue) |
Payments are collected through RevenueCat (mobile in-app purchase), and creator payouts are executed through Stripe Connect by the anansi service. The full money flow is documented in Monetization.
What the codebase is
A Turborepo monorepo managed with pnpm workspaces. Everything lives in one repository:
- 7 apps — one mobile client, one web client, five backend services
- 5 packages — a shared Prisma client, a shared queue, shared types, a shared socket client, and shared tsconfigs
Backend services are Express + TypeScript, run with tsx in development and compiled to JavaScript for production containers. The database is PostgreSQL accessed exclusively through Prisma. Redis backs both the BullMQ job queue and the Socket.IO adapter.
See Monorepo Layout for the file-by-file tour.
Naming
Backend services are named after West African deities, and the name tells you what the service does:
| Name | Meaning | Role |
|---|---|---|
| Esu | Language, mediation, exchange | Realtime Socket.IO server |
| Ogun | Iron, machinery, transformation | Media processing worker |
| Anansi | Intelligence, the web of connections | Accounting and creator payouts |
The plain-named services (api, web, mobile, igdb-heartbeat) do what their names say.
How to use these docs
- First day? Go straight to Prerequisites, then Local Setup.
- Looking for an endpoint? The API Reference is grouped by domain and mirrors
apps/api/src/router/. - Something is broken? Troubleshooting covers local problems; Runbooks covers production.
- Need an env var? Environment Variables is the consolidated table across every service.
A note on scope
This documentation describes the platform as the code currently stands, including the parts that are half-finished. Where something is incomplete, it is marked:
Shipped — implemented and running in production.
Partial — code exists but is incomplete or unverified.
Planned — designed but not built.
Those markers matter more than polish. If you find one that is wrong, fix it.