🏛️ Platform Architecture
Lifecycle note: Pages in this tree are mostly current. Exception: Realtime Comms is mixed (LiveKit client/RPC/manifests exist; Helm roadmap sections remain proposed). Secrets/Vault language may describe intended control plane while live cutover remains blocked — see Nakama multiplayer and Secrets runbook.
Executive Summary Defines the high-level platform boundaries, technology stack, routing, and data flow of the Funday ecosystem. When to change: Update this when introducing a new infrastructural layer, changing the routing logic, shifting core technologies (like Nakama, SvelteKit, or Kubernetes), or changing secret handling policy.
Find
- Identity
- Game Plugins
- Bridge
- Lobby, Matchmaking & Nakama
- Current Caveats: Nakama Multiplayer Audit (2026-07-15)
Understand
Current platform shape
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | SvelteKit 2 + Svelte 5 + Tailwind 4 + DaisyUI 5 | Web UI, game lobby, matchmaking, /play/[id] host shell |
| Backend | Nakama 3.32.0 + TypeScript runtime modules | Auth, matchmaking, leaderboards, RPCs, authoritative match state |
| Orchestration | K3s + Agones | Platform services plus dedicated game-server fleet management |
| Edge | nginx TLS → Traefik | Public HTTPS, subpath routing, WebSocket upgrade |
| Database | PostgreSQL 15.6+ in postgresql namespace | Real Nakama user/game data |
| Cache | Redis 7.2+ in funday-platform namespace | Session/cache/pub-sub support |
| Monitoring | Grafana + Prometheus | Metrics, dashboards, alerting rules |
| Docs | Quartz 5 static wiki | Source: /home/usr/funday/dev/docs; served at /dev/docs/wiki/ via quartz-wiki.service (operator/developer documentation) |
| AI Agents | Ompcord/Amy + local omp tooling | Discord and CLI assisted development |
Request routing
flowchart TD User["User (:443)"] --> Nginx["Nginx (TLS termination)"] Nginx -->|"/dev/docs/wiki/"| Quartz["Quartz :8080 (funday/dev/docs)"] Nginx -->|"/console, /v2/console"| Traefik1["Traefik (:32443)"] --> NakamaConsole["nakama-console-svc (:7351)"] Nginx -->|"/v2, /ws"| Traefik2["Traefik (:32443)"] --> Nakama["nakama (:7350)"] Nginx -->|"/grafana, /prometheus"| Traefik3["Traefik (:32443)"] --> Monitoring["monitoring ingresses"] Nginx -->|"/*"| SvelteKit["SvelteKit (:3000)"]
| Path | Target |
|---|---|
/console, /v2/console | Traefik to Nakama console. |
/v2, /ws | Traefik to Nakama HTTP/WebSocket. |
/grafana, /prometheus | Monitoring ingresses. |
/* | SvelteKit frontend on systemd. |
Nakama deployment
| Setting | Current source-backed value |
|---|---|
| Image | heroiclabs/nakama:3.32.0 |
| Deployment | gitops/platform/base/nakama/ via Argo nakama-app (intended) |
| Namespace | funday-platform |
| Replicas | GitOps intended 3 (deployment.yaml); live may differ — verify |
| Runtime path | /nakama/data/modules |
| Runtime module source | Host path /home/usr/funday/nakama-modules |
| Game mount | Host path /home/usr/funday/games mounted under runtime modules |
| HTTP port | 7350 |
| Console port | 7351 |
| Metrics port | 9100 |
| Readiness/liveness | /healthcheck on port 7350 |
Secret handling
INTENDED vs LIVE: GitOps declares Vault + ESO Argo apps. Workloads still consume materialized Kubernetes Secrets (
secretKeyRef/envFrom). Do not assume Vault is live until cluster-verified. See Secrets runbook.
🔒 Secret values are intentionally not documented here. This wiki is served at
https://funday.gg/dev/docs/wiki/viaquartz-wiki.service; keep credentials in K8s Secrets, systemd env files, or local.envfiles. Document names and locations only.Historical: Previously documented as live at
ssot.funday.gg(/home/usr/funday/ssot.funday.gg); that directory is missing. It was Quartz, not Hugo.
| Setting | Where it lives | Browser exposure |
|---|---|---|
| Database connection | Nakama deployment/config secret | Never |
| Session / refresh encryption keys | Nakama config | Never |
| Console credentials/signing key | Nakama config | Never |
| Socket server key | Nakama config | Never |
| Runtime HTTP key | Server-side env / Nakama config | Never |
| Public Nakama host/port/SSL | PUBLIC_NAKAMA_* frontend env | Safe |
Server identity
| Field | Value |
|---|---|
| Domain | funday.gg |
| Wiki | https://funday.gg/dev/docs/wiki/ (quartz-wiki.service) |
| Server IP | 213.136.90.143 |
| OS | Debian 13 (trixie) |
Related
- Play Shell Cheatsheet — Visual map of what you see on /play/[gameId] and how the pieces talk to each other
Historical supporting
- Historical supporting pages (legacy unique recoveries; not current SSOT)
- SSOT Bible (historical)
- historical roadmap