arena-plm-fiori/CLAUDE.md

arena-plm — Arena PLM → SAP S/4HANA Integration (standalone)

This file is a MAP, not a cache. It says where things are and how to verify them — it does not store conclusions. Every factual claim in this repo carries a verified-on date; an undated claim is a hypothesis, not a fact.

What this is

Approval-gated sync of Arena PLM items into SAP S/4HANA Public Cloud: materials, BOMs, change masters, documents.

Both tenants named in this repo belong to the same starter system. The working target is the starter system's customizing tenant my429480.s4hana.cloud.sap (client 100 — key-user extensibility and configuration only; no ABAP, no RAP). The starter system's development tenant my431353.s4hana.cloud.sap (client 080 — developer extensibility) is parked as of 2026-09-29, with the objects I built there left in place. Both tenants are API-only: no RFC, no custom IDocs.

Standalone successor to the Express implementation at ~/projects/sap-apps/arena-plm, which is reference-only — consult it for behavior, never extend it.

Architecture (ADR-004, 2026-09-29 — side-by-side against released APIs)

The on-stack RAP route of ADR-002 is withdrawn and superseded. The starter system's customizing tenant my429480 (client 100) supports key-user extensibility only — no ABAP, no RAP — so the custom RAP business object ADR-002 called for has no home in the tenant I work in.

The application therefore runs side-by-side against released OData APIs, with the customizing tenant as the sync target and configuration home. The replacement host is deliberately left open as OQ-11: key-user extensibility in the customizing tenant (custom business object plus a low-code UI) versus a CAP service side-by-side on BTP. My recommendation is CAP — the connectivity worker has to live side-by-side whatever else happens, and one runtime beats two. No build starts until OQ-11 is closed.

Kept, unchanged in value: the hardened TypeScript connectivity worker (Arena webhook/poll/session/files + initial sync executor) — machine-to-machine only, no UI, no user-facing URLs, and needed under either OQ-11 option — and the Fiori Elements app in app/, which is repointable.

Parked reference, not deleted: the RAP approval business object I built on the starter system's development tenant my431353 (client 080). All 19 ZARENA_PLM objects are left active there and their sources stay in docs/handover/rap/, so that route stays reversible at zero cost.

The acceptance test, as amended by ADR-004: a business user finds the application from the S/4HANA launchpad and access is governed by business roles. The "its data in the Custom CDS Views app" clause is withdrawn — it is unreachable from client 100.

Operating rules

1. Never guess SAP behavior. Query the MCP servers below first — do not first decide whether the question "needs" a lookup; that judgment is the thing that fails. If no source confirms it, say "I don't know."
2. POC before spec. Field mappings and integration specs are unusable until validated by a working POC against real endpoints.
3. No hand-rolled SAP plumbing. On-stack: RAP/EML and released ABAP APIs only. In the worker: released OData APIs through the established destination (mc-s4hana) — never hand-managed CSRF or auth.
4. Mappings live in the tenant. Evaluate Business Configuration maintenance objects before any file-based config (PRD ARN-004).
5. Read KNOWLEDGE.md before designing any SAP write path. It holds paid-for negative results; re-learning them costs hours against live systems.
6. Cite or it didn't happen. Every SAP behavioral claim recorded in PRD/ADR/KNOWLEDGE carries [source: <server> <doc-id/URL>, verified YYYY-MM-DD]. Enforcement is structural (ADR-003): hooks inject this charter each session, and a consultation gate denies edits to SAP artifacts unless an MCP/web consultation happened in the last 30 minutes. (*.md, docs/, and .claude/ paths are exempt; a denial names the server to consult — consult it, then retry the edit.)
7. API-first (adopted 2026-09-10, PRD ARN-009). Any interface this package creates or changes gets its OpenAPI 3.1 JSON contract authored or updated under docs/api/ before or with the change; implementation conforms to the contract. Consumed SAP released APIs keep SAP's published contracts — docs/api/ holds only surfaces this package owns.

