49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
# 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 `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.
|
|
|
|
## 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.
|
|
|
|
## Last Updated
|
|
|
|
2026-08-12
|