# 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](../spec/PLAYERPAL_AUTH_IDENTITY_SPEC.md) and wins on conflict.

## Precedence

```text
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](../spec/PLAYERPAL_AUTH_IDENTITY_SPEC.md) 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](status.mdx) for what is built and [contributing/docs.md](contributing/docs.md) and [contributing/style.md](contributing/style.md) for how pages are written.

| Start with | For |
|---|---|
| [product/overview.mdx](product/overview.mdx) | What PlayerPal is and who takes part |
| [developers/quickstart.mdx](developers/quickstart.mdx) | Partner engineers integrating for the first time |
| [analytics/metrics.mdx](analytics/metrics.mdx) | KPI definitions |
| [trust/privacy.mdx](trust/privacy.mdx) | Public privacy commitments |
| [security-privacy/personal-data.md](security-privacy/personal-data.md) | Internal deep dive on player data, with code evidence and gaps |
| [shop/redemption-lifecycle.md](shop/redemption-lifecycle.md) | Internal deep dive on the demo shop |

## Start here

| Document | What it covers |
|---|---|
| [architecture.md](architecture.md) | Product, components, stack, delivery phases |
| [identity.md](identity.md) | Identifiers, pairwise aliases, encoding |
| [authentication.md](authentication.md) | IAM vs PlayerPal, methods, sessions, tokens |
| [linking-and-bootstrap.md](linking-and-bootstrap.md) | Registration, operator/provider linking, Unlink, Delete Account, discovery, merge |
| [portals.md](portals.md) | URL-isolated audiences |
| [authorization.md](authorization.md) | IAM personas vs PlayerPal permissions |
| [ingestion-and-availability.md](ingestion-and-availability.md) | Sidecar, batches, outbox, SLOs |
| [loyalty.md](loyalty.md) | Ledger, eligibility, versioned campaigns, studio analytics |
| [kpis.md](kpis.md) | Partner and staff KPIs, visibility tiers, anonymous comparison rules |
| [data-model.md](data-model.md) | Identity and party tables |
| [../schema/](../schema/README.md) | Seeds + historical SQL (DDL = TypeORM) |
| [../infra/](../infra/README.md) | Local ZITADEL + NestJS + Postgres |
| [open-questions.md](open-questions.md) | Items still undecided |
| [decisions/](decisions/README.md) | 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/](../spec/playerpal-bootstrap-diagrams/)
- Device mockups: [spec/playerpal-device-mockups/](../spec/playerpal-device-mockups/)

## How to add an ADR

1. Copy [adr-template.md](adr-template.md) to `docs/decisions/NNNN-short-title.md` using the next number.
2. One decision per ADR. Keep Status / Context / Decision / Consequences.
3. Do not rewrite a decided ADR in place. Mark it `Superseded by NNNN` and write a new record.
4. Update [open-questions.md](open-questions.md) if the ADR closes or opens a question.
5. 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](historical/architecture-brief.md) and [historical/id-architecture.md](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](research/2026-09-05-zitadel-custom-login-ui.md) | ZITADEL branding vs fork Login V2 vs build-your-own vs community UI |