# 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