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

Module Map

Source Layout

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	Executed manually for the first deployment (0001 initial schema, 0002 generation lifecycle fencing); the Node runner and Job manifest are retained but not part of the deployment path.
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	Desired production split topology; the 498c2fa Web configuration is pending rollout, and the migration Job manifest is deprecated (manual SQL).
app/api/ready/route.ts	Database/schema/privilege readiness endpoint	Separate from process-level liveness.
lib/server/auth/current-user.ts	In revision 498c2fa, resolves the current SSR user through internal Go /api/auth/me when ZHINIAN_GO_INTERNAL_BASE_URL is set; otherwise uses the local direct-store authorization path	Sends only enumerated zhinian_session chunks, validates the Go response and identity binding strictly, and fails closed on bridge errors. The fixed revision is not yet live.
backend/cmd/zhinian-api	Go application entrypoint, configuration, HTTP server composition, readiness	Locally runnable and targeted by checked-in ACK routing; exact live request ownership remains unverified.
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	Merged; production is online, but the deployed revision and live routing do not yet reflect the 498c2fa repair configuration.
contracts/**/*.json	Language-neutral HTTP/Cookie/auth/jobs/billing/storage/webhook contract fixtures	Shared acceptance source for TypeScript and Go consumers.

Dependency Direction

• 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.
• Go modules depend on the PostgreSQL transport and storage/provider adapters; httpapi/publicapi depend on deep modules, never the reverse.

Approved Target Module Map

The target below is implemented in the repository. The first production deployment has occurred; the 498c2fa repair rollout and confirmation of the live cluster shape remain pending:

Target Module	Go package	Implementation notes
Next.js frontend	lib/server/auth/current-user.ts	In 498c2fa, production SSR forwards only enumerated signed session Cookie chunks to Go /api/auth/me; the live revision does not yet contain this fix. Local full-stack mode uses direct stores when the internal Go URL is absent.
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.
• Live request-path ownership and deployed workload revisions must be confirmed from ACK configuration or logs; do not infer them from the public endpoint alone.

Last Updated

2026-08-16