PlayerPal documentation
Day-to-day source of truth for architecture and decisions. The long-form identity and authentication specification remains spec/PLAYERPAL_AUTH_IDENTITY_SPEC.md and wins on conflict.
Precedence
spec/PLAYERPAL_AUTH_IDENTITY_SPEC.md wins on conflict
docs/ + docs/decisions/ day-to-day source of truth
docs/historical/ superseded briefs and old ID diagrams
Do not weaken an invariant in spec §30 without an ADR.
Guides
The documentation site (task docs:dev) has a public part for partners, prospects and investors, and this internal handbook. Public pages live in product/, developers/, analytics/, rewards/ and trust/; everything else is internal. See status.mdx for what is built and contributing/docs.md and contributing/style.md for how pages are written.
| Start with | For |
|---|---|
| product/overview.mdx | What PlayerPal is and who takes part |
| developers/quickstart.mdx | Partner engineers integrating for the first time |
| analytics/metrics.mdx | KPI definitions |
| trust/privacy.mdx | Public privacy commitments |
| security-privacy/personal-data.md | Internal deep dive on player data, with code evidence and gaps |
| shop/redemption-lifecycle.md | Internal deep dive on the demo shop |
Start here
| Document | What it covers |
|---|---|
| architecture.md | Product, components, stack, delivery phases |
| identity.md | Identifiers, pairwise aliases, encoding |
| authentication.md | IAM vs PlayerPal, methods, sessions, tokens |
| linking-and-bootstrap.md | Registration, operator/provider linking, Unlink, Delete Account, discovery, merge |
| portals.md | URL-isolated audiences |
| authorization.md | IAM personas vs PlayerPal permissions |
| ingestion-and-availability.md | Sidecar, batches, outbox, SLOs |
| loyalty.md | Ledger, eligibility, versioned campaigns, studio analytics |
| kpis.md | Partner and staff KPIs, visibility tiers, anonymous comparison rules |
| data-model.md | Identity and party tables |
| ../schema/ | Seeds + historical SQL (DDL = TypeORM) |
| ../infra/ | Local ZITADEL + NestJS + Postgres |
| open-questions.md | Items still undecided |
| decisions/ | Architecture Decision Records |
Flows, HTTP examples, and diagrams live in the spec. Topic pages summarise decisions and cite spec sections.
Diagrams
- Bootstrap and linking: spec/playerpal-bootstrap-diagrams/
- Device mockups: spec/playerpal-device-mockups/
How to add an ADR
- Copy adr-template.md to
docs/decisions/NNNN-short-title.mdusing the next number. - One decision per ADR. Keep Status / Context / Decision / Consequences.
- Do not rewrite a decided ADR in place. Mark it
Superseded by NNNNand write a new record. - Update open-questions.md if the ADR closes or opens a question.
- If the decision changes identity or privacy behaviour, update the relevant topic page and cite the spec section that still applies.
Historical briefs: historical/architecture-brief.md and historical/id-architecture.md.
Research notes
Primary-source write-ups for open design questions (not day-to-day truth; ADRs and topic pages win).
| Note | Topic |
|---|---|
| 2026-09-05-zitadel-custom-login-ui.md | ZITADEL branding vs fork Login V2 vs build-your-own vs community UI |