refactor: serve static frontend with Go APIs

2026-08-16 20:47:45 +08:00
1 parent 763d2f0648
commit b14b4fced7
@@ -0,0 +1,58 @@
+# Proposal: Static Web With Go-Only Runtime APIs
+
+## Source
+
+- Task: `20260816-static-frontend-go-api-4f8c2a7d`
+- User confirmation: the frontend must be a static page set and every API must
+  be provided by Go.
+
+## Proposed Decision
+
+Replace ADR-003's retained Next.js SSR responsibility with a stricter runtime
+boundary:
+
+- Next.js is a build tool. Its production output is the static `out/` tree.
+- An unprivileged Nginx workload serves pages and static assets only.
+- The browser calls same-origin `/api`, `/uploads`, and `/generated-results`;
+  Ingress routes those paths directly to the Go modular monolith.
+- Go exclusively owns authentication, authorization, Cookie signing and
+  validation, PostgreSQL, billing, providers, storage, Webhooks, health,
+  readiness, and the embedded WorkerLoop.
+- Client route guards are presentation behavior only and never an
+  authorization boundary.
+- The Web workload receives no runtime ConfigMap, session Secret, database
+  credential, provider Secret, or internal Go URL.
+
+## Evidence
+
+- Clean `next build` exports every application route as static content.
+- Static architecture tests fail if Next Route Handlers, Middleware, server
+  page imports, image optimization, or a non-same-origin auth seam return.
+- The checked-in Go route surface covers every browser request; the single
+  discovered billing response casing defect was corrected and regression
+  tested.
+- Full Vitest, TypeScript, Go, and ACK assertion suites pass.
+
+## Future Impact
+
+- Production Web availability is independent of PostgreSQL, Go internal DNS,
+  and session-secret injection; API failures become visible client errors
+  rather than fatal RSC rendering errors.
+- New business endpoints must be implemented in Go. Reintroducing Next Route
+  Handlers, Middleware authentication, or SSR Cookie access violates the
+  accepted boundary.
+- Schema creation remains an operator/CI concern until a dedicated migration
+  image is justified; it must not reuse the static Web image.
+
+## Semantic Conflicts
+
+- ADR-003 currently says Next serves SSR and that static export is a future
+  choice.
+- Canonical current-state and architecture documents still describe the
+  internal Next-to-Go auth bridge, retained Next Route Handlers, a Migration
+  Job artifact, and local Node Worker behavior as part of the supported shape.
+
+## Human Confirmation
+
+No further confirmation is required. The user explicitly selected this pure
+static frontend and Go-only API architecture in the source task.