Plan independent BFF and adapt selected Sendico foundations (#34)

backend/README.md

@@ -1,14 +1,38 @@
-# SXCHNGE backend
+# SXCHNGE BFF
 
-Reserved for a small backend for frontend (BFF) using a supported Sendico API. No service, runtime, or dependencies have been initialized yet.
+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).
 
-Planned responsibilities:
+## Run and validate
 
-- Consumer authentication and sessions, with a stable mapping to organization-scoped Sendico customer references.
-- Consumer-authorized access to onboarding, quotes, orders, and transaction history.
-- Product-specific orchestration and presentation of Sendico KYC, eligibility, and remaining-limit responses.
-- Server-side integration credentials and request correlation with Sendico.
+Requires Go 1.26 or later. From the repository root:
 
-Sendico owns payment execution, authoritative KYC evidence and verification records, policy evaluation, and limit reservations/enforcement. Do not copy its existing BFF or import local Sendico implementation modules.
+```sh
+make test-backend
+make lint-backend
+make run-backend
+```
 
-Before implementation, agree on customer registration and identity mapping, customer KYC operations, eligibility/limits reads, customer-scoped payment access, and retry/idempotency behavior. Validate consumer isolation even when multiple customers use the same sxchnge organization and integration principal.
+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.
+
+## Present components
+
+- `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.
+
+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.