Bootstrap copied BFF and local accounts with public Sendico contracts (#34)

backend/README.md

@@ -1,38 +1,46 @@
 # SXCHNGE BFF
 
-Independent Go module with an operational HTTP shell and selected, adapted
-Sendico foundations. Sendico remains an external financial-services provider;
-there are no Sendico module imports, shared databases or sibling-path dependencies.
-See the [architecture and service plan](../docs/architecture/bff.md) and
-[reuse provenance](PROVENANCE.md).
+A locally owned copy of Sendico's reusable BFF runtime, authentication/session
+stack and account service. See [provenance](PROVENANCE.md) and the
+[architecture and public API plan](../docs/architecture/bff.md).
 
-## Run and validate
+SXCHNGE owns its customers and authentication. SXCHNGE itself is one organization
+in Sendico. Provider integration uses only Sendico's public HTTP API; the pinned
+[OpenAPI snapshot](contracts/sendico/api.yaml) is isolated from local models.
 
-Requires Go 1.26 or later. From the repository root:
+## Run locally
+
+Requires Go 1.27 and an SXCHNGE-owned MongoDB replica set for transactions.
+Copy `config.example.yml` to an untracked `config.yml`. Set:
+
+- `SXCHNGE_MONGO_URI`: URI for the local SXCHNGE database.
+- `SXCHNGE_JWT_SECRET`: private random signing key, at least 32 bytes for HS256.
+- `SXCHNGE_DOMAIN`: local API hostname (for example `localhost:8082`).
+- `SXCHNGE_API_PROTOCOL`: `http` locally, `https` in deployment.
+- `SXCHNGE_API_ENDPOINT`: `/api/v1`.
+
+Seed the local policy descriptions before first startup (requires `mongosh`):
 
 ```sh
-make test-backend
-make lint-backend
-make run-backend
+mongosh "$SXCHNGE_MONGO_URI" --file backend/scripts/seed-policies.js
 ```
 
-The default address is `127.0.0.1:8082`; override with `SXCHNGE_HTTP_ADDR`.
-`GET /healthz` reports process health. `GET /readyz` deliberately returns **503**
-with `not_configured`: persistence, authentication and Sendico are not connected.
-No product routes return dummy success. The process handles SIGINT/SIGTERM with
-bounded graceful shutdown. Production transport must terminate HTTPS.
+The seed is repeatable and creates only the three local built-in policy
+descriptions required by the copied runtime. It grants no role permissions.
+Run `make run-backend` from the repository root. The copied CLI accepts
+`-config.file`, `-version` and `-debug`. Configure exact browser origins in YAML;
+secure refresh cookies require HTTPS for browser session testing.
 
-## Present components
+The runtime mounts `/api/v1/health` and the copied account login, API login,
+refresh, rotation and logout handlers. Customer/client records must exist in the
+local database. The account service is initialized locally; signup/profile and
+verification-delivery/completion routes are the next wiring work. This is a
+bootstrap, not a finished authentication deployment. No Sendico calls are made.
 
-- `cmd/bff`, `internal/httpapi`: HTTP process, timeouts and operational endpoints.
-- `internal/browser`: explicit HTTPS origin/CSRF policy and Secure HttpOnly
-  host-only session cookie. Apply this policy to every future browser mutation;
-  it is not yet connected to product routes because those do not exist.
-- `internal/credential`: random opaque credentials and storage digests. Never use
-  this helper for passwords or short OTP codes.
-- `internal/evidence`: confined server-generated object keys; not a substitute
-  for ownership, upload validation or private storage controls.
+## Validate
 
-Only the standard library is required. Larger adapted flows, persistence,
-provider DTOs/mappers, email and live integration follow the plan in separate
-contributions. Source-derived components evolve independently inside this repo.
+Run `make test` and `make lint-backend`. Backend tests include real MongoDB
+integration tests through Testcontainers, so Docker must be running.
+`make test-backend` runs the backend suite with the race detector.
+Architecture checks reject private Sendico imports/transports and ad hoc error
+constructors. The frontend still uses dummy services; no Flutter source changed.