Frozen document. Dates and status refer to its original source. Private resources and unreviewed images are unavailable.
Experience Layer contract
Status: accepted behavior. The owner accepted these API defaults on September 22, 2026 and selected a TypeScript BFF/backend-adapter implementation on September 23, 2026. ADR 0010 amends its deployment sequence, not this contract. The authoritative API resolution lives in Decide MuleSoft Experience Layer contracts and recovery boundaries.
This contract applies the accepted record ownership, bilingual forms, and workflow behavior. ADR 0005 records the delivery trade-off. Deployment products and implementation remain downstream.
API boundaries
The September 30 owner decision in ADR 0013 selects tRPC over same-origin HTTPS for React-to-SDUI BFF experience queries and mutations. Existing versioned REST/JSON paths remain compatibility contracts during migration and continue to serve appropriate system/external APIs. OpenAPI describes those REST paths; inferred router types and runtime parsers describe tRPC procedures. Keep separate logical experience and system contracts. The Atlas term Experience Layer names the BFF and its backend adapter boundary for the first prototype. MuleSoft is deferred to a later phase by ADR 0008.
September 30 transport/schema amendment: ADR 0011 selects TypeBox-derived JSON Schema and TypeScript types for code-owned Fastify contracts. ADR 0012 permits supported private system/workflow adapters to use gRPC/protobuf. The later tRPC amendment replaces the browser REST choice for SPA experience calls while retaining HTTPS, opaque sessions and dedicated protocol/file endpoints. Same-process owner modules stay in-process, and existing public errors, records and durable-operation semantics are preserved. See the boundary design for the planned migration.
- Experience APIs serve dashboard/context views, form/task context, drafts, submissions, decisions, operations, payment views, and document metadata. They aggregate only authorized fields for the active personal/employer context.
- System APIs expose the owning simulator modules for people/organizations, intake, coverage/benefits, claims, leave/RTW, billing/disbursements, and document registry. They also mediate release-registry and workflow-adapter access. Logical contracts need not each become a separate service or container.
- Camunda owns long-running BPMN sequencing and human tasks. The BFF owns browser transport, session mediation and request aggregation; backend adapters own system mapping and transport. Do not create a second long-running business process engine in integration code.
[Private setup detail omitted.]
- Workflow screen APIs return a server-driven UI model: the pinned Contentful component tree and declarative validation, joined with the authorized journey or Camunda task, permitted business values, revision, and allowed actions. The client supplies answers and an intended action; the BFF re-resolves the task and applies the same pinned field rules plus owner security and domain checks before accepting a command.
- Carry verified actor and business context through trusted service calls. Never trust a caller-supplied employer, subject, role, task key, or record ID as proof of access. Both API boundaries and record owners enforce relevant permissions. Token/session mechanics remain with the security decision.
Reads and durable operations
Use synchronous queries and revision-checked draft saves. Use durable asynchronous operations for submission/process starts, human decisions, cancellation, and payment-affecting commands. Return 202 Accepted with an operation reference only after the owner has durably recorded the command. Acceptance means processing has been recorded; it does not mean approval, task completion, or settlement.
The browser polls an authorized operation/status endpoint with bounded backoff and a server retry hint. On reload, it can find recent operations from its business case. WebSockets, browser event streams, and external webhooks are deferred for the first demo.
An operation record belongs to the command's business owner. A small integration module in the existing backend deployment keeps delivery/correlation receipts for Camunda and other participants. These receipts do not become editable copies of task or business state. Reads may join owner state with engine task state. Partial dashboard sections must be marked unavailable or stale; missing dependencies must never appear as empty coverage, no task, or a failed payment.
Idempotency, concurrency, and delivery
Require a stable client-generated idempotency key on effectful commands and an expected business revision where a command depends on reviewed state. Persist the deduplication key, canonical payload fingerprint, operation reference, and result with the owner's accepted update. Scope keys to the authenticated actor/service, business context, and operation type. Recheck authorization before returning a replay result.
A retry with the same key and payload returns the same operation. Reusing that key for different input is a conflict. Stale revisions require refresh and deliberate resubmission; do not silently overwrite. Owners also enforce business uniqueness, such as one payment instruction per authorized benefit decision. A fresh key must not bypass that constraint. Keep deduplication evidence for the retained operation lifecycle; later retention policy must not permit forgotten effects to be repeated.
Use a transactional outbox in the owning module and durable consumer receipts for cross-component delivery. A dispatcher retries within the agreed bounded policy using the same command identity. Start with persisted delivery records and workers; no separate message broker is required by this decision. Camunda workers reach business owners through system contracts and never write another module's tables. Avoid nested request chains that wait synchronously for the whole BPMN process.
For task actions, durably correlate the requested decision, accepted engine transition, and business application. Recheck assignment, eligibility, task state, pinned form release, and reviewed business revision. No business decision is applied merely because an action request was received. If the engine accepted the task action but the business revision changed, stop fulfillment, expose a recovery/conflict state, and preserve the competing authoritative outcome. The later spec must define the recovery path without reopening a completed task implicitly or granting an operator decision authority.
The workflow adapter must reconcile uncertain starts and task completions before retransmission. A correlation ID alone is not a deduplication guarantee. Hold an unresolved operation rather than blindly starting another process. The selected Camunda version's start/acknowledgment protocol must be proven with a lost-response test before that implementation slice is ready. Business-owner guards remain mandatory even when engine delivery is duplicated.
Journey contract outlines
Names below describe operations; exact paths, schemas, and enum values belong to specs.
| Journey | Experience contract | Authoritative effect |
|---|
| Life/Medicare supplement | Create/save draft, load pinned form, submit, provide information, read case | Intake accepts the submission and decision; coverage owner creates coverage once after approval. |
| Disability/LTC | Submit claim/request, attach evidence references, respond, review, read separate decision/payment statuses | Claims owner records decision and authorizes payout; billing/disbursements owns payment result. |
| Dental | Submit claim, review, read decision and benefit summary | Claims owner records decision; coverage owner consumes permitted benefit once. |
| Leave/RTW | Submit dates/return information, respond, read assigned tasks, act on task | Leave/RTW owner records each business decision. Evidence review and manager decision have distinct permitted views. |
| Annuity | Request withdrawal, review, read available amount and operation | Coverage owner reserves funds and finalizes once on confirmed success; releases only after a permitted confirmed terminal outcome. |
| Premium/payment servicing | Read obligations, manage synthetic account reference, authorize collection, read payment status | Billing/disbursements captures an instruction's account reference and records attempts/results without redirecting an existing instruction. |
| Documents | Register upload intent, complete transfer, list authorized metadata/versions, request authorized download | Document registry checks association and lifecycle; storage holds bytes. Scan/quarantine/access-link details remain a security decision. |
A case cancellation succeeds only when the owning record is still before approval/commitment. Approval or an authorized financial instruction/reservation closes the respective self-service cancellation window. An uncertain prior operation blocks a conflicting cancellation until reconciled. Exact per-command state guards must be enumerated in specs. No refund or reversal contract is added.
Errors, versions, and list behavior
Return stable error codes, a correlation/operation reference where authorized, and field errors keyed by canonical field identifiers. Distinguish invalid input, unauthenticated, forbidden/not-visible, stale/conflicting action, dependency unavailable, and pending/unknown operation. Exact non-disclosure handling of forbidden versus not-found belongs to security. Never send stack traces, bank details, or internal reviewer notes in errors.
Use bounded cursor pagination and explicit sort order for cases, tasks, documents, and history. API versions change for breaking contracts; internal delivery envelopes include event/command ID, schema version, business reference/revision, and correlation. Form-release compatibility includes supported API versions. Schemas and compatibility examples become shared artifacts for later agent slices.
Stable codes, fields, identifiers, and stored canonical values are language independent. The SPA renders English/Spanish from the applicable catalog; submission locale remains evidence. Changing language does not submit another command. Transport retry identity uses the captured original command payload. New actions carry their own locale and key.
If a system accepts a command but its response is lost, the SPA queries or resends the same identity. The owner returns the stored operation; a downstream timeout remains pending/unknown until reconciled. Only a confirmed result becomes succeeded or failed. If durable acceptance is unavailable, do not display a successful submission.
Evidence required in later specs
Prove response loss after acceptance, same-key replay/conflict, different-key business duplicate prevention, concurrent revision conflict, uncertain Camunda start, accepted task action with a later owner conflict, unknown payment reconciliation, and dependency outage. Include cross-employer access denial and bilingual error/status rendering. These complement the accepted workflow scenarios; no application tests are claimed yet.
Supporting references
The separation of UI-oriented and backend-oriented contracts follows MuleSoft's API categories. Keeping BPMN in Camunda is the Atlas architectural choice. Camunda job-worker documentation requires idempotent handling because jobs can be delivered more than once. Camunda message-event behavior also shows why correlation alone is insufficient: a buffered message can start another instance after a prior instance completes. These references support the recovery requirements; they do not select a runtime version or prove Atlas's eventual implementation.