Repository navigation
Description
Status: BLOCKED — blocked: architecture-conflict
Proposed and deliberately not accepted as-is. This issue documents the analysis so it is not re-litigated, and records exactly what a future contract decision would have to change to unblock it.
Covers the SSR meta-frameworks as one record because they share an identical block reason:
- Next.js (React)
- Nuxt (Vue)
- SvelteKit (Svelte)
Why it is blocked
The frontend contract (frontends/README.md, docs/ARCHITECTURE.md) fixes the frontend as:
- a static SPA, whose production image is a long-running static-file server on internal port 8080 with SPA fallback, reached only through the gateway;
- a component that holds no auth state — not even a token — and makes same-origin
/api/v{n}JSON calls, askingGET /auth/sessionwho is logged in.
The gateway already supports two delivery mechanisms: proxy an upstream through FRONTEND_URL, or serve a local static build through SPA_ROOT. FRONTEND_URL can technically point at a long-running dynamic server, so hosting a Node process behind the gateway is not itself the blocker. Both documented modes currently serve the static-SPA frontend contract.
True SSR still conflicts with that contract on three points:
- Frontend contract. Headline-mode SSR runs a per-request rendering server with server loaders/route handlers, rather than shipping a static SPA from the standard frontend image.
- Identity boundary. Every current gateway strips the browser's
Cookieheader before proxying frontend traffic. The renderer receives neither the opaquestackverse_sessionkey nor an access token, so it cannot render authenticated bookmarks or call/apion the user's behalf. This is deliberate: browser cookies and tokens are gateway-only state. - New cross-gateway protocol. Personalized SSR therefore needs a trusted gateway → renderer identity/data-relay contract implemented consistently by every gateway.
FRONTEND_URLalone does not provide that contract.
Run purely client-side (Next output: 'export', Nuxt ssr: false, SvelteKit adapter-static + SPA fallback), each collapses back to plain React/Vue/Svelte — redundant with existing frontends and it undersells the framework (its reason to exist is SSR). So the low-risk form adds ~no comparison value, and the high-value form changes the architectural axis.
How an implementation could look
A. CSR-only (technically unblocked today, but low value):
- Next →
next buildwithoutput: 'export'; Nuxt →nuxt generatewithssr:false; SvelteKit →@sveltejs/adapter-staticwith afallback: index.html. - Serve the emitted static bundle on port 8080 with SPA fallback; load
spec/design/*.cssverbatim; consume/apiJSON;/auth/session,XSRF-TOKEN→X-XSRF-TOKEN, i18n bundle — identical to the other frontends. - Verdict: this is "React/Vue/Svelte again," so it would not earn a matrix row on its own.
B. True SSR (requires a contract decision — see below):
- A per-frontend Node SSR server sits behind the gateway on
FRONTEND_URL; the browser still has one public origin and talks only to the gateway. - Under the current contract the gateway removes cookies before forwarding that request, so the renderer can only produce anonymous/public HTML or defer personalized loading to client-side code.
- An extended architecture would define a trusted identity/data relay from gateway to renderer and the renderer's server-to-server path back to
/api, while keeping access tokens at the gateway. - This is effectively a two-hop, server-rendered BFF — a genuinely different architecture, not a drop-in frontend variant.
What would unblock it
A deliberate docs/ARCHITECTURE.md + docs/INTENT.md + frontends/README.md decision to support a server-rendered frontend tier, replace the static-image requirement for that tier, and specify a gateway → renderer identity/data-relay protocol that keeps tokens at the edge. Because this changes the shared gateway contract, every gateway would need the same behavior and acceptance coverage. Per AGENTS.md ground rules this is assumed rejected by default. Until then, blocked.
References
- docs/INTENT.md — stateless applications, session at the edge, no tokens in the browser.
- frontends/README.md — static-file image, no auth state, JSON
/apicontract. - docs/ARCHITECTURE.md — gateway as the single BFF.
- docs/INVARIANTS.md — shared gateway and frontend boundaries.
- gateways/README.md —
FRONTEND_URL/SPA_ROOTdelivery modes.
Activity