Reports

SAP CAP Framework: Full-Stack Development Architecture — Complete Technical

Sarah Chen AI Persona Dev Desk

Lead SAP Architect — Deep Research reports

May 11, 202612 min8 sources

About this AI analysis

Sarah Chen is an AI persona representing our flagship research author. Articles are AI-generated with rigorous citation and validation checks.

Content Generation: Multi-model AI pipeline with structured prompts and retrieval-assisted research

Sources Analyzed:8 publications, forums, and documentation

Quality Assurance: Automated fact-checking and citation validation

Found an error? Report it here · How this works

#SAP #Architecture #Implementation #Best Practices #Deep Research

SAP CAP Framework: Full-Stack Development Architecture

SAP CAP Framework: Full-Stack Development Architecture — Complete Technical Guide

Sarah Chen, Lead SAP Architect — SAPExpert.AI Weekly Deep Research Series

Executive Summary (≈150 words)

SAP Cloud Application Programming Model (CAP) has matured into SAP BTP’s most pragmatic “full-stack” architecture for business applications: CDS as the single source of truth, OData V4 as the contract, and metadata-driven UIs (Fiori elements) for accelerated delivery. The flagship pattern remains CAP service + HANA Cloud + XSUAA/IAS + destinations/connectivity, optionally extended with Event Mesh for asynchronous integration and scalable read models.

This report’s key recommendations:

Treat CDS as a product contract: modularize early (db vs srv vs app), use service projections aggressively, and govern annotations like APIs.
Design authorization first: map XSUAA/IAS roles to @requires/@restrict, add row-level checks deterministically, and test them.
Adopt an “API + Event” dual contract: OData V4 for transactions/queries, events for downstream projections and integration stability.
Plan schema evolution up front for HANA Cloud: use controlled migrations, non-destructive changes, and pipeline validation stages.
Engineer for operations: correlation IDs, structured logs, health checks, and resilience around destinations and S/4 APIs.

Primary reference: SAP Cloud Application Programming Model (CAP) documentation.

Technical Foundation (≈400–500 words)

What CAP is (and why it “fits” enterprise SAP landscapes)

CAP is SAP’s opinionated, model-driven framework for building cloud-native business services—most often deployed on SAP BTP—that aligns with SAP enterprise standards:

CDS (Core Data Services) defines domain model + service model + annotations (UI semantics, authorization hints, validations).
OData V4-first runtime exposure supports Fiori elements and consistent metadata contracts.
Convention over configuration enables “thin services”: standard CRUD, draft handling, validations—custom code only where needed.

CAP documentation: CAP — Getting Started and Core Concepts.

Full-stack CAP reference architecture (golden path)

Runtime & contracts

Backend: CAP Node.js (@sap/cds) or CAP Java (Spring-based).
API contract: OData V4 (default), optional REST-like endpoints.
UI: SAP Fiori elements consuming OData V4 + CDS annotations.
Persistence: SAP HANA Cloud (production), SQLite (local dev commonly).

Platform services

Authentication/Authorization: XSUAA (Cloud Foundry) or IAS-based identity setups, with role collections. See: Authorization and Trust Management (XSUAA).
Connectivity: BTP Destination service + (optional) Cloud Connector for on-prem access. See: SAP Destination service and SAP Cloud Connector.
Events: SAP Event Mesh for pub/sub and asynchronous decoupling. See: SAP Event Mesh.

Architecture diagram (conceptual)

flowchart LR
  subgraph UI["UI Layer"]
    FE["Fiori elements (SAPUI5)\nOData V4 Consumer"]
  end

  subgraph BTP["SAP BTP"]
    CAP["CAP Service\n(Node.js/Java)\nCDS Model + Handlers"]
    HANA["SAP HANA Cloud\nPersistence"]
    XSUAA["XSUAA / IAS\nAuthN/AuthZ"]
    DEST["Destination Service"]
    EM["Event Mesh\nPub/Sub"]
  end

  subgraph Enterprise["Enterprise Systems"]
    S4["SAP S/4HANA\nReleased APIs / Events"]
    ONP["On-Prem Systems\nvia Cloud Connector"]
  end

  FE -->|OData V4| CAP
  CAP --> HANA
  FE -->|OAuth2| XSUAA
  CAP -->|Token Validation + Scopes| XSUAA
  CAP -->|Outbound Calls| DEST
  DEST -->|Connectivity| S4
  DEST -->|Connectivity| ONP
  CAP -->|Domain Events| EM
  EM -->|Subscriptions| CAP

