# 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`; `ed97814` enforces plaintext PostgreSQL. Publication of immutable images and live rollout 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, private-network enforcement for unencrypted RDS traffic,
  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