75 lines
5.6 KiB
Markdown
75 lines
5.6 KiB
Markdown
# 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
|