NianAIGC/.project-docs/30-worklog/tasks/20260812-next-go-architecture-4d81e2.md

Task: Assess Next.js frontend and Go backend architecture

Identity

• Task ID: 20260812-next-go-architecture-4d81e2
• Mode: Feature
• Branch: codex/20260812-next-go-architecture-4d81e2-next-go-architecture
• Worktree: D:\Datas\OthersProjects\NianAIGC-next-go-architecture-4d81e2
• Base commit: a235266bed
• Owner: codex
• Status: Ready for Integration

Scope

• Assess whether the current Next.js full-stack application can become a Next.js frontend with a Go backend.
• Inspect the current API, server modules, authentication, PostgreSQL, asynchronous worker, storage, provider, billing, and SSR coupling surfaces.
• Compare a combined Go API/worker modular monolith, a Next BFF strangler migration, and separate Go API/worker workloads.
• Recommend a target architecture and migration boundary without changing application or deployment code.

Intent And Constraints

• Challenge the premise that this is a direct deployment-only split; distinguish feasibility from migration cost.
• Preserve the existing HTTP, cookie, multi-tenant, job-claim, wallet-idempotency, and migration contracts during any future rewrite.
• Prefer a same-origin deployment boundary to avoid introducing CORS and cross-site cookie complexity.
• Keep confirmed repository facts separate from recommendations and assumptions that require production evidence or human direction.
• Treat the accepted ACK-001 worker/Web ownership boundary as authoritative until a replacement architecture decision is approved.

Outcome

• On 2026-08-12, the user explicitly confirmed the recommended target architecture: same-origin Next.js frontend plus a Go modular-monolith backend, initially retaining two long-lived Pods and embedding the task loop in Go.
• Confirmed that the architecture can become a Next.js frontend plus Go backend, but it requires an equivalent backend rewrite rather than a command or manifest change.
• Counted 45 app/api route files with 64 HTTP handlers and identified approximately 10.7k lines of directly affected TypeScript server/auth/provider implementation; a behavior-compatible migration is estimated at roughly 10k-14k equivalent implementation lines plus tests and infrastructure.
• Recommended a same-origin ACK target: Ingress routes pages to Next.js and API/file paths to a Go modular monolith. Go owns authentication, RDS, OSS, providers, billing, Webhooks, and initially an internal worker loop; Next.js retains rendering and HTTP calls but no database or provider secrets.
• Recommended retaining the PostgreSQL claim_generation_jobs and billing_post_wallet_entry functions as concurrency authorities rather than replacing them with Go in-memory locks.
• Recommended a strangler migration that freezes the current HTTP/Cookie contract, migrates vertical slices with shadow reads and single-owner writes, and cuts the worker over only after the old worker is stopped and in-flight locks are handled.
• Determined that the recommended initial steady state remains two long-lived Pods (Next x1 + Go x1). Separating the Go API and Go worker creates a third workload and should follow demonstrated scaling or failure-isolation needs rather than be the default first step.
• Confirmed that retaining SSR means Next.js remains a server process even when it no longer accesses the database; a truly static frontend requires client-side authentication and page-guard changes.
• No application, database, or deployment files were changed.

Verification

• Read the current project memory, accepted RDS/ACK decisions, architecture documents, deployment manifests, API routes, server modules, auth code, worker script, and PostgreSQL migration contract from base commit a235266.
• Independently reviewed the migration surface, modular-monolith design, BFF strangler design, separate API/worker design, and compatibility risks using bounded parallel agents.
• Cross-checked the critical session, tenant-isolation, job-claim, wallet-idempotency, provider-recovery, storage, readiness, and migration contracts against current code and SQL.
• Final read-only architecture review returned PASS after requiring explicit limits on per-path strangler routing, SSR session introspection, the full cookie contract, side-effect-free shadowing, worker drain/cutover, and coupled API/worker scaling.
• No live traffic profile, Go prototype, RDS integration run, provider call, or ACK rollout was performed.

Follow-ups

• Human direction is now confirmed for replacing ACK-001 with the initial two-Pod modular-monolith target; canonical promotion still requires the serialized Integration Gate.
• Decide whether Go must parse existing zhinian_session cookies or whether one forced re-login at cutover is acceptable.
• Confirm external /api/v1 compatibility obligations, expected traffic/backlog, team ownership of the Go codebase, and whether SSR must be retained.
• If approved, first create executable HTTP/Cookie golden tests and a migration proposal; do not begin with a big-bang route rewrite.

Promotion Candidates

• Target: .project-docs/10-decisions/decision-index.md and a new accepted architecture decision. Proposal: replace ACK-001 with a same-origin Next.js frontend and Go backend boundary, initially using a Go modular monolith with an internal worker loop and retaining PostgreSQL as the job and billing concurrency authority. Evidence: current Next.js owns all business logic and RDS access while the Node worker only invokes an internal HTTP tick; the assessed migration surface and alternatives are recorded in this task outcome. Future impact: changes application ownership, secrets, deployments, API compatibility policy, worker lifecycle, scaling, and rollback strategy. Semantic conflicts: conflicts with accepted ACK-001, which assigns database access to the Next Web workload and requires the Worker to call Web over HTTP without database credentials. Human confirmation required: received from the user on 2026-08-12; serialized Integration Gate promotion remains pending.

• Target: .project-docs/20-architecture/system-overview.md, module-boundaries.md, and data-flow.md. Proposal: after the replacement decision is accepted and implemented, document Next.js as a rendering/client module and Go as the owner of identity, jobs, assets, billing, administration, RDS, OSS, providers, Webhooks, and asynchronous execution. Evidence: the recommended deep-module boundaries and same-origin routing seam in this task outcome. Future impact: future feature work and deployment configuration will use the Go HTTP interface instead of importing Next.js server modules. Semantic conflicts: must not be promoted while the existing Next.js implementation and ACK-001 remain authoritative. Human confirmation required: yes.