jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
a146979dad
zlh-grind/Codex/Portal/DECISIONS.md

3.4 KiB
Raw Blame History

Portal - Decisions

Settled

  • Portal should consume API-normalized state, not talk directly to agents for normal status/actions.
  • Portal should not keep fallback direct-agent bridges in the frontend repo once the API owns the supported route.
  • Portal must never add or expose INTERNAL_API_TOKEN in browser/client code.
  • Portal must treat admin/internal API routes as unavailable to normal browser UI; user-facing pages should call user-safe API routes only.
  • Portal server deletion should use DELETE /api/servers/{id} with the logged-in user's JWT, not the legacy DELETE /api/containers/{vmid} path.
  • Portal delete UX should map API responses explicitly, including 409 as Stop host before deleting.
  • Portal compatibility must be revalidated after API control-plane hardening because JWT, ownership, admin, and internal-token boundaries can change response codes without changing UI code.
  • agentStatus === online is not enough by itself for game action eligibility.
  • ready === false does not automatically mean a stopped server is unstartable.
  • Portal should not infer Needs attention from connectable === false; it must prefer specific API/host/operation states before falling back to error labels.
  • game-server readiness and dev-container readiness should remain separate because DEV status is host/agent/IDE oriented while GAME status is game service/connectability oriented.
  • host/container lifecycle actions should be represented as accepted asynchronous operations and polled through API-owned host status rather than treated as completed immediately.
  • server creation progress should be shown on the Servers surface with user-facing phases rather than leaving the user on the create form without progress context.
  • creation progress may begin before the API returns a VMID, but once the VMID exists Portal should reconcile the pending marker to the real server id.
  • stopped/stopping host lifecycle states should not be presented as fresh creating or installing setup work.
  • IDE controls should stay compact and colocated with IDE readiness indicators on console and server-list surfaces.
  • backup actions should not be blocked purely by frontend readiness assumptions when backend can decide validity.
  • Portal is now tracked on a Node 24 baseline aligned with the API runtime line.
  • Portal linting should use the current ESLint / Next 16-compatible path rather than removed next lint behavior.
  • confirmed-unused HUD wrapper components and stale legacy CSS should stay removed rather than being reintroduced as dead scaffolding.
  • runtime/tooling cleanup is allowed when it preserves user-visible behavior and keeps lint/build green.
  • Portal should preserve compatibility with API auth and hosted IDE flows even when API token verification is tightened.
  • dashboard summary/spotlight UI should be backed by real API data and should not advertise routes that Portal does not actually implement.
  • onboarding tour targets must stay aligned with the real navigation structure.
  • billing, profile, and similar authenticated account surfaces should stay within the hub/dashboard shell unless there is a deliberate UX reason not to.

Tracking rule

  • when Portal work completes, remove it from OPEN_ITEMS.md
  • if it changes long-lived UX/state model assumptions, update CURRENT_STATE.md or this file
  • after API hardening, verify Portal routes by behavior rather than assuming old 401/403/404 semantics are unchanged