docs: record first-deployment model and manual schema initialization
This commit is contained in:
1 parent
ff055c972d
commit
ca019abb14
14 files changed
+124
-62
No files matched your search
@@ -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