2.4 KiB
2.4 KiB
Data Flow
Primary Flows
| 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. |
Approved Target Flows
These flows become active only after ADR-003 is implemented:
| Flow | Source | Destination | Required behavior |
|---|---|---|---|
| Browser UI | Browser | Same-origin Ingress -> Next.js or Go by path | Preserve current URLs; avoid cross-origin Cookie/CORS changes. |
| SSR identity/data | Next.js | Internal Go HTTP Interface | Forward Cookie and origin; Go remains the sole authorization authority. |
| Backend persistence | Go Modules | PostgreSQL Adapter -> RDS | Parameterized queries and transactions; fail closed in production. |
| Task execution | Embedded Go WorkerLoop | RDS claim -> provider -> OSS -> RDS -> Webhook | Bounded concurrency, recoverable leases, one owner for external side effects. |
| Asset lifecycle | Go Assets | OSS plus RDS metadata | Shared storage required before horizontal scaling. |
| Schema rollout | Migration Job | RDS | Existing version/checksum/advisory-lock contract remains unchanged. |
State Ownership
- 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
- 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.
In the approved target, the internal Worker HTTP endpoint is removed only after the Node Worker is drained and the Go WorkerLoop is verified. It remains part of the current implementation until that cutover.
Last Updated
2026-08-12