# 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 | Applied by `scripts/migrate-postgres.mjs`. |
| `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 | Migration Job precedes Web/Worker rollout. |
| `app/api/ready/route.ts` | Database/schema/privilege readiness endpoint | Separate from process-level liveness. |

## 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.

## Approved Target Module Map

The target below is a design contract, not current source layout:

| Target Module | Interface | Implementation notes |
|---|---|---|
| Next.js frontend | Pages, SSR, and same-origin browser calls | Forwards Cookie/request context to Go; no direct persistence or domain ownership. |
| Go Identity | Login/logout/session/password/authorization | Preserves the current signed chunked Cookie and per-request account/organization/sessionVersion validation. |
| Go Administration | Organizations, accounts, settings visibility, logs, administrative usage | Enforces current super-admin and organization-admin rules. |
| Go Assets | Register/upload/list/get/delete/download | Uses object-storage Adapter; preserves owner-scoped 404 and storage metadata. |
| Go Jobs | Submit/query/cancel/retry/claim/execute/terminal transitions/Webhooks | Uses the PostgreSQL claim function and hides provider/retry/refund state. |
| Go Billing | Quote/wallet/ledger/price/charge/refund/settlement | Uses the PostgreSQL wallet function and integer-fen arithmetic. |
| Go Usage | Platform/public attribution and usage records | Retains organization/account context and job uniqueness. |

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.

## Last Updated

2026-08-12