arena-plm-fiori/docs/adr/ADR-001-cap-first-rebuild.md

ADR-001 — CAP-first rebuild; Express predecessor demoted to reference

Date: 2026-09-04 · Status: Accepted — amended by ADR-002 (2026-09-04): the rebuild target is now on-stack RAP + Fiori Elements in the tenant, with a side-by-side connectivity worker; CAP exits the architecture. This ADR's core rationale — the SAP toolchain must engage, and the Express shape is not the pattern — stands unchanged.

Context

The working predecessor (~/projects/sap-apps/arena-plm) is Express.js + axios with hand-rolled SAP patterns. It functions, but it sits outside the SAP-native toolchain: the CAP, Fiori, and UI5 MCP servers and skills had nothing to attach to, so development guidance never engaged, and the implementation drifted from SAP best practice — hand-managed CSRF tokens, an approval store in droplet-local SQLite that vanishes on restart, JWT validation with no scope checks. The estate is explore-phase; there is no production cutover to protect, so preserving the legacy shape has no value beyond reference.

Decision

I rebuild arena-plm as a CAP (Node.js) application: the approval domain modeled in CDS, all S/4HANA calls through CAP remote services / SAP Cloud SDK via the mc-s4hana destination, and Fiori Elements evaluated before any custom UI5. The Express app is reference-only — consulted for behavior and tombstones, never extended.

Consequences

• The SAP toolchain becomes load-bearing: cap-mcp-server is consulted on every model and service change, which is the corrective for the tooling-never-engaged failure mode.
• Auth, CSRF, and destination handling move onto framework-managed code paths, eliminating the predecessor's hand-rolled plumbing.
• The approval workflow domain must be re-modeled in CDS; behavior parity is checked against the reference app, never assumed from it.
• Whether the sync-pipeline half stays inside CAP or becomes a separate hardened worker is deliberately deferred (PRD OQ-4).