docs: integrate approved Next Go architecture

.project-docs/20-architecture/data-flow.md

@@ -9,6 +9,19 @@
 | Schema rollout | ACK migration Job | RDS PostgreSQL | Versioned checksummed migrations under an advisory lock. |
 | Readiness | ACK probe | Web `/api/ready` -> RDS | Verifies connection, 11 runtime tables, required privileges, and 2 functions. |
 
+## Approved Target Flows
+
+These flows become active only after ADR-003 is implemented:
+
+| Flow | Source | Destination | Required behavior |
+|---|---|---|---|
+| Browser UI | Browser | Same-origin Ingress -> Next.js or Go by path | Preserve current URLs; avoid cross-origin Cookie/CORS changes. |
+| SSR identity/data | Next.js | Internal Go HTTP Interface | Forward Cookie and origin; Go remains the sole authorization authority. |
+| Backend persistence | Go Modules | PostgreSQL Adapter -> RDS | Parameterized queries and transactions; fail closed in production. |
+| Task execution | Embedded Go WorkerLoop | RDS claim -> provider -> OSS -> RDS -> Webhook | Bounded concurrency, recoverable leases, one owner for external side effects. |
+| Asset lifecycle | Go Assets | OSS plus RDS metadata | Shared storage required before horizontal scaling. |
+| Schema rollout | Migration Job | RDS | Existing version/checksum/advisory-lock contract remains unchanged. |
+
 ## State Ownership
 
 - Production relational state belongs to RDS PostgreSQL when `ZHINIAN_DATA_BACKEND=postgres`.
@@ -21,6 +34,8 @@
 - Alibaba Cloud ACK resources under `deploy/ack/`.
 - Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing.
 
+In the approved target, the internal Worker HTTP endpoint is removed only after the Node Worker is drained and the Go WorkerLoop is verified. It remains part of the current implementation until that cutover.
+
 ## Last Updated
 
 2026-08-12

.project-docs/20-architecture/module-map.md

@@ -16,6 +16,22 @@
 - Routes and services depend on store interfaces; stores depend on the shared database adapter; the adapter does not depend on domain stores.
 - Worker depends on the internal Web HTTP API, not the database module.
 
+## Approved Target Module Map
+
+The target below is a design contract, not current source layout:
+
+| Target Module | Interface | Implementation notes |
+|---|---|---|
+| Next.js frontend | Pages, SSR, and same-origin browser calls | Forwards Cookie/request context to Go; no direct persistence or domain ownership. |
+| Go Identity | Login/logout/session/password/authorization | Preserves the current signed chunked Cookie and per-request account/organization/sessionVersion validation. |
+| Go Administration | Organizations, accounts, settings visibility, logs, administrative usage | Enforces current super-admin and organization-admin rules. |
+| Go Assets | Register/upload/list/get/delete/download | Uses object-storage Adapter; preserves owner-scoped 404 and storage metadata. |
+| Go Jobs | Submit/query/cancel/retry/claim/execute/terminal transitions/Webhooks | Uses the PostgreSQL claim function and hides provider/retry/refund state. |
+| Go Billing | Quote/wallet/ledger/price/charge/refund/settlement | Uses the PostgreSQL wallet function and integer-fen arithmetic. |
+| Go Usage | Platform/public attribution and usage records | Retains organization/account context and job uniqueness. |
+
+Real internal seams are PostgreSQL transport, object storage, generation providers, and deterministic test dependencies. Avoid one shallow repository Interface per table.
+
 ## Risky Or Sensitive Areas
 
 - `database/migrations/` and the two concurrency-sensitive PostgreSQL functions.

.project-docs/20-architecture/system-overview.md

@@ -4,6 +4,22 @@
 
 The Next.js application runs as a Web workload with a separate HTTP-polling Worker. Production server state is stored directly in PostgreSQL through a shared server-only adapter; development and tests can explicitly use local JSON. ACK deploys database migration, Web, Worker, Service, and Ingress resources separately.
 
+This remains the implemented and deployable architecture. No Go backend code or Go deployment resources have been integrated.
+
+## Approved Target Architecture
+
+The accepted target in ADR-003 is a same-origin Next.js frontend plus Go modular-monolith backend:
+
+| Target component | Responsibility | Constraint |
+|---|---|---|
+| Next.js frontend | Pages, static assets, SSR, browser UI | Calls Go over HTTP; no RDS/provider/OSS/business Secret. |
+| Go backend | Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness | Owns relational access and initially embeds WorkerLoop. |
+| RDS PostgreSQL | Relational state and cross-instance concurrency | Retains versioned migrations and both concurrency-sensitive database functions. |
+| Migration Job | Schema and application-role grants | Remains one-shot and separate from long-lived workloads. |
+| Alibaba Cloud OSS | Shared generated/uploaded assets | Must be production-ready before horizontal workload scaling. |
+
+Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads`, and `/generated-results` to Go. The initial target remains two long-lived Pods (`Next x1 + Go x1`). This target is not yet implemented.
+
 ## Main Components
 
 | Component | Responsibility | Notes |
@@ -24,7 +40,8 @@ The Next.js application runs as a Web workload with a separate HTTP-polling Work
 
 ## Related Decisions
 
-- `RDS-001`, `RDS-002`, `ACK-001` in the decision index.
+- Current implementation: `RDS-001`, `RDS-002`, and `ACK-001`.
+- Accepted target: `ADR-003`; it supersedes ACK-001 only after verified implementation and cutover.
 
 ## Last Updated