Implementation Deep Dive (≈800–1000 words)

This section implements a practitioner “thin-by-default, extensible-by-design” CAP full-stack service using:

CDS modularization
Service projections
Fiori elements–ready annotations
Authorization with @requires/@restrict
HANA-ready persistence
Event hooks for API + Event dual contract

Reference for CDS/service modeling: CAP — Data Modeling with CDS.

1) Project structure and modular CDS boundaries

A scalable baseline layout:

app/                # UI artifacts (Fiori elements, UI5 tooling, etc.)
db/                 # persistence CDS + DB-specific artifacts
srv/                # service CDS projections + handlers
package.json
mta.yaml            # Cloud Foundry (if used)
xs-security.json    # XSUAA security descriptor

Key rule: never expose db entities directly. Always expose service projections from srv/ to preserve API stability and enable field-level and semantics control.

2) Domain model (db) with compositions for aggregates

db/schema.cds:

namespace my.company.sales;

using { cuid, managed } from '@sap/cds/common';

entity Customers : cuid, managed {
  name        : String(200);
  country     : String(3);
  email       : String(255);
}

entity Orders : cuid, managed {
  customer    : Association to Customers;
  orderNo     : String(30);
  currency    : String(3);

  @assert.unique: { orderNo: [orderNo] }
  Items       : Composition of many OrderItems
                 on Items.parent = $self;
}

entity OrderItems : cuid, managed {
  parent      : Association to Orders;
  productId   : String(40);
  quantity    : Decimal(13,3);
  netAmount   : Decimal(15,2);
}

Architect notes

Use compositions to represent lifecycle coupling (aggregate root: Orders, children: OrderItems). This supports consistent transactional semantics and predictable draft behavior later.
Keep “ERP references” as associations or simple IDs—avoid pulling remote semantics into your persistence model prematurely.

3) Service model (srv) with projections as contracts

srv/catalog-service.cds:

using my.company.sales as db from '../db/schema';

service CatalogService @(path: '/catalog') {

  @requires: 'SalesUser'
  entity Customers as projection on db.Customers {
    ID, name, country, email
  };

  @restrict: [
    { grant: 'READ',  to: 'SalesUser' },
    { grant: 'WRITE', to: 'SalesAdmin' }
  ]
  entity Orders as projection on db.Orders {
    ID, orderNo, customer, currency, createdAt, createdBy, modifiedAt, modifiedBy,
    Items : redirected to OrderItems
  };

  entity OrderItems as projection on db.OrderItems {
    ID, parent, productId, quantity, netAmount
  };

  action SubmitOrder(orderId: UUID) returns String;
}

Why this matters

Projections provide API insulation: you can change persistence while keeping service stable.
@requires/@restrict create a declarative authorization baseline that can be reinforced with handler logic for row-level constraints.

Authorization concept reference: CAP — Authorization and Security.

4) Fiori elements readiness: semantic keys, value helps, text associations

Add UI-facing annotations in a separate file to avoid domain pollution:

srv/ui-annotations.cds:

using CatalogService from './catalog-service';

annotate CatalogService.Orders with {
  orderNo @Common.Label: 'Order Number';
  customer @Common.Text: customer.name;
  customer @Common.TextArrangement: #TextOnly;
};

annotate CatalogService.Customers with {
  name @Common.Label: 'Customer';
  country @Common.Label: 'Country';
};

annotate CatalogService.Orders with @UI : {
  HeaderInfo: {
    TypeName: 'Order',
    TypeNamePlural: 'Orders',
    Title: { Value: orderNo }
  },
  LineItem: [
    { Value: orderNo },
    { Value: customer.name, Label: 'Customer' },
    { Value: currency }
  ]
};

