From 8551d14591c3f5546fce6997f6fea39b64ba8943 Mon Sep 17 00:00:00 2001 From: planner-bot Date: Wed, 19 Aug 2026 12:39:33 +0000 Subject: [PATCH] docs: MVP vertical slice planning doc for client-server wiring - Architecture task: ApiClient autoload (HTTP + JWT + error contract) - Implementation task: Login/Register UI wired to /api/auth - Implementation task: Browse worlds screen wired to GET /api/worlds - Validation task: End-to-end smoke test (login + list worlds) --- docs/planning/client-server-wiring.md | 37 +++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/planning/client-server-wiring.md diff --git a/docs/planning/client-server-wiring.md b/docs/planning/client-server-wiring.md new file mode 100644 index 0000000..3c3419b --- /dev/null +++ b/docs/planning/client-server-wiring.md @@ -0,0 +1,37 @@ +# MVP Vertical Slice: Client-Server Wiring — Plan + +## Goal +Prove the real Godot client and the real backend can talk: **a user can register/log in +and see a list of worlds from the game client**. Nothing more. Gameplay, join-a-world, +chat, avatar, Discovery search/tags/trending, Social/Economy/Trust & Safety are all +explicitly out of scope. + +## Verified backend contract (as of this writing) +- `POST /api/auth/register` — JSON body `{username, email, password, date_of_birth}`. + `date_of_birth` is a `YYYY-MM-DD` string. Returns `201 {access_token, token_type}`. + Rejects under-18 with `400`. +- `POST /api/auth/login` — OAuth2 **form-encoded** (`application/x-www-form-urlencoded`) + `username` + `password` (this is NOT a JSON endpoint). Returns `{access_token, token_type}`. +- `GET /api/worlds` — **requires auth** (`CurrentUser`), returns a JSON array of + `{id, name, description, visibility, owner_id, created_at}`. There is no unauthenticated + public-worlds path, so the worlds list screen can only be shown after login/register. +- `GET /api/health` — unauthenticated, `{status, app}`. +- Base URL: uvicorn default `http://127.0.0.1:8000` (must be configurable in the client). +- CORS is irrelevant to the native Godot `HTTPRequest` client (no browser origin). + +## Task breakdown +| # | Type | Task | Depends on | +|---|------|------|-----------| +| 1 | architecture | `ApiClient` autoload: HTTP + JWT storage + error contract | — | +| 2 | implementation | Main-menu **login** wiring (form-encoded) | 1 | +| 3 | implementation | Main-menu **register** wiring (JSON + age gate) | 2 | +| 4 | implementation | **World list** screen consuming `GET /api/worlds` | 2 | +| 5 | testing | End-to-end headless smoke test + manual verify | 1,3,4 | + +## Design decisions captured (resolved in task 1) +- Token storage: in-memory singleton property for the MVP; a `save_to_disk` seam is left + open but not required yet (no re-login on restart in this slice). +- Error contract: every call returns a discriminated result (`ok`/`error`) so callers + never crash on network failure; non-2xx surfaces `{status, detail}` from the backend. +- Base URL: read from a ProjectSetting, defaulting to `http://127.0.0.1:8000`. +- Login is form-encoded; register is JSON — the client helper must support both content types. -- 2.52.0