commit f3699e6f434c6d4252818af379e4da894bb41315 Author: alexz Date: Fri Jul 24 20:47:16 2026 +0000 Import sap-architecture skill diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..6cc973e --- /dev/null +++ b/SKILL.md @@ -0,0 +1,475 @@ +--- +name: sap-architecture +description: Use this skill WHENEVER the user wants to create, generate, draw, design, or author an SAP architecture diagram, SAP BTP solution diagram, SAP Cloud Foundry / Kyma / ABAP environment landscape, Cloud Connector topology, SAP S/4HANA landscape, Fiori / SAP Build / Joule architecture, subaccount diagram, MCP-to-SAP deployment diagram, XSUAA auth flow, Principal Propagation diagram, or anything that should match the visual style of https://architecture.learning.sap.com / SAP Architecture Center. Input is a text description of the topology; output is a pixel-polished `.drawio` file (and optionally a PNG export) that matches the canonical SAP Horizon look — correct palette, Helvetica typography, 10-px grid, SAP BTP service icons, straight arrows, no clipped labels. +--- + +# SAP Architecture Diagram + +Take a natural-language description of an SAP / BTP / on-prem landscape and produce a polished draw.io file in the SAP Architecture Center visual style. Every artifact it emits is validated against the same rules SAP follows in the published reference architectures. + +## Environment setup (do this once per session, before step 1) + +All commands in this skill reference `$SKILL_DIR` — the directory containing this SKILL.md. Set it first, from wherever this file is mounted (e.g. `/mnt/skills/user/sap-architecture`): + +```bash +export SKILL_DIR=/mnt/skills/user/sap-architecture # adjust to this file's actual location +``` + +The skill directory is **read-only**. All scripts resolve their bundled assets relative to their own location, so they run fine from anywhere — but every output must go to a writable path. Do all work in `/home/claude/` and copy final deliverables to `/mnt/user-data/outputs/` (then present them). Scripts that cache artifacts (`render_compare.py`, `template_browser.py`, `iterate.py`) write to `.cache/` under the current working directory, so always invoke them with `cd /home/claude` (or another writable CWD), never from inside the skill directory. + +**Optional renderer (needed only for PNG/SVG export and Nudge mode's visual loop).** The deterministic pipeline — scaffold, relabel, icons, autofix, validate, corpus scoring — needs nothing beyond Python 3 stdlib and works immediately. Rendering to an image requires the draw.io desktop binary, which is a one-time ~105 MB install per session (~2 minutes). If the task calls for a PNG or you want the vision-feedback loop, install it up front: + +```bash +cd /tmp && curl -sL -o drawio.deb \ + https://github.com/jgraph/drawio-desktop/releases/download/v28.0.6/drawio-amd64-28.0.6.deb +apt-get install -y ./drawio.deb >/dev/null 2>&1; apt-get install -yf >/dev/null 2>&1 +printf '#!/bin/bash\nexec xvfb-run -a /usr/bin/drawio "$@" --no-sandbox --disable-gpu\n' \ + > /tmp/drawio-headless && chmod +x /tmp/drawio-headless +export DRAWIO_CLI=/tmp/drawio-headless +``` + +The `xvfb-run` wrapper is required — there is no display server, and the raw binary will hang without it. dbus errors printed during export are harmless Electron noise; the PNG still lands. If the download fails (network restrictions) or the user doesn't need an image, skip this entirely: the validator and corpus scorer are the real quality gates, and the `.drawio` deliverable opens directly in [app.diagrams.net](https://app.diagrams.net). Never block delivery of a validated `.drawio` file on renderer availability. + +There is no browser in this environment, so ignore any `--open` flags mentioned below and any `open ` suggestions printed by the scripts. Instead, copy generated PNGs / `review.html` to the outputs directory and present them — or, for your own review, read the PNGs directly with the view tool. + +## STOP — read this before generating any XML + +This skill normally starts from a pristine SAP reference template. The single most common failure mode is the LLM trying to write a `.drawio` file from scratch and ending up with: dark page background, custom flow verbs (PROMPT/ROUTE/CONTEXT/DELEGATE), wrong zone hierarchy (e.g. Joule nested inside BTP instead of beside it), missing SAP footer/logo branding, off-vocabulary connector colors. None of those mistakes are recoverable by autofix — they are baked into the structure. + +The mandatory first action — before any other tool call — is: + +```bash +python3 "$SKILL_DIR"/scripts/scaffold_diagram.py \ + "" \ + --include-external-sap-references \ + --out +``` + +That script ranks the 71 bundled SAP templates and, when present, cached official SAP reference architectures against the request, copies the best match to the destination, and prints the alternatives. Now you have a SAP-anchored starting point. From here you make surgical label changes only — never `cat < foo.drawio`, never write XML from scratch. + +If the user asks "use the X template", pass `--template ac_X.drawio` to the scaffold instead. If you genuinely need to inspect candidates first without copying, pass `--dry-run`. + +If the scaffolded family is visibly wrong and no SAP reference is close enough, use `render_semantic.py` as a constrained fallback for supported archetypes (`security-operations`, `devops`, `on-prem-connectivity`, `private-connectivity`, `btp-application`, `data-integration`, `integration-flow`, `ai-agent`). This is still deterministic SAP-style XML, not freehand XML. + +The validate.py / compare.py gates will reject weak generations: dark `pageBackgroundColor` is now an error, novelty pill verbs are warnings, missing zones lower the score against the chosen reference, and all bundled references must score 100 against themselves. + +## When to use + +Trigger on any of: + +- "Create an SAP architecture diagram for …" +- "Draw my BTP deployment" +- "Diagram the XSUAA auth flow" +- "Show how ARC-1 connects on-prem SAP via Cloud Connector" +- "Make an L0/L1/L2 SAP ref-arch for …" +- "Like the SAP Architecture Center style" + +For generic diagrams (flowcharts, ER, class) **without** an SAP angle, use a general-purpose diagram approach (e.g. a flowchart skill or Mermaid) instead — this skill's templates and validators are SAP-specific and will fight you. + +## The 6-step workflow + +Follow this sequence exactly — each step produces input for the next, and each gate catches different classes of bug. + +### 1. Parse the description → plan + +Before touching XML, write out (in your head or as a hidden scratch pad): + +1. **Level** — pick L0 / L1 / L2. Default is **L2**. See `references/levels.md` for signals. SAP's published BTP guideline defines these three levels; do not invent L3 unless the user explicitly asks for a non-SAP internal physical diagram. +2. **Zones** — list the landscape columns needed, typically 2–4 of: `User / MCP Client`, `SAP BTP`, `On-Premise`, `Third-party / Hyperscaler`. Some scenarios (Agentic AI) put `Joule` as its own top-level zone beside BTP, not nested inside. +3. **Services** — for each zone list the concrete cards (service name, role, vendor). Flag which BTP services need the official icon from the bundled library. +4. **Flow** — number the steps 1..N. Pick a pill color per step from the semantic palette (auth=green, trust=magenta, MCP=teal, authz=indigo). Use only canonical pill verbs: TRUST, Authenticate, Authorization, A2A, MCP, ORD, HTTPS, OData/REST, SAML2/OIDC, Identity Lifecycle, etc. +5. **Accent / focus app** — the "star" of the diagram (ARC-1, Joule, user's own app). Uses the purple accent. + +Good user context includes: target audience/level, actors and entry points, SAP BTP services, SAP cloud/on-prem/third-party systems, identity and trust mechanism, numbered flow/protocols, required zones, and explicit exclusions. If the user pasted a long architecture note, reduce it to one diagram scope before selecting a template. Do not try to draw every component mentioned in a long document. + +Keep this plan short — a 10-line bullet list is plenty. Don't skip it: diagrams built without a plan drift off-grid and end up with bent arrows. The plan is what you feed into `scaffold_diagram.py` in step 2. + +### 2. Scaffold from a SAP reference template — MANDATORY + +This step is non-negotiable. Run scaffold_diagram.py — it both ranks templates and copies the best one to the destination: + +```bash +python3 "$SKILL_DIR"/scripts/scaffold_diagram.py \ + "" \ + --include-external-sap-references \ + --out +``` + +If you only want to inspect candidates first, add `--dry-run` (no file is created). To pin a specific template, use `--template `. To rename the `` attribute after copy, pass `--diagram-name "Agentic AI on BTP"`. The external-reference flag is safe when no external corpus is cached; it silently uses only bundled templates. + +**71 reference templates** are bundled, all Apache-2.0, sourced verbatim from `SAP/btp-solution-diagrams` (prefix `btp_`), `SAP/architecture-center` (prefix `ac_`), and curated external SAP reference examples (prefix `ext_`). Reference families: Task Center, Build Work Zone, Build Process Automation, Cloud Identity Services / IAM, Private Link, Event-Driven Architecture, E2B connectivity, multi-region resiliency, Federated ML, hyperscaler data integration, Generative AI / RAG, A2A / MCP, Edge Integration Cell, Business Data Cloud, OData via App Router / CAP, B2B / A2A / API-managed integration, DevOps, Joule, SIEM/SOAR, SuccessFactors integration, and Agentic AI. + +The selector reads `assets/reference-examples/template-metadata.json`, which gives every bundled template a curated title, domain, level, aliases, and scenario tags. Templates marked `"primary": true` win for canonical family prompts (e.g. `ac_RA0029_AgenticAI_root.drawio` for "Agentic AI on SAP BTP"). Trust those rankings over raw visible labels such as `Page-1`. + +**Selection guidance once you've reviewed candidates:** + +1. Pick the level first (L0/L1/L2) — `levels.md`. +2. Pick the closest **scenario family**: identity → IAS / IAM templates; data flow → Task Center / Build Work Zone; networking → Private Link / OData PrivateLink; AI umbrella → `ac_RA0029_AgenticAI_root.drawio`; pure A2A/MCP → `ac_RA0029_A2A_MCP.drawio`; embodied/robotic → `ac_RA0029_EmbodiedAIAgents.drawio`; multitenancy → SuSaaS. +3. If two templates are close, prefer the simpler one. Don't try to inherit the busiest available diagram. + +Known anchor templates: + +- Full **Agentic AI / AI Agents with Joule** landscape → `ac_RA0029_AgenticAI_root.drawio`. This is the SAP Architecture Center-style template with SAP Joule, SAP BTP subaccount, Network divider, 3rd Party area, SAP Cloud Solutions, SAP Cloud Identity Services, and Architecture Center footer. Use `ac_RA0029_EmbodiedAIAgents.drawio` only when the prompt explicitly says embodied, robotic, physical agents, or custom implementation layer. +- Focused **A2A / MCP** flow → `ac_RA0029_A2A_MCP.drawio`. +- **Joule tool ecosystem** overview → `ac_RA0029_JouleAgentsToolsEcosystem.drawio`. + +After scaffold has copied a template, **preserve the SAP visual frame** — title band, zone containers, legend (if any), SAP logos, network divider, Architecture Center footer / QR / reference id (if any), identity flow placement, and the selected template's canvas size. For new diagrams without a clear source template, use `1169 × 827`. Rename `` to your subject. Prefer surgical relabeling over deletion. If cards or edges must change, duplicate existing template cells and keep similar zone density, icon count, pill count, and connector rhythm. The fastest way to a good diagram is renaming labels, swapping icons in-place, and adding a few cards next to the existing ones; the slowest way is rewriting the file. + +If the user's scenario is **simpler than the chosen template**, thin the template deliberately instead of preserving irrelevant branches: + +1. Keep the frame, zones, footer, colors, icon scale, and main connector rhythm. +2. Pick the single main flow first; delete only whole unused branches (card + its incoming/outgoing edges + its pills/number markers). +3. Never leave dangling edge references. After each deletion pass, run `validate.py`; orphaned edges are structural warnings that generated diagrams should fix before delivery. +4. Re-space cards as groups inside their zones; keep sibling cards aligned on common x/y centers and keep at least 40 px between cards and pills. +5. Prefer moving pills into connector gaps over adding edge text. If a pill no longer explains a real edge, delete it with that branch. +6. If thinning removes more than roughly one third of the template, switch to `render_semantic.py` or pick a simpler SAP reference template. + +For Architecture Center templates such as `ac_RA0029_AgenticAI_root.drawio`, do **not** replace the white canvas, footer, network divider, or SAP-branded area structure with a dark dashboard layout. If the user asks for a "legend" but the chosen template has no separate bottom legend, satisfy that by preserving the existing inline pills/labels and printing the flow narration after the diagram. + +**Do not draw from scratch.** Starting from a pristine template is the single highest-fidelity trick in this skill. Building a `.drawio` directly with Write/Edit (without scaffold_diagram.py first) is the most common cause of validator errors, dark backgrounds, novelty pill verbs, and bent edges. + +### 2b. Semantic fallback for ceiling-limited templates + +Use this only when scaffold candidates are the wrong architecture family or the user asks for a new composition that cannot be expressed by relabeling one template. The renderer supports a small set of BTP archetypes and produces grid-snapped SAP-style XML with anchored orthogonal edges: + +```bash +python3 "$SKILL_DIR"/scripts/render_semantic.py \ + "" \ + --out +``` + +Override the archetype only when the automatic choice is wrong: + +```bash +python3 "$SKILL_DIR"/scripts/render_semantic.py \ + "" --archetype security-operations --out +``` + +Supported archetypes: `security-operations`, `devops`, `on-prem-connectivity`, `private-connectivity`, `btp-application`, `data-integration`, `integration-flow`, `ai-agent`. + +Use `on-prem-connectivity` for SAP Cloud Connector / SAP Connectivity service / SAP Destination service / on-premise SAP S/4HANA flows, including ARC-1 from VS Code through Cloud Foundry. Use `btp-application` for generic Fiori/App Router/CAP/HANA Cloud application diagrams that are not integration-suite flows. Use `data-integration` for SAP-to-hyperscaler data movement such as Databricks, Snowflake, lakehouse, Datasphere, or data warehouse prompts. After semantic rendering, run the same autofix / validate / render-review loop. If a proper SAP template exists, prefer the template; semantic fallback is for escaping a bad nearest-template geometry ceiling. + +### 3. Place BTP service icons from the bundled library + +For every BTP service in your plan, look up the icon: + +```bash +python3 "$SKILL_DIR"/scripts/extract_icon.py "Destination Service" \ + --x 600 --y 300 --id svc-dest --parent 1 +``` + +**Icon size — critical, this is the #1 visible bug:** the SAP corpus uses **32×32 px** for the vast majority of icons (224× across the 71 templates), then **48×48** (157×) only for focal anchors next to a zone label. The script's defaults are now `--w 32 --h 32`. **Do not override above 48×48** — anything 64+ overpowers the cards and overlaps text. The validator now flags `w>64 or h>64` as a warning. + +**Icon placement — the second most common bug:** never drop an icon on top of a card's text. Two safe patterns: + +1. **Tucked inside a card** — set the icon's `parent` to the card's id, with small local `x` / `y` (e.g. `x=8 y=8 w=24 h=24`). The icon sits in the card's top-left corner. +2. **In a dedicated empty region** — a 32×32 icon in a slot near the zone label, with no other vertex within ~40 px. + +The validator now flags any icon that overlaps a non-icon vertex by more than 25% of the icon's area. + +The script: +- Fuzzy-matches the service name against the 100-icon index (`assets/icon-index.json`) +- Emits a ready-to-paste `` with the exact SVG data URI the SAP library ships +- Snaps `x/y/w/h` to the 10-px grid + +To list all available icons: `extract_icon.py --list` + +**If the bundled 100-icon library lacks the icon** (common for business objects and non-BTP products), fall back in this order — never leave a bare unstyled rectangle: + +1. draw.io's built-in SAP shape library: `shape=mxgraph.sap.icon;SAPIcon=;` with grey tile chrome (`fillColor=#EDEFF0;strokeColor=#D5DADD;gradientColor=#FCFCFC;gradientDirection=west;`). Names follow the product, e.g. `SAP_Task_Center`, `SAP_Destination_service`. +2. The SAP UI5 icon font as SVG paths — 705 official semantic icons (`business-partner`, `sales-order`, `supplier`, `inventory`, …): `https://cdn.jsdelivr.net/npm/@ui5/webcomponents-icons/dist/generated/assets/v5/SAP-icons.json` (`data. = {path, viewBox}`). Build ``, base64 it, embed it — **using the draw.io data-URI form from `references/drawio-gotchas.md` §1 (no `;base64` token)**, and size per the inscription rule (§6). +3. A grey circle tile (stroke `#D5DADD`) with the label below. + +Third-party logos (Salesforce, IBM, …): embedded SVG/PNG data URI on a circle tile, `imageAspect=1`, square logos inscribed (side ≤ tile diameter / √2). + +Common service → canonical library name hints: "Destination Service" → `sap-destination-service`, "Connectivity Service" → `sap-connectivity-service`, "XSUAA" / "Authorization & Trust" → `sap-authorization-and-trust-management-service`, "Cloud Connector" → `cloud-connector`, "Audit Log" → `sap-audit-log-service`. + +Backend products such as `SAP S/4HANA` are not BTP service icons. Do **not** let `extract_icon.py "SAP S/4HANA"` select `SAP S/4HANA for Microsoft Teams`; the script now fails closed for that query. Use `extract_asset.py "sap-s-4hana" --kind sap-brand-name` for a product label or `extract_asset.py "on-premise-sap" --kind generic-icon` for a generic backend icon. + +For non-service SAP starter-kit assets, use `extract_asset.py` instead. It covers the full indexed library surface: BTP service icons, generic icons, connector presets, area/default shapes, essential shapes, number markers, SAP brand-name text, text elements, and annotation/interface pills. + +```bash +python3 "$SKILL_DIR"/scripts/extract_asset.py --list --kind connector +python3 "$SKILL_DIR"/scripts/extract_asset.py "direct one-directional" \ + --kind connector --id flow-auth --x 200 --y 300 +python3 "$SKILL_DIR"/scripts/extract_asset.py "devices non sap" \ + --kind generic-icon --id ext-devices --x 100 --y 200 +``` + +Prefer these library assets over hand-authored arrows, number bubbles, interface pills, generic device/user icons, or product-name text. SAP explicitly provides these custom draw.io libraries as the starter kit; matching them is higher fidelity than recreating the shapes by style string. + +### 4. Surgical relabel — preserve the template, change only what differs + +You scaffolded from a SAP template in step 2. Now make the *minimum* edits required for the user's scenario: + +- Rename the diagram title and zone labels. +- Swap service-card labels (use exact SAP product names: "SAP S/4HANA Cloud", not "S/4HANA"). +- Add or swap icons via `extract_icon.py` / `extract_asset.py`. +- Adjust connector source/target if you swapped services. + +Prefer the deterministic relabel helper for bulk label edits before hand-editing XML: + +```bash +python3 "$SKILL_DIR"/scripts/relabel.py scaffold.drawio labels.json \ + --out candidate.drawio +``` + +Use either a visible-label map (`{"Old visible label": "New label"}`) or an explicit id map (`{"ids": {"cell-id": "New label"}, "labels": {...}}`). The helper matches visible labels after stripping HTML wrappers and treating `
` as whitespace, so it is safer than ad-hoc search/replace. + +Whenever an edit **adds or hand-authors** mxCell XML (new cards, new edges, embedded logos) rather than just relabeling, first read `references/drawio-gotchas.md` — it covers the encoding rules that fail silently (`;base64` truncation → blank icons, reserved ids `0`/`1` → file rejected, z-order, facing connection points, waypoints, container-relative coordinates). Scaffolded template cells already comply; your additions must too. + +**Do NOT touch:** canvas size, zone hierarchy (e.g. don't nest Joule inside BTP if the reference puts them side by side), network divider, SAP logos, footer band, identity-flow placement. Those carry the SAP visual identity; preserving them is what keeps the score above 90. + +For complex scenarios that require more than label edits, switch into **Nudge mode** below — it converges via small, scored steps with vision feedback, and is much more reliable than trying to land everything in one pass. The manual draw.io workflow (`references/manual-workflow.md`) remains the safety net for the last 20% of polish. + +### 4a. Study the SAP design recipe before editing + +After scaffold, you will get a `📐 SAP design recipe of