docs: integrate RDS and ACK architecture memory

.project-docs/20-architecture/data-flow.md

@@ -4,15 +4,23 @@
 
 | Flow | Source | Destination | Notes |
 |---|---|---|---|
+| Web persistence | Routes/services/stores | PostgreSQL adapter -> RDS | Parameterized SQL; related statements share one Pool client transaction. |
+| Worker processing | Worker process | Internal Web Service `/api/internal/worker/tick` | Authenticated by internal token; Worker has no RDS credentials. |
+| Schema rollout | ACK migration Job | RDS PostgreSQL | Versioned checksummed migrations under an advisory lock. |
+| Readiness | ACK probe | Web `/api/ready` -> RDS | Verifies connection, 11 runtime tables, required privileges, and 2 functions. |
 
 ## State Ownership
 
-- {state owner or persistence rule}
+- Production relational state belongs to RDS PostgreSQL when `ZHINIAN_DATA_BACKEND=postgres`.
+- Local JSON under the runtime directory is an explicit development/test backend, not a production fallback.
+- Uploads/generated files remain runtime/object-storage state and are not made shared by the PostgreSQL migration.
 
 ## External Interfaces
 
-- {API, file, service, or user-facing boundary}
+- Alibaba Cloud RDS PostgreSQL via its internal endpoint and verified TLS CA.
+- Alibaba Cloud ACK resources under `deploy/ack/`.
+- Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing.
 
 ## Last Updated
 
-{YYYY-MM-DD}
+2026-08-12

.project-docs/20-architecture/module-map.md

@@ -4,15 +4,24 @@
 
 | Path | Responsibility | Owner Notes |
 |---|---|---|
+| `lib/server/database.ts` | Server-only PostgreSQL Pool, TLS, queries, transactions, readiness | Only deep database transport boundary for runtime stores. |
+| `lib/server/{data-store,account-store,billing-store}.ts` | Domain persistence with PostgreSQL/local implementations | Preserve exported interfaces for callers. |
+| `database/migrations/` | Immutable versioned PostgreSQL schema changes | Applied by `scripts/migrate-postgres.mjs`. |
+| `scripts/postgres-client.mjs` | Validated database configuration for Node operations scripts | Shared by migration/bootstrap/import scripts. |
+| `deploy/ack/` | ACK deployment resources and secret/config templates | Migration Job precedes Web/Worker rollout. |
+| `app/api/ready/route.ts` | Database/schema/privilege readiness endpoint | Separate from process-level liveness. |
 
 ## Dependency Direction
 
-- {dependency direction rule}
+- Routes and services depend on store interfaces; stores depend on the shared database adapter; the adapter does not depend on domain stores.
+- Worker depends on the internal Web HTTP API, not the database module.
 
 ## Risky Or Sensitive Areas
 
-- {module or path that needs extra care}
+- `database/migrations/` and the two concurrency-sensitive PostgreSQL functions.
+- Account authentication/password transactions and billing wallet idempotency.
+- ACK Secrets, RDS CA mounting, Ingress protection for internal Worker routes, and pool connection budgeting.
 
 ## Last Updated
 
-{YYYY-MM-DD}
+2026-08-12

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

@@ -2,21 +2,30 @@
 
 ## Current Architecture
 
-{short description of the current system shape}
+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
 
-- {boundary that future work should respect}
+- 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
 
-- {ADR reference}
+- `RDS-001`, `RDS-002`, `ACK-001` in the decision index.
 
 ## Last Updated
 
-{YYYY-MM-DD}
+2026-08-12