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

status: accepted

Render Contentful forms from pinned bilingual releases

Atlas uses structured Contentful entries and a custom React component registry for forms. A release operation compiles and validates the published content graph, then retains an immutable bundle compatible with the renderer, workflow, submission contract, and business-rule version. A draft or case pins that bundle, including forms required by later workflow tasks.

This is Atlas's server-driven UI pattern. Contentful owns the authored screen and form definitions: sections, supported components, layout order, labels, help text, options, conditional display, and declarative field-validation settings. The BFF compiles these definitions and returns an authorized screen model with data and actions derived from the user's journey and current Camunda task. React renders the model through an allowlisted component registry. A new supported form field or content change should not require a React page change.

Transport clarification, 2026-09-30: ADR 0013 selects tRPC between React and the SDUI BFF. The transport does not change pinned Contentful field definitions, validation or Camunda screen selection.

Validation clarification, 2026-09-30: ADR 0011 selects TypeBox for the supported definition vocabulary and API envelopes. Form fields and their declarative constraints remain authored in Contentful and pinned by release. The BFF must not compile arbitrary CMS-supplied schemas or create a competing code-owned product form.

The owner accepted this form architecture and confirmed US English (en-US) and US Spanish (es-US) for the initial demo. Each release contains both languages. Language switching changes presentation while preserving the release, answers, business identifiers, and workflow state.

Rationale

This supports structured content authoring and the Atlas component system while keeping runtime business rules and authorization with backend owners. A reproducible bundle protects applications in progress from later edits to forms or referenced content. Native Camunda Forms/form-js and freeform JSON-only editing were considered as alternatives; Atlas retains Contentful's structured model and its own React renderer.

Camunda determines process position, active task, assignment, and permitted task transitions. It identifies a logical screen or form reference; it does not store presentation content or executable validation scripts. Before a process starts, the selected journey and draft state provide that context. The BFF resolves the reference against the case's pinned release, applies actor and record permissions, and returns only permitted fields, values, and actions.

Consequences

Contentful publication alone neither activates a form release nor deploys a workflow. Releases require supported components, valid bindings, compatible contracts, and complete English/Spanish content. The backend hosts a derived release registry; Contentful remains the authoring authority. Authors preview only synthetic data.

Existing drafts/processes keep their release; automatic migration is deferred. Retain active definitions and compatible rendering/submission support. The SPA obtains authorized task/business context through the selected BFF, and the backend validates inputs and stores drafts. Unsupported or missing releases fail visibly without losing answers or silently choosing a newer form.

The BFF enforces the Contentful-authored field constraints again on save and submit; browser checks are for immediate feedback. Contentful cannot override identity, record ownership, task eligibility, submission-contract compatibility, or domain rules such as benefit and payment decisions. These remain server-owned checks even when a CMS-authored rule also helps explain an input error.

The form and locale contract defines the component vocabulary, release lifecycle, runtime binding, language behavior, sample payload, and examples for later specs. Runtime/storage products, exact APIs, BPMN states, and IAM enforcement remain separate decisions.

Evidence: the owner's acceptance and explicit locale clarification in Decide the Contentful form contract and publishing lifecycle.