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
@@ -1,28 +1,35 @@
|
||||
# Data Flow
|
||||
|
||||
## Local Full-Stack Flows
|
||||
## Development Flows
|
||||
|
||||
These repository flows remain available for local development and do not establish which Service currently owns a path in the live production cluster.
|
||||
`next dev` serves the page development loop; runtime API behavior still belongs
|
||||
to a separately running Go backend or an equivalent same-origin development
|
||||
proxy. Legacy TypeScript server adapters remain unreferenced cleanup candidates
|
||||
and are not a supported production path.
|
||||
|
||||
| Flow | Source | Destination | Notes |
|
||||
|---|---|---|---|
|
||||
| Web persistence | Routes/services/stores | PostgreSQL adapter -> RDS | Parameterized SQL; related statements share one Pool client transaction. |
|
||||
| Worker processing | Worker process | Internal Web Service `/api/internal/worker/tick` | Authenticated by internal token; Worker has no RDS credentials. |
|
||||
| Browser UI development | Browser | Next dev page server | Pages/components only; no Next API or Middleware. |
|
||||
| Runtime API development | Browser/tooling | Go HTTP server | Same contracts as production; Go localstore is explicit non-production mode. |
|
||||
| Schema rollout | Manual SQL execution by the deployment operator | RDS PostgreSQL | Versioned checksummed files under `database/migrations/`; 0001 then 0002, then application-role grants. |
|
||||
| Readiness | ACK probe | Web `/api/ready` -> RDS | Verifies connection, 11 runtime tables, required privileges, and 2 functions. |
|
||||
|
||||
## Approved Target Flows
|
||||
|
||||
The Go implementation and desired ACK routing for these flows are present in the repository. Production is already online, but its exact live Service ownership has not been confirmed from cluster configuration or logs:
|
||||
The implementation and desired ACK routing are present in `b14b4fc`.
|
||||
Production is already online, but the static revision and exact live Service
|
||||
ownership have not been confirmed from cluster configuration or logs:
|
||||
|
||||
| Flow | Source | Destination | Required behavior |
|
||||
|---|---|---|---|
|
||||
| Browser UI | Browser | Same-origin Ingress -> Next.js or Go by path | Preserve current URLs; avoid cross-origin Cookie/CORS changes. |
|
||||
| SSR identity | Next.js `getOptionalAuthSession()` | Internal Go `GET /api/auth/me` | Implemented in `498c2fa` when `ZHINIAN_GO_INTERNAL_BASE_URL` is configured: forward only enumerated `zhinian_session` Cookie chunks, use no-store transport, strictly validate authenticated/anonymous response shape and identity binding, and fail closed on bridge errors. No unrelated Cookie or origin forwarding. Without the URL, local full-stack mode keeps direct-store authorization. The live revision does not yet contain this fix. |
|
||||
| Browser UI | Browser | Same-origin Ingress -> Nginx static Web | Preserve current page URLs; Nginx performs no application logic. |
|
||||
| Browser identity | Browser auth Module | Same-origin Ingress -> Go `GET /api/auth/me` | Browser automatically sends HttpOnly Cookie; validate anonymous/authenticated response shapes, keep no token in JavaScript, and use client guards only for UX. |
|
||||
| Browser business/file requests | Browser components | Same-origin Ingress -> Go `/api`, `/uploads`, `/generated-results` | Go revalidates session/account/organization/sessionVersion and enforces every protected action. |
|
||||
| Backend persistence | Go Modules | PostgreSQL Adapter -> RDS | Parameterized queries and transactions; fail closed in production. |
|
||||
| Task execution | Embedded Go WorkerLoop | RDS claim -> provider -> OSS -> RDS -> Webhook | Bounded concurrency, recoverable leases, one owner for external side effects. |
|
||||
| Asset lifecycle | Go Assets | OSS plus RDS metadata | Shared storage required before horizontal scaling. |
|
||||
| Schema rollout | Migration Job | RDS | Existing version/checksum/advisory-lock contract remains unchanged. |
|
||||
| Schema rollout | Manual operator or dedicated CI | RDS | Execute immutable versioned SQL plus grants outside long-lived workloads; no Web-image migration Job. |
|
||||
| Web health | ACK probe | Nginx `/healthz` | Static process/container health only; no database implication. |
|
||||
| Go readiness | ACK probe | Go `/api/ready` -> RDS | Database/schema/privilege-aware readiness. |
|
||||
|
||||
## State Ownership
|
||||
|
||||
@@ -35,11 +42,14 @@ The Go implementation and desired ACK routing for these flows are present in the
|
||||
- Alibaba Cloud RDS PostgreSQL via its internal endpoint and verified TLS CA.
|
||||
- Alibaba Cloud ACK resources under `deploy/ack/`.
|
||||
- Live production at `https://nianxxaigc.nianxx.cn`; public `/api/ready` has returned HTTP 200 with PostgreSQL configured, without proving the owning Service.
|
||||
- Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing.
|
||||
- The legacy internal Worker prefix is denied by Ingress; production uses the
|
||||
embedded Go WorkerLoop and ships no Node Worker manifest.
|
||||
|
||||
The accepted production topology uses the embedded Go WorkerLoop rather than the local-development Node Worker. The exact live workload set remains to be confirmed from the cluster.
|
||||
|
||||
The SSR identity bridge and ACK internal URL are merged but not yet deployed. The current live revision produces a production RSC error for authenticated `/create`; the repair rollout must deploy `498c2fa` and verify the flow with an authenticated smoke test.
|
||||
The accepted production topology uses the embedded Go WorkerLoop. The current
|
||||
live revision produces an RSC error for authenticated `/create`; the rollout
|
||||
must deploy `b14b4fc` under immutable image references and smoke login,
|
||||
authenticated routes, logout, roles, `/healthz`, `/api/health`, and
|
||||
`/api/ready`.
|
||||
|
||||
## Last Updated
|
||||
|
||||
|
||||
@@ -4,30 +4,33 @@
|
||||
|
||||
| Path | Responsibility | Owner Notes |
|
||||
|---|---|---|
|
||||
| `lib/server/database.ts` | Server-only PostgreSQL Pool, TLS, queries, transactions, readiness | Only deep database transport boundary for runtime stores. |
|
||||
| `lib/server/{data-store,account-store,billing-store}.ts` | Domain persistence with PostgreSQL/local implementations | Preserve exported interfaces for callers. |
|
||||
| `database/migrations/` | Immutable versioned PostgreSQL schema changes | Executed manually for the first deployment (0001 initial schema, 0002 generation lifecycle fencing); the Node runner and Job manifest are retained but not part of the deployment path. |
|
||||
| `scripts/postgres-client.mjs` | Validated database configuration for Node operations scripts | Shared by migration/bootstrap/import scripts. |
|
||||
| `deploy/ack/` | ACK deployment resources and secret/config templates | Desired production split topology; the `498c2fa` Web configuration is pending rollout, and the migration Job manifest is deprecated (manual SQL). |
|
||||
| `app/api/ready/route.ts` | Database/schema/privilege readiness endpoint | Separate from process-level liveness. |
|
||||
| `lib/server/auth/current-user.ts` | In revision `498c2fa`, resolves the current SSR user through internal Go `/api/auth/me` when `ZHINIAN_GO_INTERNAL_BASE_URL` is set; otherwise uses the local direct-store authorization path | Sends only enumerated `zhinian_session` chunks, validates the Go response and identity binding strictly, and fails closed on bridge errors. The fixed revision is not yet live. |
|
||||
| `backend/cmd/zhinian-api` | Go application entrypoint, configuration, HTTP server composition, readiness | Locally runnable and targeted by checked-in ACK routing; exact live request ownership remains unverified. |
|
||||
| `backend/internal/*` | ADR-003 deep modules and adapters, 18 packages: `identity`, `administration`, `assets`, `billing`, `usage`, `jobs`, `providers`, `webhook`, `httpapi`, `publicapi`, `application`, `orchestration`, `postgres`, `localstore`, `logging`, `settings`, `templates`, `prompt` | Merged; production is online, but the deployed revision and live routing do not yet reflect the `498c2fa` repair configuration. |
|
||||
| `app/**`, `components/**` | Statically exportable pages and browser UI | No Route Handlers, Middleware, server auth imports, or request-time page dependencies. |
|
||||
| `components/browser-auth.tsx` | Browser identity context and presentation guards | Consumes validated same-origin state; guards are UX only. |
|
||||
| `lib/client/browser-auth.ts` | Deep browser/Go auth Interface | Owns `GET /api/auth/me` parsing plus safe return-path validation. |
|
||||
| `next.config.ts`, `Dockerfile`, `deploy/nginx.conf` | Static export and production Web runtime | Build emits `out/`; unprivileged Nginx serves files and rejects Go-owned paths when reached directly. |
|
||||
| `database/migrations/` | Immutable versioned PostgreSQL schema changes | Executed manually/through dedicated operator CI; no migration Job reuses Web. |
|
||||
| `deploy/ack/` | Seven ACK manifests plus Secret template | Static Web + Go topology; Web has no runtime config/Secret and Go owns the session Secret. |
|
||||
| `backend/cmd/zhinian-api` | Go application entrypoint, configuration, HTTP server composition, health/readiness | Sole runtime API owner targeted by checked-in Ingress. |
|
||||
| `backend/internal/*` | ADR-003 deep modules and adapters, 18 packages: `identity`, `administration`, `assets`, `billing`, `usage`, `jobs`, `providers`, `webhook`, `httpapi`, `publicapi`, `application`, `orchestration`, `postgres`, `localstore`, `logging`, `settings`, `templates`, `prompt` | Implemented in `b14b4fc`; publication of immutable images and rollout of the static Web + Go revision remain pending. |
|
||||
| `contracts/**/*.json` | Language-neutral HTTP/Cookie/auth/jobs/billing/storage/webhook contract fixtures | Shared acceptance source for TypeScript and Go consumers. |
|
||||
|
||||
## Dependency Direction
|
||||
|
||||
- Routes and services depend on store interfaces; stores depend on the shared database adapter; the adapter does not depend on domain stores.
|
||||
- Worker depends on the internal Web HTTP API, not the database module.
|
||||
- Go modules depend on the PostgreSQL transport and storage/provider adapters; `httpapi`/`publicapi` depend on deep modules, never the reverse.
|
||||
- Static pages/components depend on `lib/client/browser-auth.ts` and relative
|
||||
same-origin HTTP paths; they never depend on `lib/server`.
|
||||
- Go `httpapi`/`publicapi` depend on deep business Modules; Modules depend on
|
||||
PostgreSQL/storage/provider Adapters, never on Web or HTTP presentation.
|
||||
- The embedded WorkerLoop uses Go application/Module seams and PostgreSQL
|
||||
claims; there is no Node-to-Web internal tick dependency.
|
||||
|
||||
## Approved Target Module Map
|
||||
|
||||
The target below is implemented in the repository. The first production deployment has occurred; the `498c2fa` repair rollout and confirmation of the live cluster shape remain pending:
|
||||
The target below is implemented in `b14b4fc`; image publication, ACK rollout,
|
||||
and confirmation of the live cluster shape remain pending:
|
||||
|
||||
| Target Module | Go package | Implementation notes |
|
||||
|---|---|---|
|
||||
| Next.js frontend | `lib/server/auth/current-user.ts` | In `498c2fa`, production SSR forwards only enumerated signed session Cookie chunks to Go `/api/auth/me`; the live revision does not yet contain this fix. Local full-stack mode uses direct stores when the internal Go URL is absent. |
|
||||
| Static frontend | `components/browser-auth.tsx`, `lib/client/browser-auth.ts` | Browser calls same-origin Go `/api/auth/me`; no SSR bridge, request Cookie parsing, internal Go URL, or server fallback. |
|
||||
| Go Identity | `internal/identity` | Login/logout/session/password/authorization; preserves the signed chunked Cookie and per-request account/organization/sessionVersion validation. |
|
||||
| Go Administration | `internal/administration` | Organizations, accounts, settings visibility, logs, administrative usage; enforces super-admin and organization-admin rules. |
|
||||
| Go Assets | `internal/assets` | Register/upload/list/get/delete/download; uses object-storage Adapter; preserves owner-scoped 404 and storage metadata. |
|
||||
@@ -45,7 +48,10 @@ Real internal seams are PostgreSQL transport, object storage, generation provide
|
||||
- Account authentication/password transactions and billing wallet idempotency.
|
||||
- ACK Secrets, RDS CA mounting, Ingress protection for internal Worker routes, and pool connection budgeting.
|
||||
- `backend/internal/{postgres,jobs,billing}`: claim and wallet correctness across Go replica scaling until WorkerLoop concurrency is deliberate.
|
||||
- Live request-path ownership and deployed workload revisions must be confirmed from ACK configuration or logs; do not infer them from the public endpoint alone.
|
||||
- Static Web image construction/container startup still needs CI smoke evidence.
|
||||
- Go `emptyDir` file state is lost on Pod replacement when OSS is absent.
|
||||
- Live request-path ownership and deployed workload revisions must be confirmed
|
||||
from ACK configuration or logs; do not infer them from a public endpoint.
|
||||
|
||||
## Last Updated
|
||||
|
||||
|
||||
@@ -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