A beginner-friendly, developer-focused guide with real project examples

Introduction

SAP Commerce (formerly Hybris) architecture can feel confusing when you are new to the platform.
There are controllers, facades, services, integrations, and many moving parts.

In this beginner-friendly guide, I explain SAP Commerce architecture using a real project flow, simple language, and developer-level examples.
This article is useful for:

• Beginners learning SAP Commerce
• Developers moving from Java to SAP Commerce
• Anyone preparing for SAP Commerce interviews or certification

What Is SAP Commerce Architecture?

SAP Commerce follows a layered architecture.
Each layer has a clear responsibility and should not mix with others.

At a high level, SAP Commerce has:

• UI Layer
• Controller Layer
• Facade Layer
• Service Layer
• Integration Layer
• Persistence Layer (Database & Solr)

This separation helps build scalable, maintainable, enterprise-grade applications.

Real Project Scenario (Simple Example)

Let’s understand the architecture using a real-world scenario:

A B2B user logs in, searches for a product, adds it to the cart, inventory is checked from SAP ERP, and the order is placed.

This is a very common flow in real SAP Commerce projects.

Step 1: UI Layer (Where the Request Starts)

The UI layer is where the user interacts with the application.

Depending on the project, this can be:

• Spartacus (Angular) using REST APIs
• Accelerator (JSP) using Spring MVC controllers

Example (Spartacus calling OCC API)

POST /occ/v2/b2bsite/users/current/carts/current/entries

At this stage:

• No business logic
• No database logic
• No ERP calls

The UI only sends a request.

Step 2: Controller Layer (Entry Point)

Controllers receive requests from the UI.

Responsibilities of Controllers

• Accept request
• Validate basic inputs
• Call the facade layer

Controllers should be thin and simple.

Example Controller Code

@PostMapping("/entries")
public CartModificationWsDTO addToCart(
        @RequestBody AddToCartRequestWsDTO request) {
    return cartFacade.addToCart(
            request.getProduct().getCode(),
            request.getQuantity());
}

👉 Beginner Tip:
If you write business logic inside a controller, it is a design problem.

Step 3: Facade Layer (Orchestration Layer)

The facade layer acts as a bridge between UI and services.

Why Facades Are Important

• Keeps controllers clean
• Reusable for UI, OCC, Backoffice, and batch jobs
• Handles data conversion

Example Facade Code

public CartModificationData addToCart(String productCode, long quantity) {
    validateProduct(productCode);
    return cartService.addToCart(productCode, quantity);
}

Facades should coordinate, not contain heavy logic.

Step 4: Service Layer (Business Logic Layer)

This is the most important layer in SAP Commerce.

What Goes into Services

• Business rules
• Validations
• Pricing logic
• Inventory logic

Example Service Code

public CartModificationData addToCart(String productCode, long quantity) {
    ProductModel product = productService.getProductForCode(productCode);
    inventoryService.validateAvailability(product, quantity);
    priceService.recalculateCart();
    return commerceCartService.addToCart(
            getSessionCart(), product, quantity, null);
}

👉 Real-world note:
Most custom logic in SAP Commerce projects lives in the service layer.

Step 5: Integration Layer (ERP & External Systems)

SAP Commerce usually does not own pricing or inventory data.

Integration is done with:

• SAP ECC / S/4
• SAP CPI
• External services

Example Inventory Check

public void validateAvailability(ProductModel product, long quantity) {
    InventoryResponse response =
        erpInventoryClient.getAvailability(product.getCode());
    if (response.getAvailableQty() < quantity) {
        throw new InsufficientStockException(
            "Not enough inventory");
    }
}

Real-Time vs Async

• Cart & pricing → synchronous
• Order confirmation → asynchronous

Step 6: Persistence Layer (Database & Type System)

SAP Commerce uses a Type System to store data.

Example items.xml

<itemtype code="CustomInventory" extends="GenericItem">
    <attributes>
        <attribute qualifier="productCode" type="java.lang.String"/>
        <attribute qualifier="availableQty" type="java.lang.Long"/>
    </attributes>
</itemtype>

FlexibleSearch Example

SELECT {pk} FROM {Product AS p} WHERE {p.code}=?code

⚠️ Poor FlexibleSearch queries can cause performance issues.

Step 7: Solr (Search & Performance)

Solr handles:

• Product search
• Category pages
• Facets and filters

Common Beginner Mistakes

• Reindexing too frequently
• Indexing unnecessary fields
• Ignoring caching

Solr configuration has a big impact on performance.

Order Placement Flow (End to End)

When the user places an order:

1. Cart validation
2. Inventory re-check
3. Price re-check
4. OrderModel creation
5. Business process started
6. ERP order creation
7. Confirmation sent

Business Process Trigger

businessProcessService.startProcess(
    "order-process-" + order.getCode(),
    "order-process");

Security and Performance Basics

Security

• OAuth / JWT for OCC
• Input validation
• Secure properties
• HTTPS

Performance

• Avoid ERP calls on page load
• Cache facade/service results
• Use async processing where possible

Common Mistakes Beginners Make

• Writing logic in controllers
• Calling ERP on every page load
• No caching strategy
• Very large service classes
• Ignoring Solr optimization

FAQ – SAP Commerce Architecture

What is SAP Commerce architecture?
SAP Commerce architecture is a layered design that separates UI, business logic, integrations, and persistence.

Where should business logic be written?
Business logic should always be written in the service layer.

How does SAP Commerce integrate with SAP ERP?
Integration is done using RFC, OData, or SAP CPI based on project needs.

Conclusion

SAP Commerce architecture becomes easy once you understand the real request flow.

If you follow:
UI → Controller → Facade → Service → Integration → Persistence

You will build:

• Clean and maintainable code
• Scalable enterprise solutions

What’s Next?

In upcoming posts, I’ll cover:

• Facade vs Service best practices
• SAP Commerce interview questions