61 lines
3.9 KiB
Markdown
61 lines
3.9 KiB
Markdown
# 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
|