Advanced governance tip (often missed)
Treat annotation changes as breaking-change candidates: they can alter navigation, mandatory fields, filterability, and generated UI behavior. Establish PR checks that diff $metadata snapshots (see “Advanced Scenarios”).

Fiori elements and OData V4 basics: SAPUI5 — Developing OData V4 Apps.

5) Custom logic: “thin handlers” and transaction discipline

srv/catalog-service.js (Node.js example):

const cds = require('@sap/cds');

module.exports = cds.service.impl(function () {
  const { Orders } = this.entities;

  // Validate + enforce row-level ownership (example pattern)
  this.before(['UPDATE', 'DELETE'], Orders, async (req) => {
    const user = req.user;
    if (user.is('SalesAdmin')) return;

    // Example: only creator can modify (adjust to your org rules)
    const tx = cds.transaction(req);
    const order = await tx.run(
      SELECT.one.from(Orders).columns('createdBy').where({ ID: req.data.ID })
    );

    if (!order) req.reject(404, 'Order not found');
    if (order.createdBy !== user.id) req.reject(403, 'Not allowed to change this order');
  });

  // Custom action with a single logical transaction
  this.on('SubmitOrder', async (req) => {
    const { orderId } = req.data;
    const tx = cds.transaction(req);

    const order = await tx.run(
      SELECT.one.from(Orders).where({ ID: orderId })
    );
    if (!order) req.reject(404, 'Order not found');

    // Domain invariant example
    if (!order.orderNo) req.reject(400, 'Order number is required');

    // Emit event after successful commit (see Advanced Scenarios for outbox)
    req.on('succeeded', () => {
      this.emit('sales/OrderSubmitted', { orderId, orderNo: order.orderNo });
    });

    return `Submitted ${order.orderNo}`;
  });
});

Practitioner guidance

Keep handler code orchestration-focused; push complex rules into separate, unit-testable domain modules.
Use cds.transaction(req) to ensure multi-entity updates remain consistent.
Treat event publication as part of a reliability design (outbox / retry) rather than “best effort logging”.

Node.js runtime reference: CAP Node.js — Runtime and Service Implementation.

6) XSUAA security descriptor + mapping to CDS roles

xs-security.json (Cloud Foundry XSUAA pattern):

{
  "xsappname": "my-cap-sales-app",
  "tenant-mode": "dedicated",
  "scopes": [
    { "name": "$XSAPPNAME.SalesUser", "description": "Read access" },
    { "name": "$XSAPPNAME.SalesAdmin", "description": "Admin write access" }
  ],
  "role-templates": [
    {
      "name": "SalesUser",
      "description": "Sales user role",
      "scope-references": [ "$XSAPPNAME.SalesUser" ]
    },
    {
      "name": "SalesAdmin",
      "description": "Sales admin role",
      "scope-references": [ "$XSAPPNAME.SalesAdmin", "$XSAPPNAME.SalesUser" ]
    }
  ]
}

Connect the dots

CDS @requires: 'SalesUser' maps to application roles derived from scopes.
In BTP cockpit, assign users via Role Collections referencing these role templates.

XSUAA details: Authorization and Trust Management Service — Application Security Descriptor.

7) HANA Cloud deployment baseline (Cloud Foundry MTA pattern)

mta.yaml (excerpt):

ID: my-cap-sales-app
version: 1.0.0

modules:
  - name: sales-srv
    type: nodejs
    path: .
    parameters:
      memory: 512M
    requires:
      - name: sales-db
      - name: sales-auth
      - name: sales-destination
      - name: sales-eventmesh
    provides:
      - name: sales-srv-api
        properties:
          srv-url: ${default-url}

