wangxuming/NianAIGC
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reconcile canonical memory with merged Go backend

Browse Source
This commit is contained in:
zn-admin committed 2026-08-14 07:19:41 +08:00
1 parent f10cdd9695
commit eacb4c67de
14 files changed
+171 -57
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.project-docs/20-architecture/system-overview.md
+17 -14
View File
@@ -2,34 +2,36 @@
## Current Architecture
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.
The deployed production architecture is the Next.js Web workload plus a separate HTTP-polling Node 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.
ADR-003's Go backend is implemented and merged into `main` under `backend/` (see the Module Map), but no Go workload is deployed and no production traffic is routed to it. Until the single-writer cutover passes its compatibility checks, the Next.js/Node topology above remains the deployed and authoritative truth.
## 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. |
| 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. | Existing; unchanged until cutover. |
| Go backend | Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness | Owns relational access and initially embeds WorkerLoop. | Implemented in `backend/` and merged; unrouted in production. |
| RDS PostgreSQL | Relational state and cross-instance concurrency | Retains versioned migrations and both concurrency-sensitive database functions. | Production database; migrations 0001/0002 apply at rollout. |
| Migration Job | Schema and application-role grants | Remains one-shot and separate from long-lived workloads. | Existing Job; migration 0002 included. |
| 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 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.
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`). The Go implementation is complete and merged; deployment and traffic cutover are not.
## 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`. |
| 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 | No direct database connection or RDS Secret. |
| PostgreSQL adapter | Backend selection, Pool lifecycle, TLS, parameterized queries, transactions, readiness | Server-only module at `lib/server/database.ts`. |
| RDS PostgreSQL | Accounts, assets, jobs, usage, templates, billing state | Schema managed by versioned migrations. |
| 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 Web horizontally. |
| Runtime/object storage | Uploads, generated assets, and logs | Container-local/PVC by default; use OSS/shared storage before scaling horizontally. |
## Important Boundaries
@@ -37,6 +39,7 @@ Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads
- 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 merged Go implementation must not be routed in production before the cutover review; Next Route Handlers, Secrets, and ACK manifests stay under their current owners until then.
## Related Decisions
@@ -45,4 +48,4 @@ Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads
## Last Updated
2026-08-12
2026-08-14