3.1 KiB
System Overview
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.
This remains the implemented and deployable architecture. No Go backend code or Go deployment resources have been integrated.
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. |
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.
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. |
| 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. |
| 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. |
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
pgor 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.
Related Decisions
- Current implementation:
RDS-001,RDS-002, andACK-001. - Accepted target:
ADR-003; it supersedes ACK-001 only after verified implementation and cutover.
Last Updated
2026-08-12