upload current sources

docs/adr/ADR-002-on-stack-first.md

@@ -0,0 +1,85 @@
+# ADR-002 — On-stack first: RAP approval domain + Fiori app in the tenant; side-by-side reduced to a connectivity worker
+
+Date: 2026-09-04 · Status: Accepted (amends ADR-001)
+
+## Context
+
+The decisive test came from outside: the showcased UI apps present the data
+well, but they are invisible from inside S/4HANA — not in the Fiori launchpad,
+not discoverable in the Custom CDS Views app, reachable only via standalone
+Cloud Foundry URLs behind an ad-hoc route structure with weak access control.
+For an S/4HANA user, an application that cannot be found in the tenant does not
+exist.
+
+ADR-001 correctly rejected the Express shape but still assumed a side-by-side
+BTP application (CAP) as the rebuild target. That assumption fails the same
+test: a CAP app on BTP is still a standalone URL outside the tenant.
+
+S/4HANA Cloud Public Edition offers two in-tenant extensibility tiers, both
+verified against SAP documentation (2026-09-04, via sap-docs MCP):
+
+- **Developer extensibility**: upgrade-stable ABAP Cloud development directly
+  on the stack (ADT against the development tenant) — CDS entities, RAP
+  business objects with behavior, custom Fiori apps deployed into the tenant,
+  authorization via IAM app → business catalog → business role.
+- **Key-user extensibility**: Custom Business Objects, Custom CDS Views (on
+  released C1 view entities), Custom Analytical Queries, and Business
+  Configuration maintenance via the Custom Business Configurations app.
+
+The estate's standing rule already says extensibility-first: check what the
+tenant can host before building side-by-side.
+
+## Decision
+
+I move the application into the tenant and shrink the side-by-side footprint to
+what genuinely cannot run there:
+
+**On-stack (developer extensibility, ABAP Cloud / RAP):**
+- A custom RAP business object for the Arena change approval domain — staging
+  data, approval state machine (pending → approved/rejected), audit fields —
+  persisted in the tenant.
+- A Fiori Elements List Report / Object Page on that BO, deployed to the
+  tenant's Fiori launchpad; approve/reject as RAP actions.
+- IAM app, business catalog, and business roles as the only access control —
+  no user-facing custom URLs anywhere.
+- Custom CDS views over the approval BO (joinable with released views such as
+  I_Product) so the data is discoverable in the Custom CDS Views app and usable
+  in analytical queries — the discoverability test that triggered this ADR.
+- Business mappings evaluated as Business Configuration maintenance objects
+  (Custom Business Configurations app) instead of JSON files in git.
+
+**Side-by-side (one hardened TypeScript worker, no UI, no user URLs):**
+- Arena connectivity only: webhook receipt, delta polling, session management
+  (25-min TTL, login race), file streaming.
+- Initially also the sync executor: on approval, it calls the released OData
+  APIs (Product/BOM/ChangeMaster/Attachment) exactly as the predecessor did —
+  every KNOWLEDGE.md tombstone stays valid unchanged.
+- It exchanges data with the tenant through the approval BO's service binding
+  exposed via a custom communication scenario/arrangement with a technical
+  user.
+
+CAP exits the architecture: with the domain, UI, and persistence on-stack, the
+remaining side-by-side piece is a pipeline, and per the two-archetype standard
+a pipeline is a worker, not a CAP service. This resolves ADR-001's deferred
+question and PRD OQ-1 through OQ-4 in one move.
+
+## Consequences
+
+- The Fiori launchpad becomes the application's only front door; the shared
+  BTP gateway, XSUAA role juggling, and standalone routes disappear from this
+  package entirely.
+- Persistence and audit live in the tenant — the predecessor's
+  lost-on-restart approval queue defect is solved structurally, not patched.
+- The toolchain shifts: ABAP Cloud + RAP + Fiori Elements, so the MCP loadout
+  moves to sap-docs / abap-docs / sap-released-objects / fiori / ui5, and
+  cap-mcp-server leaves the loadout.
+- Verification items before build (POC gates):
+  - V-1: confirm developer-extensibility access on my429480 (development
+    tenant reachable via ADT, developer business role assigned).
+  - V-2: confirm a custom communication scenario can expose the approval BO's
+    OData service to the worker's technical user.
+  - V-3: evaluate on-stack Application Jobs vs the worker for Arena delta
+    polling; and Business Configuration objects vs config files (ARN-004).
+- Fallback recorded: if developer extensibility proves unavailable on this
+  tenant, the key-user tier (Custom Business Object with generated UI) is the
+  degraded-but-still-in-tenant variant; side-by-side is no longer the fallback.