Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Cortex Architecture

Cortex Architecture

The Cortex is designed in a multi-layered application structure. Each layer has a specific set of responsibilities and each layer is loosely coupled to the other layers. This design is known as abstraction, where each layer is responsible for a set of tasks and each layer isn't interdependent on the other layers to complete tasks. The sections below outline the Cortex architecture, including the application container and each of the architectural layers.

The reason why this architecture design was chosen is that it simplifies the job of Java developers who are customizing the Cortex. Java developers only need to know two layers: the Rest Resources Layer and the Integration Layer. Customizations, including new features and additions to existing features (like an extension for a cart, lineitem, profile, and so on) are coded solely in these two layers. Because the layers are abstracted, Java developers don't need to touch the other layers in order to implement their customization. For example, if the Java developer was adding a new recommendation feature to shopping carts, they would create a new resource in the Rest Resources layer that would add a link to the shopping cart and create a new resource integration in the Integration Layer to integrate with a back-end system. Developers don't have to change the Authentication, HTTP Bridge, or the Kernel layers in order to create this customization—they also don't have to change the shopping cart resource.

Application Container

Cortex runs in an OSGi container. This container then runs inside of a web application and the web application runs on an application server. This setup leverages the power of the OSGi component model while allowing Cortex to run on a standard application server. Since OSGi contains a collection of components (bundles), each of which can each be in a different state, we created the following OSGi bundle to ensure the server returns an error state when any of the required top-level resource bundles are not started:

  • resource-configuration bundle - Contains an OSGi blueprint configuration file that defines the list of the top-level resource bundles Cortex requires to be in a valid working state.

Since Cortex web application needs to define all of the Maven artifacts to be included for deployment, the web app's pom references the top-level resource bundles as well as all the bundles from the other layers.

Architecture Layers

The sections below provide an overview of each layer and describes their responsibilities. For a detailed description of how a single authorized request makes its way through these architecture layers, see Architecture Call Stack.


The authentication layer is responsible for logging customers into Cortex and for restricting unauthorized customers from accessing protected resources. Once authenticated, Cortex passes an OAuth2.0 token back to the client. When a request for a protected resource comes into the authentication layer, the layer checks that the customer's token is valid and then allows the request to proceed.

HTTP Bridge

The HTTP Bridge uses Jersey to determine the type of incoming HTTP request (GET, PUT, DELETE, POST) and then delegates the requests down to the Kernel for processing. When the request result percolates back up to this layer, the Bridge uses Jackson to convert the returned result into a JSON object. The Bridge then sends the JSON object and an HTTP status messages, indicating the request's success or failure, back to the application that initiated the request.


The Kernel receives the request and the request's URI from the bridge. The Kernel parses the URI to determine the resource being referenced and then delegates the request to the Resource Server to load the resource.

Rest Resources

Each resource is a separate OSGi bundle that controls a specific aspect of e-commerce functionality. For example, the profiles resource is responsible for the customer's details, such as first name, last name, and addresses. The carts resource tracks the items you're purchasing along with total quantity, and so on. It is in this layer alone that java developers make their customizations to expand Cortex capabilities.

Integration Layer

This layer is designed in a similar manner as the Rest Resources layer, where each resource integration is a separate OSGi bundle. Each of the bundles in the layer are implementations of the lookup and writer strategy interfaces that are defined in the Rest Resources Layer. The rest resources call into this layer to perform tasks like retrieve a user's cart, update a customer's profile, and so on. This layer then calls into the Commerce Engine Core using DTOs and domain transformers to perform the tasks that were initiated by the rest resource. By having a granular set of integration bundles and communicating with DTOs, this layer's resource integrations can be customized to integrate with other back-end systems.

Commerce Engine Core

The Core engine of Elastic Path Commerce Engine and contains all services needed to provide e-commerce functionality to Cortex.