docs: integrate approved Next Go architecture

.project-docs/10-decisions/adr-003-next-go-target.md

@@ -0,0 +1,56 @@
+# ADR-003: Next.js Frontend And Go Backend Target
+
+## Status
+
+Accepted target; implementation pending
+
+## 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.
+
+## Related
+
+- `.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`

.project-docs/10-decisions/decision-index.md

@@ -7,6 +7,7 @@
 | RDS-001 | Production persistence uses explicit direct PostgreSQL through one server-only adapter; local JSON is explicit development/test mode. | Accepted | 2026-08-12 | Server stores and scripts | `ZHINIAN_DATA_BACKEND=postgres` fails closed and never silently falls back. |
 | RDS-002 | Database changes use versioned, checksummed, advisory-locked migrations executed by a one-shot deployment Job. | Accepted | 2026-08-12 | Database schema and ACK rollout | Migrations do not run in each Web pod init container. |
 | ACK-001 | Worker remains an HTTP poller and does not receive RDS credentials; Web owns database access. | Accepted | 2026-08-12 | ACK workloads | Worker calls the internal Web Service with a shared internal token. |
+| ADR-003 | Target architecture is a same-origin Next.js frontend plus Go modular-monolith backend with an initially embedded WorkerLoop. | Accepted target; implementation pending | 2026-08-12 | Application and ACK architecture | Current ACK-001 topology remains authoritative until code migration and cutover pass the required compatibility tests. See `adr-003-next-go-target.md`. |
 
 ## Superseded Decisions