NianAIGC/.project-docs/20-architecture/system-overview.md

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.

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

• RDS-001, RDS-002, ACK-001 in the decision index.

Last Updated

2026-08-12