# Go backend foundation

This directory contains the first implementation slice of ADR-003. It is a
runnable compatibility foundation, but it is **not** the current production API
owner: Next.js, the Node Worker, Docker Compose, and the ACK manifests remain
unchanged until later route-by-route cutover work passes the shared contracts.

Implemented Modules:

- `identity`: legacy `zhinian_session` HMAC/chunking, database-refreshed
  authorization, and the password-login lifecycle.
- `postgres`: fail-closed configuration, verified-CA TLS, readiness, atomic
  password lockout transactions, and calls to the existing claim and wallet
  PostgreSQL functions.
- `httpapi`: process health, database readiness, current-session, password
  login, and logout handlers.
- `application`: composition and the `cmd/zhinian-api` process entry point.

From the repository root:

```bash
npm run go:fmt
npm run go:test
npm run go:vet
npm run go:build
```

The runner defaults to `CGO_ENABLED=0` for reproducible cross-platform builds.
To exercise the local foundation manually without changing the existing Next
server, use a different port:

```bash
ZHINIAN_DATA_BACKEND=local GO_BACKEND_PORT=8080 ./backend/zhinian-api
```

`/api/health`, `/api/ready`, `/api/auth/me`, `/api/auth/password`, and
`/api/auth/logout` are implemented in the separately runnable Go process. No
Ingress, Docker, ACK, Secret, or Worker ownership has moved to Go yet, so
Next.js remains the production owner of every route.

The authentication handlers reuse the shared Cookie contracts and PostgreSQL
Adapters. Self-service/admin password mutation and production route ownership
remain with Next.js until later path-level cutover.