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 (my429480.s4hana.cloud.sap productive; development tenant my431353.s4hana.cloud.sap since 2026-09-15 — API-only tenants: no RFC, no custom IDocs): materials, BOMs, change masters, documents. 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-002, 2026-09-04 — on-stack first)

The application lives in the tenant: a custom RAP business object for the approval domain, a Fiori Elements app in the tenant's Fiori launchpad, IAM app / business catalog / business roles as the only access control, and custom CDS views for discoverability. Side-by-side is reduced to one hardened TypeScript connectivity worker (Arena webhook/poll/session/files + initial sync executor) — machine-to-machine only, no UI, no user-facing URLs.

The acceptance test: a business user finds the app in the Fiori launchpad and its data in the Custom CDS Views app. Anything that fails that test is not done.

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 development tenant (create/activate/transport/ATC/unit tests)	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 (verified 2026-09-15): the sap-api CLI (/usr/local/bin/sap-api) reaches the development tenant my431353 by default (credentials in ~/projects/sap-integrations/_shared/.env; the productive credential is .env.prod-my429480.bak) 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.

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	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-14)

Implementation so far: the TypeScript connectivity worker in worker/ (Fastify surface + Arena session core; sync executors are stubs until V-2). The on-stack RAP track has no code yet — gated on V-1. The Fiori Elements app (app/, TypeScript) is scaffolded against a mock OData V4 service: npm run start-mock serves it on port 8082; its service identity is provisional until reconciled with the live RAP UI binding at V-2.

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-001 amended by ADR-002)
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