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

status: accepted

Use a local TypeScript BFF for the Atlas prototype

Placement amendment, 2026-09-26: ADR 0010 supersedes the dedicated Lima VM and local-only demo placement below. The BFF, adapter and MuleSoft deferral decisions remain accepted. Atlas now certifies on the Mac before cloud deployment.

Contract amendment, 2026-09-30: ADR 0011 selects TypeBox for Fastify's code-owned schema contracts. ADR 0012 selects gRPC for suitable private adapters while retaining browser HTTPS/REST and REST integrations where needed. These refine this BFF decision; they do not replace Contentful-driven forms, Camunda workflow ownership or durable delivery. Migration remains implementation work.

Browser transport amendment, 2026-09-30: ADR 0013 selects tRPC over same-origin HTTPS for React-to-SDUI BFF experience calls. It amends the earlier browser REST clause while preserving existing REST compatibility paths, dedicated authentication/file endpoints, TypeBox, and suitable private gRPC integrations.

The owner selected the BFF and backend-adapter alternative for Atlas's first prototype and moved MuleSoft to a later phase. This supersedes ADR 0007 for the prototype. The choice follows Evaluate a BFF and backend adapters as the MuleSoft replacement and the owner's subsequent explicit selection.

Build the Experience API as a Node.js 24 LTS, TypeScript and Fastify backend-for-frontend. Keep versioned REST/OpenAPI and JSON Schema contracts. Put System API adapters for synthetic legacy and payment systems in private backend modules. Camunda remains the BPMN engine, Contentful remains the content authoring source, Keycloak remains IAM, and the business record owners retain authorization, revisions, durable command acceptance, idempotency, outbox delivery, reconciliation and audit.

The first demo runs on the owner's Mac with Docker Compose in a dedicated Linux VM. Use the lightweight Camunda configuration, PostgreSQL, private document volumes, ClamAV and real scanning. Serve the built React/Vite SPA with the BFF through a loopback HTTPS gateway for integrated demos; the Vite development server can proxy the same routes while coding. Contentful remains hosted for authoring and publishing. An imported, immutable bilingual release can render without a live Contentful request on every page. No VPS, Vercel, CloudHub or Mac tunnel is part of the first demo.

This choice removes the first-phase MuleSoft entitlement and hosting dependency. It puts API mapping and policy code under Atlas ownership. It does not license or implement MuleSoft in the later phase, and any later migration needs a separate ADR and compatibility plan.

The Mac was previously observed with 64 GiB RAM and 16 logical CPUs. Start local capacity measurement with an 8-CPU, 24-GiB, 100-GiB-sparse-disk VM allocation. This is a test budget, not a proven requirement. Check ARM64 image support, peak memory during scanner updates, persistence and representative journeys before treating the demo as runnable.

The previous VM prototype showed that a plain guest could reach a harmless Mac-loopback listener. Do not use that VM as a claimed host security boundary. The chosen topology has no cloud-to-Mac tunnel or public ingress. Local route, guest integration and secret controls still need verification.

The authentication change is recorded separately in ADR 0009. The Experience API contract retains its behavioral guarantees and changes vendor ownership only.