System Overview

Current Architecture

There is no deployed production architecture yet. Local development keeps the Next.js full-stack Web workload plus the HTTP-polling Node Worker; production server state is stored directly in PostgreSQL through a shared server-only adapter, and development/tests can explicitly use local JSON.

The first production deployment will run the ADR-003 split topology directly: Next.js serves pages/static/SSR, and the merged Go backend under backend/ owns /api, /uploads, and /generated-results. There is no legacy production instance, so there is no cutover and no Node Worker in production — the Go process embeds the WorkerLoop from day one. The deployment artifacts are checked in: backend/Dockerfile (non-root static Go image), deploy/ack/go-api.yaml (Deployment plus Service), and the split-path Ingress in deploy/ack/ingress.yaml; the image build/push and target-cluster validation remain.

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	Implementation state
Next.js frontend	Pages, static assets, SSR, browser UI	Calls Go over HTTP; no RDS/provider/OSS/business Secret.	Local dev also runs its API routes; production serves pages only.
Go backend	Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness	Owns relational access and embeds the WorkerLoop.	Implemented in `backend/` and merged; first production deployment pending.
RDS PostgreSQL	Relational state and cross-instance concurrency	Retains versioned migrations and both concurrency-sensitive database functions.	Schema initialized by manual SQL (migrations 0001/0002) plus role grants.
Migration Job	Schema and application-role grants	Remains one-shot and separate from long-lived workloads.	Manifest retained but not used; initial schema is executed manually.
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.

Ingress will route page/static paths to Next.js and /api, /uploads, and /generated-results to Go from the first deployment. The initial target is two long-lived Pods (Next x1 + Go x1).

Main Components

Component	Responsibility	Notes
Next.js Web	Browser/API routes, domain services, persistence calls, internal Worker tick endpoint	Owns the PostgreSQL pool and `/api/ready` until cutover.
Worker	Periodically invokes the internal Worker tick endpoint	Local development only; production uses the embedded Go WorkerLoop.
PostgreSQL adapter	Backend selection, Pool lifecycle, TLS, parameterized queries, transactions, readiness	Server-only module at `lib/server/database.ts`.
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 into `main`; locally runnable and contract-tested; unrouted in production.
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).
Migration Job	Applies migrations and exact application-role privileges	Must complete before Web rollout.
Runtime/object storage	Uploads, generated assets, and logs	Container-local/PVC by default; use OSS/shared storage before scaling horizontally.

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 are injected only into Web and migration workloads; Worker uses the internal HTTP boundary.
The Go implementation must be validated against non-production RDS/OSS/provider/Webhook dependencies before the first production rollout; Next Route Handlers stay in the repository for local development.

Current implementation: RDS-001 and RDS-002 (schema execution now manual SQL per DEP-001).
Accepted target: ADR-003; it supersedes ACK-001 once the first production deployment runs the Go stack.
First-deployment model: DEP-001.

Last Updated

2026-08-14

4.8 KiB Raw Blame History