4.6 KiB
4.6 KiB
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 | First production deployment uses the split topology; the migration Job manifest is deprecated (manual SQL). |
app/api/ready/route.ts |
Database/schema/privilege readiness endpoint | Separate from process-level liveness. |
backend/cmd/zhinian-api |
Go application entrypoint, configuration, HTTP server composition, readiness | Locally runnable; production routing still owned by Next.js. |
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 into main; unrouted until cutover. |
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/publicapidepend on deep modules, never the reverse.
Approved Target Module Map
The target below is implemented in backend/internal/ and merged into main; the first production deployment remains pending:
| Target Module | Go package | Implementation notes |
|---|---|---|
| Next.js frontend | (Next.js, unchanged) | Forwards Cookie/request context to Go; no direct persistence or domain ownership after cutover. |
| 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.
Last Updated
2026-08-14