MCP routing (this package's loadout — deliberately slim, matched to ADR-002)

Working on	Server
ABAP Cloud / RAP / CDS statement syntax & semantics	abap-docs
RAP guides, extensibility docs, SAP Help / Community	sap-docs
Is this SAP object released for ABAP Cloud? Successors?	sap-released-objects
Fiori Elements, @UI annotations, manifest	fiori-mcp-server
Writing objects INTO the starter system's development tenant (create/activate/transport/ATC/unit tests) — parked 2026-09-29 with that tenant	adt-mcp — SAP ADT MCP Server from sapse.adt-vscode, http://127.0.0.1:2236/mcp; bearer token lives in ~/.vscode-server/data/Machine/settings.json and changes on VS Code reload — refresh .mcp.json then
UI5 controls/views (only if custom UI proves necessary)	ui5-mcp-server

When MCP guidance conflicts with training knowledge, follow MCP.

Live system checks from this box: as of 2026-09-29 the sap-api CLI (/usr/local/bin/sap-api) reaches the starter system's customizing tenant my429480 by default (credentials in ~/projects/sap-integrations/_shared/.env; the parked development-tenant credential is .env.starter-dev-my431353.bak and the customizing-tenant copy is .env.starter-cust-my429480.bak, both in the same folder) and Arena — API catalog search, EDMX fetch, OpenAPI generation (sap-api apis generateOpenapi --service …), communication arrangements (comm), user/role admin (users), and read paths for the released business APIs and Arena items. Read commands are fair game for design and acceptance; mutating commands are delegated like any other write. The retarget is in place, but the my429480 credential itself answered HTTP 401 ("Anmeldung fehlgeschlagen") on 2026-09-29 — it needs refreshing before any CLI call against that tenant succeeds.

Delegation (project agents in .claude/agents/)

Implementation goes to the specialists below; their tool restrictions are the role contract (the reviewer cannot write, the test agent runs on the low-cost model). All inherit the ADR-003 hooks automatically. Design record and verified sources: docs/agent-roster.md.

Work	Agent
On-stack ABAP Cloud: RAP BO, CDS, behavior, IAM artifacts — dormant while the RAP route is parked (ADR-004)	rap-developer
Fiori Elements app, @UI annotations, manifest, launchpad	fiori-developer
TS connectivity worker: Arena API, Cloud SDK OData writes	worker-developer
Read-only SAP review: clean core, contracts, tombstones	sap-code-reviewer
Tests for worker + service layers	test-engineer

Repo state & commands (verified 2026-09-29)

Nothing in this package has ever been deployed or reached a business user, and no build resumes until OQ-11 is closed. What exists:

• worker/ — the TypeScript connectivity worker (Fastify surface + Arena session core; sync executors are stubs). Built, 137 tests green, never deployed. Needed under either OQ-11 option.
• app/ — the Fiori Elements app (TypeScript), bound to a mock OData V4 service: npm run start-mock serves it on port 8082. Its service identity is provisional; it gets repointed once OQ-11 names the host.
• docs/handover/rap/ — the sources for the 19 ZARENA_PLM objects I activated on the starter system's development tenant my431353, parked 2026-09-29 with the objects left in place. Reference and a reversible route, not a live track.

In worker/: npm run build (tsc), npm run lint (eslint), npm test (vitest), npm run dev (tsx watch). The worker's HTTP surface is governed by docs/api/worker.openapi.json (rule 7) — change the contract first.

Files

File	Purpose
PRD.md	Living requirements, target architecture, contracts, verification items
CHANGELOG.md	Append-only decision log
KNOWLEDGE.md	Dated tombstones & landmines — the only knowledge carried from the predecessor; also check it when anything unexpected appears in the repo
docs/adr/	Architecture decision records (ADR-004 supersedes ADR-002 and partly revives ADR-001)
docs/agent-roster.md	Specialist-agent design + verified sources
docs/predecessor-flow.md	How the Express predecessor actually works (extracted 2026-09-10) — read before designing executor, poller, or approval behavior
.claude/hooks/	ADR-003 enforcement scripts (grounding injections, consult gate, consult marker); tests/run.sh pipe-tests them — run it after any hook change