ADR-003: Next.js Frontend And Go Backend Target

Status

Accepted target; Go implementation merged into main on 2026-08-14 (see .project-docs/30-worklog/current-state.md); first production deployment pending — there is no legacy production instance, so no cutover applies (see DEP-001 in the decision index)

Date

2026-08-12

Context

The integrated application currently runs as a Next.js full-stack Web workload plus a Node process that periodically calls an internal Worker tick endpoint. Next.js owns browser rendering, HTTP routes, authentication, PostgreSQL access, task execution, billing, providers, storage, and Webhooks. This makes the deployment operationally compact, but keeps the UI framework and the complete business backend in the same runtime.

The user explicitly approved a long-term split in which Next.js is the frontend and a Go modular monolith owns the backend. The user later clarified that this integration records design and progress only; it does not authorize or claim a completed code migration.

Decision

The approved target is a same-origin ACK topology with two long-lived workloads:

Next.js serves pages, static assets, and SSR. It calls Go over HTTP and does not own RDS, provider, OSS, billing, or migration credentials.
Go owns the existing /api/**, /uploads/**, and /generated-results/** contracts; identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness, and an initially embedded WorkerLoop.
RDS PostgreSQL remains the source of relational truth and cross-instance concurrency.
The one-shot, versioned PostgreSQL migration Job remains separate.
Split the embedded WorkerLoop into a third workload only after independent scaling or failure-isolation needs are demonstrated.

The implementation must preserve the existing HTTP and Cookie Interface, multi-tenant authorization, idempotency, task state, wallet, storage, and Webhook behavior. It must continue calling claim_generation_jobs and billing_post_wallet_entry; Go process-local locks cannot replace these database functions.

Until the implementation is complete and verified, the existing ACK-001 Web/HTTP-polling-Worker architecture remains the deployed and source-code truth.

Rationale

Establishes clear runtime and Secret ownership between UI and backend.
Allows backend lifecycle, testing, and future scaling to evolve independently of Next.js.
Removes the internal HTTP tick seam once the Go WorkerLoop is production-ready.
Keeps the initial workload count at two rather than introducing a separate API and Worker before evidence justifies it.
Preserves the already-reviewed PostgreSQL concurrency and migration contracts.

Consequences

The migration is a substantial behavior-compatible rewrite across TypeScript and Go, not a deployment-only change.
Next.js can remain SSR but is database-free; static export is a separate future choice.
Go API replica count initially also changes WorkerLoop concurrency and provider/RDS load.
Executable compatibility tests and reversible, single-writer cutover are mandatory.
Current code, manifests, and configuration remain unchanged by this ADR.

Supersedes

ACK-001 after the Go implementation and cutover are complete. ACK-001 remains the transition-state operational decision until then.

.project-docs/10-decisions/proposals/20260812-go-backend-migration-6f4a92__next-go-architecture.md
.project-docs/30-worklog/tasks/20260812-next-go-architecture-4d81e2.md
.project-docs/30-worklog/tasks/20260812-go-backend-migration-6f4a92.md
RDS-001 and RDS-002 in .project-docs/10-decisions/decision-index.md

3.6 KiB Raw Blame History