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

React to SDUI BFF with tRPC

The owner accepted ADR 0013 on September 30, 2026. This is the selected transport design. The first draft slice is implemented and locally verified; the remaining experience calls and full certification still need work.

flowchart LR

    REACT[React and Vite SDUI renderer] -->|tRPC queries and POST mutations over HTTPS| GATE[Same-origin HTTPS gateway]

    CONTRACT[Type-only inferred router contract] -.-> REACT

    GATE --> FAST[Fastify tRPC adapter]

    FAST --> AUTH[Opaque session and current context]

    AUTH --> PROC[Authorized experience procedures]

    TB[Reviewed TypeBox input and output parsers] --> PROC

    PROC --> SCREEN[SDUI model assembler]

    CMS[Contentful bilingual definitions] --> REL[Pinned allowlisted release]

    REL --> SCREEN

    WF[Camunda task and logical screen] --> SCREEN

    PROC --> OWN[Existing business-owner interfaces]

    OWN --> DB[(Records, revisions and outbox)]

    OWN --> ADAPT[Private workflow and system adapters]

    ADAPT -->|Supported gRPC or HTTPS operations| WF

Boundary choices

Connection	Selected contract	Qualification requirement
React experience calls	tRPC on Fastify over same-origin HTTPS; initial path `/api/trpc/v1`	Typed client and router builds, explicit input/output validators, no backend runtime code in browser output
Authentication and current context	Existing Keycloak-backed opaque session; request-scoped identity and live owner permissions	Expiry/logout, context switches and cross-owner non-disclosure remain enforced
SDUI model	Pinned bilingual CMS definition, permitted values, revision and allowed actions selected by workflow state	Renderer compatibility, immutable release binding and authoritative CMS answer validation
Mutations	POST, exact Origin, session-bound CSRF and owner revisions; explicit retry identity for durable commands	Reject GET mutation and batching; no automatic effectful retries; preserve uncertain outcomes
Structure and responses	TypeBox through a tRPC-compatible parser; strict input and authorized output validation	Never assume the wildcard Fastify route validates a procedure; do not transform answers or disclose raw errors
Dedicated HTTPS protocols	OIDC redirects, session bootstrap/logout, binary documents, health probes	Existing security and private-file scanning checks still apply
Legacy/system REST APIs	Existing versioned paths and their OpenAPI contracts	Keep during migration and for appropriate non-tRPC consumers
BFF to suitable private services	ADR 0012 gRPC adapters or supported HTTPS APIs	Engine compatibility, deadlines, service authentication and recovery proof

First tracer bullet

Migrate the existing generic application draft's list, read, create and revision-checked save calls. Procedures should invoke listDrafts, getDraft, createDraft and saveDraft directly behind the existing personal/customer context resolver. Preserve their owner checks and release compiler. The initial read returns the existing pinned form definition and answers; it does not manufacture a product form or new Camunda workflow. Case submission and remaining experience calls follow in bounded slices.

Use a non-batching typed client with same-origin credentials and an operation-specific CSRF header on mutations. Create or refresh the client when the session's CSRF token changes. Cancel or ignore stale responses after logout, context switching or unmount. Do not add a client cache that can mix identities or contexts. If caching is added later, its keys and invalidation require explicit tests.

The tRPC error formatter must expose safe Atlas codes such as unauthenticated, not_found, csrf_denied, stale_draft and release_unavailable where the current contract permits them. Preserve bilingual field-error codes and limits without echoing input or exception details. Test error mapping independently of presentation; returning an exception's message directly is insufficient.

Gates and remaining work

Pin compatible packages and establish a browser-safe router type entry point. Test reviewed TypeBox parsers and Fastify HTTP guards at the public endpoint.
Migrate one draft behavior at a time with recorded red/green tests. Retain the legacy paths and owner implementations.
Check both package builds and the production browser bundle. Qualify the bilingual draft journey through the existing local HTTPS gateway and real session/database/release services.
Migrate case operations, task actions and other experience features with their existing idempotency and recovery tests. New BFF features use the selected tRPC contract.
Retire a compatibility path only after its consumers and acceptance checks have migrated. Keep REST for the documented protocol, file and integration cases.

The first draft slice evidence records local list/read/create/save implementation and its bounded qualification. Other experience calls still need migration; full-stack certification and private gRPC qualification remain separate. The Journey amendment record retains the original decision.