# System Overview

## Current Architecture

The first production deployment is online at `https://nianxxaigc.nianxx.cn`.
An earlier public `/api/ready` response returned HTTP 200 with PostgreSQL
configured, but the latest observed Go API startup fails during bootstrap
because the RDS endpoint refuses TLS. The exact live Service owner and deployed
image revision for each path have not been confirmed through cluster
configuration or logs.

The repository implements the strict 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. Revision `ed97814` additionally
forces PostgreSQL plaintext for the TLS-refusing RDS endpoint. Deployment and
live validation of that exact revision remain pending.

## 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`; publish the image from `ed97814` with the matching Go release. |
| 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. Clients enforce plaintext (`sslmode=disable`); use only the internal endpoint protected by VPC, security groups, and an RDS allowlist. | Repository procedure requires manual SQL (migrations 0001/0002) plus role grants; live plaintext bootstrap/readiness and network-isolation evidence remain 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.
- PostgreSQL transport is code-enforced plaintext because the selected RDS
  endpoint refuses TLS. Database traffic must stay on the Alibaba Cloud private
  network and be restricted with VPC, security-group, and allowlist controls.
- 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.

## Related Decisions

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

## Last Updated

2026-08-16