70 lines
6.7 KiB
Markdown
70 lines
6.7 KiB
Markdown
# 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: a235266bed8f1a7e19518cdd3aa5ed3e0a309b82
|
|
- 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.
|