Backend architecture
Backend architecture
This page is the index for the WalkRPG backend’s design layer. Phase 8a delivered the spec: ADRs + API contracts + Prisma schema. Phase 8b (backend-engineer) turns this spec into running NestJS code.
Canon contract
The backend is built against three canonical decisions:
- D-007 — vertical-slice scope, streak-based step economy, restrictive anti-cheat, full networked multiplayer.
- D-008 — GCP-native stack (Cloud SQL + Cloud Run + Firebase Auth + Firebase App Check + Memorystore Redis), native dual mobile (Swift + Kotlin), hybrid premium + sub monetization.
- D-009 — Firebase Auth multi-provider, heavy offline (7-day cap, provisional allocations), strict GDPR (
europe-central2-warsawresidency, 30-day delete-on-demand, 12-month inactivity anonymization, no profiling).
See Canonical decisions for the full text.
Architectural decision records (ADR)
| # | Title | Pillar / canon link |
|---|---|---|
| ADR-0001 | GCP-native architecture topology (production target; Band Zero amendment for test phase) | D-008 |
| ADR-0002 | Step ingest pipeline (production target; deferred in phase 8b) | D-007 + D-009 |
| ADR-0003 | Streak attestation algorithm (production target; trust-mode in phase 8b) | Pillar 1 |
| ADR-0004 | Anti-cheat layer (production target; light validation only in phase 8b) | D-007 |
| ADR-0005 | GDPR data flows + retention (production target; deferred in phase 8b) | D-009 |
| ADR-0006 | Test-phase infrastructure: local + Cloudflare Tunnel + mock auth | Phase 8b re-scope |
ADR-0006 is the current authoritative scope for phase 8b. ADRs 0001-0005 describe the production target per D-007/D-008/D-009 and are deferred until the production-migration phase (currently paused — see roadmap deferred undertakings).
API contracts (closed-beta vertical slice — first 4 endpoints)
| Method | Path | Purpose |
|---|---|---|
| POST | /auth/callback | Firebase ID token exchange, lazy-create User + Walker, mint internal session JWT |
| POST | /step/ingest | Submit per-day step bucket, validate attestation, update streak (provisional) |
| GET | /walker/profile | Cold-start home-screen payload — walker + region + streak + active quest + faction ranks |
| GET | /tree/state | Allocated nodes/keystones + available unlocks + topology refs |
Phase 11 (closed beta) adds: POST /tree/allocate, POST /tree/keystone/allocate, GET /quest/list, POST /quest/progress, guild + chat + co-op endpoints.
Prisma schema
The closed-beta schema lives at backend/prisma/schema.prisma. It implements all 14 models referenced by the ADRs and API contracts:
- Identity:
User,Walker - Step economy:
StepLog,StreakState,AttestationLog - Tree state:
TreeAllocation,KeystoneAllocation - Gameplay:
QuestProgress,FactionRep - Social:
Guild,GuildMembership,ChatMessage,CoOpSession - Operational:
RegionalEvent,Subscription
Content (regions, factions, nodes, keystones, quests, NPCs) is NOT stored in Postgres as foreign-keyed rows — it is sourced from @walkrpg/data’s typed instances at boot. Postgres holds per-walker references to content IDs (string columns). This matches D-004 (TypeScript + Zod as data source of truth).
Firebase EU residency posture
Backend uses Path B (NestJS-side Auth shim — Firebase Auth as federation broker only, no PII at rest in US infrastructure). Rationale + GCP provisioning checklist in ops/decisions/2026-05-18-firebase-eu-residency-verification.md.
What this layer does NOT cover (yet)
- NestJS module/service/controller code — phase 8b.
- Prisma migration files — phase 8b.
- Mobile-side step ingest code — when mobile stack ramps.
- WebSocket gateway shape (chat, co-op presence) — phase 11.
- Crafting subsystem — phase 12.
- Watch-native — phase 13.