# Data Flow

## Development Flows

`next dev` serves the page development loop; runtime API behavior still belongs
to a separately running Go backend or an equivalent same-origin development
proxy. Legacy TypeScript server adapters remain unreferenced cleanup candidates
and are not a supported production path.

| Flow | Source | Destination | Notes |
|---|---|---|---|
| Browser UI development | Browser | Next dev page server | Pages/components only; no Next API or Middleware. |
| Runtime API development | Browser/tooling | Go HTTP server | Same contracts as production; Go localstore is explicit non-production mode. |
| Schema rollout | Manual SQL execution by the deployment operator | RDS PostgreSQL | Versioned checksummed files under `database/migrations/`; 0001 then 0002, then application-role grants. |

## Approved Target Flows

The static implementation and desired ACK routing are present in `b14b4fc`;
`ed97814` adds the plaintext PostgreSQL transport correction.
Production is already online, but the static revision and exact live Service
ownership have not been confirmed from cluster configuration or logs:

| Flow | Source | Destination | Required behavior |
|---|---|---|---|
| Browser UI | Browser | Same-origin Ingress -> Nginx static Web | Preserve current page URLs; Nginx performs no application logic. |
| Browser identity | Browser auth Module | Same-origin Ingress -> Go `GET /api/auth/me` | Browser automatically sends HttpOnly Cookie; validate anonymous/authenticated response shapes, keep no token in JavaScript, and use client guards only for UX. |
| Browser business/file requests | Browser components | Same-origin Ingress -> Go `/api`, `/uploads`, `/generated-results` | Go revalidates session/account/organization/sessionVersion and enforces every protected action. |
| Backend persistence | Go Modules | PostgreSQL Adapter -> internal RDS endpoint | Parameterized queries and transactions; fail closed in production; code-enforced plaintext (`sslmode=disable`) within VPC/security-group/allowlist isolation. |
| 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 | Manual operator or dedicated CI | RDS | Execute immutable versioned SQL plus grants outside long-lived workloads; no Web-image migration Job. |
| Web health | ACK probe | Nginx `/healthz` | Static process/container health only; no database implication. |
| Go readiness | ACK probe | Go `/api/ready` -> RDS | Database/schema/privilege-aware readiness. |

## 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 using code-enforced
  plaintext; VPC, security-group, and RDS allowlist controls are the transport
  isolation boundary.
- Alibaba Cloud ACK resources under `deploy/ack/`.
- Live production at `https://nianxxaigc.nianxx.cn`; public `/api/ready` has returned HTTP 200 with PostgreSQL configured, without proving the owning Service.
- The legacy internal Worker prefix is denied by Ingress; production uses the
  embedded Go WorkerLoop and ships no Node Worker manifest.

The accepted production topology uses the embedded Go WorkerLoop. The current
live revision produces an RSC error for authenticated `/create`; the rollout
must deploy `ed97814` under immutable image references and smoke PostgreSQL
bootstrap/readiness, login,
authenticated routes, logout, roles, `/healthz`, `/api/health`, and
`/api/ready`.

## Last Updated

2026-08-16