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

Module Map

Source Layout

Path	Responsibility	Owner Notes
app/**, components/**	Statically exportable pages and browser UI	No Route Handlers, Middleware, server auth imports, or request-time page dependencies.
components/browser-auth.tsx	Browser identity context and presentation guards	Consumes validated same-origin state; guards are UX only.
lib/client/browser-auth.ts	Deep browser/Go auth Interface	Owns GET /api/auth/me parsing plus safe return-path validation.
next.config.ts, Dockerfile, deploy/nginx.conf	Static export and production Web runtime	Build emits out/; unprivileged Nginx serves files and rejects Go-owned paths when reached directly.
database/migrations/	Immutable versioned PostgreSQL schema changes	Executed manually/through dedicated operator CI; no migration Job reuses Web.
deploy/ack/	Seven ACK manifests plus Secret template	Static Web + Go topology; Web has no runtime config/Secret and Go owns the session Secret.
backend/cmd/zhinian-api	Go application entrypoint, configuration, HTTP server composition, health/readiness	Sole runtime API owner targeted by checked-in Ingress.
backend/internal/*	ADR-003 deep modules and adapters, 18 packages: identity, administration, assets, billing, usage, jobs, providers, webhook, httpapi, publicapi, application, orchestration, postgres, localstore, logging, settings, templates, prompt	Implemented in b14b4fc; publication of immutable images and rollout of the static Web + Go revision remain pending.
contracts/**/*.json	Language-neutral HTTP/Cookie/auth/jobs/billing/storage/webhook contract fixtures	Shared acceptance source for TypeScript and Go consumers.

Dependency Direction

• Static pages/components depend on lib/client/browser-auth.ts and relative same-origin HTTP paths; they never depend on lib/server.
• Go httpapi/publicapi depend on deep business Modules; Modules depend on PostgreSQL/storage/provider Adapters, never on Web or HTTP presentation.
• The embedded WorkerLoop uses Go application/Module seams and PostgreSQL claims; there is no Node-to-Web internal tick dependency.

Approved Target Module Map

The target below is implemented in b14b4fc; image publication, ACK rollout, and confirmation of the live cluster shape remain pending:

Target Module	Go package	Implementation notes
Static frontend	components/browser-auth.tsx, lib/client/browser-auth.ts	Browser calls same-origin Go /api/auth/me; no SSR bridge, request Cookie parsing, internal Go URL, or server fallback.
Go Identity	internal/identity	Login/logout/session/password/authorization; preserves the signed chunked Cookie and per-request account/organization/sessionVersion validation.
Go Administration	internal/administration	Organizations, accounts, settings visibility, logs, administrative usage; enforces super-admin and organization-admin rules.
Go Assets	internal/assets	Register/upload/list/get/delete/download; uses object-storage Adapter; preserves owner-scoped 404 and storage metadata.
Go Jobs	internal/jobs	Submit/query/cancel/retry/claim/execute/terminal transitions/Webhooks; uses the PostgreSQL claim function and hides provider/retry/refund state.
Go Billing	internal/billing	Quote/wallet/ledger/price/charge/refund/settlement; uses the PostgreSQL wallet function and integer-fen arithmetic.
Go Usage	internal/usage	Platform/public attribution and usage records; retains organization/account context and job uniqueness.
Compatibility HTTP	internal/httpapi, internal/publicapi	Preserve current browser and public /api/v1 paths, JSON shapes, status codes, and auth boundaries.
Infrastructure seams	internal/postgres, internal/localstore, internal/providers, internal/webhook, internal/orchestration, internal/application, internal/logging	PostgreSQL transport, storage adapters, provider adapters, webhook delivery, embedded WorkerLoop orchestration, application composition, streamed event logging.

Real internal seams are PostgreSQL transport, object storage, generation providers, and deterministic test dependencies. Avoid one shallow repository Interface per table.

Risky Or Sensitive Areas

• 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.
• backend/internal/{postgres,jobs,billing}: claim and wallet correctness across Go replica scaling until WorkerLoop concurrency is deliberate.
• Static Web image construction/container startup still needs CI smoke evidence.
• Go emptyDir file state is lost on Pod replacement when OSS is absent.
• Live request-path ownership and deployed workload revisions must be confirmed from ACK configuration or logs; do not infer them from a public endpoint.

Last Updated

2026-08-16