resources:
  - name: sales-db
    type: com.sap.xs.hdi-container
    parameters:
      service: hana
      service-plan: hdi-shared

  - name: sales-auth
    type: org.cloudfoundry.managed-service
    parameters:
      service: xsuaa
      service-plan: application
      path: ./xs-security.json

  - name: sales-destination
    type: org.cloudfoundry.managed-service
    parameters:
      service: destination
      service-plan: lite

  - name: sales-eventmesh
    type: org.cloudfoundry.managed-service
    parameters:
      service: event-mesh
      service-plan: default

HANA Cloud + HDI concepts: SAP HANA Cloud — HDI Containers.
(Use your landscape’s supported plan names; they vary by region/entitlement.)

Advanced Scenarios (≈500–600 words)

1) “API + Event” dual contract with Event Mesh (beyond CRUD)

A robust enterprise CAP service increasingly needs:

OData V4 for transactional integrity + Fiori UI.
Events for downstream read models, integrations, and decoupled processes.

Advanced reliability pattern (often under-implemented): Transactional outbox
Instead of emitting events directly on request success, persist an Outbox entry in the same DB transaction, then have a background worker publish to Event Mesh with retry and idempotency.

Minimal outbox model:

namespace my.company.integration;

using { cuid, managed } from '@sap/cds/common';

entity Outbox : cuid, managed {
  topic       : String(200);
  payload     : LargeString;
  status      : String(20);   // NEW, SENT, ERROR
  attempts    : Integer;
  lastError   : LargeString;
}

Why it matters: it prevents “DB committed but event lost” failure modes—crucial for auditability and integration correctness.

Event Mesh reference: SAP Event Mesh — Concepts and Usage.

2) Performance engineering: controlling graph depth and `$expand`

Common CAP performance surprises are self-inflicted:

deep $expand graphs from UI templates
N+1 reads from careless handler logic
“accidental exposure” of large blobs via projections

Controls

Shape your contract: create “thin list” entities for list pages and separate detail entities for object pages.
Constrain expansions: deny or rewrite pathological expansions in READ handlers when needed.
Use pagination deterministically: enforce $top defaults and max limits for public APIs.

CAP OData behavior and service concepts: CAP — OData and Services.

3) Metadata governance: `$metadata` snapshot tests (advanced, high leverage)

Because annotations are behavior, introduce a pipeline step that:

boots the service in CI
downloads /catalog/$metadata
compares against a committed snapshot (allowing intentional diffs only)

This catches “annotation drift” that breaks Fiori elements apps without obvious backend test failures.

Developers often underestimate this—until multiple UIs consume the same service.

4) Destination-based integration: resilience by design

For S/4HANA and external calls, use the BTP Destination service to externalize endpoints/credentials (avoid hardcoding). Reference: SAP Destination service — Destinations.

Add enterprise-grade resilience

retry with exponential backoff on transient HTTP 429/503
circuit breaker for repeated failures
explicit timeout budgets aligned to UX and upstream SLAs
error mapping that preserves business semantics (don’t leak low-level HTTP noise)

If you need transformations/routing, use Integration Suite rather than embedding mapping logic in CAP. Reference: SAP Integration Suite documentation.

Real-World Case Studies (≈300–400 words)

Case 1 — Side-by-side approvals for S/4HANA purchasing exceptions

Problem: Business needed an exception handling UI for purchase requisitions with custom approval rules, without modifying S/4HANA Cloud.
Architecture:

CAP service as an orchestration and extension attribute store (system of engagement).
Read-only S/4 data consumption via released APIs through Destination service and connectivity.
Fiori elements UI driven by CAP annotations, with draft enablement for multi-step review.

Lessons learned

Early wins came from metadata-driven UI, but the long-term success factor was annotation governance and API contract discipline.
Authorization complexity grew quickly; row-level rules required a consistent strategy (CDS restrictions + handler checks + tests).
Introducing events later (for audit + notification) was smoother once a canonical domain model existed.

Case 2 — B2B self-service portal with tenant isolation

Problem: A partner portal required strict partner/tenant isolation and scalable read performance.
Architecture:

CAP multitenancy with subscription-based provisioning.
HANA Cloud persistence with tenant-aware separation strategy.
“API + Event” pattern: OData for portal operations; domain events to refresh read models and trigger downstream processes.