docs: record first-deployment model and manual schema initialization
This commit is contained in:
zn-admin committed
1 parent
ff055c972d
commit
ca019abb14
14 files changed
+124
-62
No files matched your search
@@ -6,12 +6,12 @@
|
||||
|---|---|---|---|
|
||||
| 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. |
|
||||
| Schema rollout | ACK migration Job | RDS PostgreSQL | Versioned checksummed migrations under an advisory lock. |
|
||||
| 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 for these flows is merged into `main` under `backend/`; they become active only after the single-writer deployment cutover routes traffic to Go and drains the Node Worker:
|
||||
The Go implementation for these flows is merged into `main` under `backend/`; they become active on the first production deployment, which routes `/api`, `/uploads`, and `/generated-results` to Go from day one:
|
||||
|
||||
| Flow | Source | Destination | Required behavior |
|
||||
|---|---|---|---|
|
||||
@@ -34,7 +34,7 @@ The Go implementation for these flows is merged into `main` under `backend/`; th
|
||||
- Alibaba Cloud ACK resources under `deploy/ack/`.
|
||||
- Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing.
|
||||
|
||||
In the approved target, the internal Worker HTTP endpoint is removed only after the Node Worker is drained and the Go WorkerLoop is verified. It remains part of the deployed implementation until that cutover.
|
||||
The internal Worker HTTP endpoint remains part of the local-development implementation only; production never deploys the Node Worker and uses the embedded Go WorkerLoop from the first rollout.
|
||||
|
||||
## Last Updated
|
||||
|
||||
|
||||
@@ -6,9 +6,9 @@
|
||||
|---|---|---|
|
||||
| `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 | Applied by `scripts/migrate-postgres.mjs`; 0001 initial schema, 0002 generation lifecycle fencing. |
|
||||
| `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 | Migration Job precedes Web/Worker rollout; Go ownership changes wait for cutover. |
|
||||
| `deploy/ack/` | ACK deployment resources and secret/config templates | First production deployment uses the split topology; the migration Job manifest is deprecated (manual SQL). |
|
||||
| `app/api/ready/route.ts` | Database/schema/privilege readiness endpoint | Separate from process-level liveness. |
|
||||
| `backend/cmd/zhinian-api` | Go application entrypoint, configuration, HTTP server composition, readiness | Locally runnable; production routing still owned by Next.js. |
|
||||
| `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 into `main`; unrouted until cutover. |
|
||||
@@ -22,7 +22,7 @@
|
||||
|
||||
## Approved Target Module Map
|
||||
|
||||
The target below is implemented in `backend/internal/` and merged into `main`; deployment and traffic cutover remain pending:
|
||||
The target below is implemented in `backend/internal/` and merged into `main`; the first production deployment remains pending:
|
||||
|
||||
| Target Module | Go package | Implementation notes |
|
||||
|---|---|---|
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
## Current Architecture
|
||||
|
||||
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.
|
||||
There is no deployed production architecture yet. Local development keeps the Next.js full-stack Web workload plus the HTTP-polling Node Worker; production server state is stored directly in PostgreSQL through a shared server-only adapter, and development/tests can explicitly use local JSON.
|
||||
|
||||
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.
|
||||
The first production deployment will run the ADR-003 split topology directly: Next.js serves pages/static/SSR, and the merged Go backend under `backend/` owns `/api`, `/uploads`, and `/generated-results`. There is no legacy production instance, so there is no cutover and no Node Worker in production — the Go process embeds the WorkerLoop from day one. The deployment artifacts for the Go workload are still to be built.
|
||||
|
||||
## Approved Target Architecture
|
||||
|
||||
@@ -12,20 +12,20 @@ The accepted target in ADR-003 is a same-origin Next.js frontend plus Go modular
|
||||
|
||||
| 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. |
|
||||
| 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. |
|
||||
| Go backend | Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness | Owns relational access and embeds the WorkerLoop. | Implemented in `backend/` and merged; first production deployment pending. |
|
||||
| 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. |
|
||||
| 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`). The Go implementation is complete and merged; deployment and traffic cutover are not.
|
||||
Ingress will route page/static paths to Next.js and `/api`, `/uploads`, and `/generated-results` to Go from the first deployment. The initial target is two long-lived Pods (`Next x1 + Go x1`).
|
||||
|
||||
## 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` until cutover. |
|
||||
| Worker | Periodically invokes the internal Worker tick endpoint | No direct database connection or RDS Secret. |
|
||||
| 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`. |
|
||||
| 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. |
|
||||
@@ -39,12 +39,13 @@ 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.
|
||||
- The Go implementation must be validated against non-production RDS/OSS/provider/Webhook dependencies before the first production rollout; Next Route Handlers stay in the repository for local development.
|
||||
|
||||
## Related Decisions
|
||||
|
||||
- Current implementation: `RDS-001`, `RDS-002`, and `ACK-001`.
|
||||
- Accepted target: `ADR-003`; it supersedes ACK-001 only after verified implementation and cutover.
|
||||
- Current implementation: `RDS-001` and `RDS-002` (schema execution now manual SQL per `DEP-001`).
|
||||
- Accepted target: `ADR-003`; it supersedes ACK-001 once the first production deployment runs the Go stack.
|
||||
- First-deployment model: `DEP-001`.
|
||||
|
||||
## Last Updated
|
||||
|
||||
|
||||
Reference in new issue
Block a user