System Overview

Current Architecture

The first production deployment is online at https://nianxxaigc.nianxx.cn. The public /api/ready endpoint has been observed returning HTTP 200 with PostgreSQL configured. The exact live Service owner for each path has not been confirmed through cluster configuration or logs, so the deployed routing shape is not inferred here.

The live revision predates b14b4fc and authenticated /create currently triggers a production RSC error. The repository now implements the stricter ADR-003 boundary: Next.js statically exports pages, unprivileged Nginx serves them, the browser reads identity from Go /api/auth/me, and Go owns every runtime API/file route plus database-backed authorization and the embedded WorkerLoop. The new images and ACK configuration have not yet been deployed.

Approved Target Architecture

The accepted target in ADR-003 is a same-origin static Next.js export on Nginx plus a Go modular-monolith backend:

Target component	Responsibility	Constraint	Implementation state
Static Web	Next.js build output (`out/`) and browser UI served by Nginx	No SSR, Middleware, Route Handlers, runtime configuration, application Secret, or internal Go URL.	Implemented and statically verified in `b14b4fc`; deployment pending.
Go backend	Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness	Owns relational access and embeds the WorkerLoop in the approved topology.	Implemented in `backend/`; production is online, but exact live path ownership is not asserted without cluster evidence.
RDS PostgreSQL	Relational state and cross-instance concurrency	Retains versioned migrations and both concurrency-sensitive database functions.	Repository procedure requires manual SQL (migrations 0001/0002) plus role grants; live execution evidence remains to be confirmed.
Schema operator/CI	Schema and application-role grants	Runs versioned SQL outside long-lived workloads; never reuses the static Web image.	First-deployment procedure is manual; no migration Job manifest is shipped.
Alibaba Cloud OSS	Shared generated/uploaded assets	Must be production-ready before horizontal workload scaling.	Still behind a storage Adapter; not validated against real OSS.

The checked-in Ingress routes pages/static assets to Nginx and /api, /uploads, and /generated-results to Go. The approved long-lived workload set is static Web plus Go; Web can scale independently, while Go stays one replica until file storage is shared.

Main Components

Component	Responsibility	Notes
Static Web	Next.js pages/components compiled to `out/`; unprivileged Nginx serves navigation and hashed assets	Browser auth Module calls same-origin Go; client guards are UX only.
Go backend	`cmd/zhinian-api` plus 18 `internal/` packages: identity, administration, assets, billing, usage, jobs, providers, webhook, httpapi, publicapi, application, orchestration, postgres, localstore, logging, settings, templates, prompt	Merged and contract-tested; checked-in manifests route backend paths to Go, while exact live routing remains to be confirmed from the cluster.
Contract fixtures	Language-neutral JSON contracts for auth, admin, assets, billing, http, jobs, logs, providers, settings, usage, webhook under `contracts/`	Shared executable acceptance source for TypeScript and Go consumers.
RDS PostgreSQL	Accounts, assets, jobs, usage, templates, billing state	Schema managed by versioned migrations (0001, 0002).
Schema operator/CI	Executes versioned SQL and grants manually	No Node migration manifest or executable exists in the static Web image.
Runtime/object storage	Uploads, generated assets, and logs	Go `emptyDir` by default; use OSS/shared storage before scaling or replacing the Pod when persistence is required.

Important Boundaries

Production backend selection is explicit and fail-closed; never turn a PostgreSQL configuration failure into local JSON fallback.
Store callers depend on stable store interfaces, not pg or SQL details.
Multi-statement consistency uses one transaction client; atomic job claim and wallet posting remain database functions.
Database credentials and the session-signing Secret belong to Go and the manual schema operator; static Web receives neither.
Browser requests stay same-origin, but Go authorizes every protected API and file request; page visibility is not a security boundary.
Next Route Handlers, Middleware, SSR Cookie access, and production next start are prohibited by the accepted architecture.
The live environment still requires post-deployment validation against RDS/OSS/provider/Webhook dependencies.

Current implementation: RDS-001 and RDS-002 (schema execution now manual SQL per DEP-001).
Accepted implementation: ADR-003 as amended by b14b4fc; production is online, but the new static revision and exact live routing remain unverified.
First-deployment model: DEP-001.

Last Updated

2026-08-16

5.1 KiB Raw Blame History