Transports architecture

Chronacta exposes a gRPC API (api/proto/stream/v1/stream.proto) as the authoritative network contract. Export/import, NATS, the Admin UI BFF, REST, and WebSocket are implemented as adapters around the gRPC contract.

Primary transport: gRPC

• All stream, admin, schema, subscription, projection, auth, cluster, and integration operations remain gRPC-authoritative on the data plane port (default :2113).
• The Go SDK (pkg/client) is the reference client; it mirrors the protobuf contract without separate storage semantics.
• Compatibility guarantees: compatibility.md and compatibility-policy.md.

Browser / operator UI: BFF, not grpc-web

• Admin UI uses a Go BFF (pkg/adminui/) with server-rendered HTML and htmx — see admin-ui.md.
• Live stream tail in Admin UI uses SSE from the BFF (GET /admin/streams/{id}/tail).
• No grpc-web or browser-exposed bearer tokens in the default deployment.

REST and WebSocket (thin adapters)

Transport	Status	Package	Surface
REST v2	Implemented	pkg/restgateway	OpenAPI map + GET /v1/openapi.json; health, append/read, stream info, admin subset, login
WebSocket v2	Implemented	pkg/wsgateway	GET /v1/ws/streams/{id}, GET /v1/ws/all; per-connection send buffer (backpressure)
SSE (BFF)	Implemented	pkg/adminui	Admin session live tail

gRPC → HTTP map: pkg/openapi/grpc-http-map.yaml is the source of truth for REST paths and OpenAPI generation (cmd/openapi-gen → api/openapi/openapi.json). Validation: make openapi-validate (spec lint + route parity with pkg/restgateway).

Enable via config / env (CHRONACTA_GATEWAY_REST_*, CHRONACTA_GATEWAY_WS_* — see internal/config).

Rules for alternate transports:

1. Map to the same domain operations as gRPC (no divergent semantics).
2. Reuse auth/RBAC rules (bearer token same as gRPC).
3. Ship with integration smoke tests comparable to pkg/client.

SDK stability

• pkg/client tracks server releases; breaking changes require a minor/major bump per compatibility policy.
• CI smoke check: make sdk-smoke runs pkg/client integration tests plus TypeScript/Python REST client smoke.
• REST v2 SDKs: sdk/typescript (RestClient), sdk/python (chronacta.RestClient) — hand-maintained against the OpenAPI map; proto codegen stubs under sdk/*/gen.

Not provided

• Full OpenAPI of every admin RPC (REST v2 is an explicit mapped subset).
• GraphQL or message-queue-native APIs beyond existing NATS bridge.
• JavaScript projection runtime (permanently excluded)

Production notes

• Single wire contract remains gRPC; REST/WS cannot drift business rules.
• Browser operators get SSE without exposing grpc-web.
• REST/WS cover a subset; advanced ops stay on gRPC/CLI.
• Extra listeners to secure and monitor in production.