Starter kit structure

The Adobe Commerce integration starter kit provides boilerplate code to synchronize the following entities across systems:

By default, object synchronization is bi-directional. Changes in Commerce are propagated to the external backoffice application and vice versa.

The source code follows the file structure of a typical App Builder application. Most importantly, the actions directory contains the source code for all the serverless actions.

The following diagram shows the directory structure of the starter kit project:

|__ root
|   |__ actions
|   |   |__ <entity>
|   |   |   |__ commerce
|   |   |   |   |__ consumer
|   |   |   |   |__ <action>
|   |   |   |__ external
|   |   |   |   |__ consumer
|   |   |   |   |__ <action>
|   |   |__ ingestion
|   |   |   |__ webhook
|   |   |__ webhook
|   |   |   |__ <action>
|   |__ scripts
|   |   |__ commerce-event-subscribe
|   |   |__ onboarding
|   |__ test
|   |__ utils

The most important directories and files are described below.

actions directory

The actions directory has the following subdirectories:

Each entity directory has commerce and external subdirectories. The commerce directory contains the runtime actions responsible for handling incoming events from Commerce and synchronizing the data with the 3rd-party external system. The external directory defines the runtime actions that handle incoming events from the external system and updates entities in Commerce.

The contents of the commerce and external directories are similar. Each contains

Individual directories that define actions contain the following files:

File
Purpose
index.js
Contains the main method that gets invoked when handling an event. It is responsible for coordinating the different activities involved in that handling, such as validating the incoming payload, transforming the payload to the target API, and interacting with the target API.
pre.js and post.js
Provide convenient extension points to introduce custom business logic before and after interacting with the target API.
sender.js
Implements the logic to interact with the target API so that the changes are propagated. For actions in the external directory, Commerce APIs are the target. Actions in the commerce directory target external APIs.
schema.json
(external directories only) Defines the schema to be validated against the incoming event payload.
transformer.js
Implements the logic to transform the incoming event payload to make it suitable for the target API being called to propagate the changes.
validator.js
Implements the logic to validate the incoming event payload.

scripts/onboarding directory

The onboarding directory contains the scripting needed to install and set up the starter kit. The scripts/onboarding/config/starter-kit-registrations.json configuration file creates all the registrations for all entities that are present in the repo's app.config.yaml file. You can edit this file to remove any unnecessary Commerce or back office registrations. Onboarding describes the installation process.

scripts/commerce-event-subscribe directory

The commerce-event-subscribe directory contains the script to subscribe the Commerce event provider, which was created during onboarding, to the Commerce events. The scripts/onboarding/config/starter-kit-registrations.json configuration file contains all the Commerce events you want subscribe to. Edit this file to add, remove, or modify the events necessary for your project. Onboarding describes the installation process.

test directory

The starter kit provides unit tests for most of the included runtime actions. These tests are in the test/actions directory. You can also find unit tests for the onboarding script in the test/onboarding directory.

Testing a Serverless Action provides details about unit testing.