Frozen document. Dates and status refer to its original source. Private resources and unreviewed images are unavailable.

status: accepted

Use gRPC for suitable private service adapters

Later browser amendment, September 30, 2026: ADR 0013 selects tRPC over HTTPS for the React-to-SDUI BFF connection. It supersedes the browser REST choice in the paragraph below. This ADR still governs suitable private gRPC adapters; no browser gRPC-Web is added.

On September 30, 2026, the owner confirmed HTTPS/REST between the browser and BFF, with gRPC for suitable internal adapters. Retain versioned JSON/OpenAPI Experience APIs, opaque Keycloak-backed sessions and CSRF from ADRs 0008 and 0009. Adopt gRPC behind private adapter interfaces for integrations with a supported protobuf API. Fastify owns the HTTP boundary; a gRPC client owns its separate HTTP/2 channel. Enabling Fastify HTTP/2 alone is not a gRPC implementation.

Camunda's supported Zeebe command/job API is the first integration candidate. Keep REST for Orchestration Cluster searches and Camunda user-task operations where required. The existing apps/bff/src/camunda.ts uses REST only. Switching a supported operation to gRPC requires an explicit, tested adapter migration; this ADR does not claim that migration is complete. Camunda's API catalog distinguishes its REST Orchestration Cluster API and Zeebe gRPC API.

Contracts and delivery

Use vendor-version-compatible protobuf definitions or a compatible official SDK. For Atlas-owned remote services, version .proto contracts and generated TypeScript mappings. TypeBox validates JSON boundaries; protobuf supplies RPC wire types. Both map into the same domain interfaces and owner checks. Preserve 64-bit identifiers without JavaScript number rounding, explicit field presence and established JSON values. Do not infer authorization or business validity from successful protobuf decoding.

Every RPC needs a bounded deadline, bounded payload/concurrency, redacted correlation metadata and explicit error mapping. Use service authentication appropriate to the destination; keep credentials server-side. Across hosts use certificate-verified TLS and destination-supported workload authentication. Local plaintext is permitted only on the isolated Compose network, documented and tested; no public or browser gRPC ingress is added. Do not forward browser cookies or arbitrary identity headers as service authority.

ADR 0005 still owns durable acceptance, outbox delivery and recovery. A timeout or lost response after dispatch may leave an effect uncertain. Reconcile the original operation before another effect is attempted. Do not automatically fall back from gRPC to REST after an ambiguous write. Retry settings must be explicit and safe for the operation, including any SDK defaults; neither retries nor protobuf provide exactly-once business effects.

Trade-off and rollout

REST-only adapters are simpler and remain appropriate for Contentful, Keycloak and services without gRPC contracts. gRPC adds typed service contracts and streaming where needed, but also protobuf tooling, HTTP/2 lifecycle and fault-handling work. Keep same-process business-owner calls as module interfaces; do not split the modular BFF into network services merely to use gRPC. No gRPC-Web, new broker or second workflow engine is selected.

Start with one supported Camunda operation through the existing lifecycle interface and qualify it against the real engine and public HTTPS journey before expanding. Retain a configured rollback to the previous adapter after pending operations have been assessed. See the boundary design and rollout, Node gRPC implementation, deadline guidance and retry behavior.