docs: integrate static frontend architecture
This commit is contained in:
brother7 committed
1 parent
b14b4fced7
commit
bb50d06d1d
13 files changed
+243
-82
No files matched your search
@@ -4,47 +4,60 @@
|
||||
|
||||
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 `498c2fa` and authenticated `/create` currently triggers a production RSC error. The fixed repository revision implements the ADR-003 boundary: Next.js serves pages/static/SSR without database credentials and refreshes authenticated SSR through internal Go `/api/auth/me`; the checked-in production topology assigns backend routes, database-backed authorization, RDS access, and the embedded WorkerLoop to Go. The updated Web image and ACK configuration have not yet been deployed, and the authenticated smoke test remains open. Local development remains a separate Next.js full-stack shape with explicit PostgreSQL or local JSON stores and the HTTP-polling Node Worker.
|
||||
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 Next.js frontend plus Go modular-monolith backend:
|
||||
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 |
|
||||
|---|---|---|---|
|
||||
| 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. |
|
||||
| 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. | 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. |
|
||||
| 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 page/static paths to Next.js and `/api`, `/uploads`, and `/generated-results` to Go. Production is already online; confirming that the live cluster matches this desired state is part of the repair rollout. The approved initial target is two long-lived Pods (`Next x1 + Go x1`).
|
||||
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 |
|
||||
|---|---|---|
|
||||
| Next.js Web | Local full-stack browser/API routes and stores; fixed production revision serves pages/static/SSR plus the internal Go identity bridge | Local development may use direct stores. The database-free production configuration in `498c2fa` is not yet deployed. |
|
||||
| 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`. |
|
||||
| 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). |
|
||||
| Migration Job | Retained one-shot migration artifact | Not used for the first production deployment; the operator executes versioned SQL and grants manually. |
|
||||
| Runtime/object storage | Uploads, generated assets, and logs | Container-local/PVC by default; use OSS/shared storage before scaling horizontally. |
|
||||
| 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.
|
||||
- In the approved production split topology, database credentials belong to Go and the manual migration operator; the fixed Next.js Web configuration and any local-only Node Worker do not receive them.
|
||||
- The live production environment requires post-deployment validation against RDS/OSS/provider/Webhook dependencies; Next Route Handlers stay in the repository for local development.
|
||||
- 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 target: `ADR-003`; production is online, but its exact live realization must be confirmed from cluster evidence.
|
||||
- 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
|
||||
|
||||
Reference in new issue
Block a user