Spryker Documentation

Migrate OauthApi to API Platform

Fri, 24 Apr 2026 12:48:49 +0000

This document describes how to migrate the `OauthApi` Glue module to API Platform. The `OauthApi` module now ships an API Platform `/token` resource in-place — the Processor class and resource schema live inside the `OauthApi` module itself and delegate to the `Authentication` client. ## Prerequisites Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. ## Overview The `OauthApi` module provided the `/token` endpoint for the `GlueStorefrontApiApplication`. It registered the resource through the `OauthApiTokenResource` plugin, which routed requests to a legacy controller. This endpoint is now served by API Platform: | Endpoint | Operation | Legacy plugin | |---|---|---| | `POST /token` | OAuth2 token endpoint supporting `password` and `refresh_token` grant types | `OauthApiTokenResource` | The API Platform `Tokens` resource delegates to `Spryker\Client\Authentication\AuthenticationClient::authenticate()`, which returns an `OauthResponseTransfer` used to populate the response. {% info_block infoBox "Application scope" %} This `/token` endpoint is registered only in the `GlueStorefrontApiApplication`. In the legacy Glue application, `/token` is served by the `AuthRestApi` module — see [Migrate AuthRestApi to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html). {% endinfo_block %} ## 1. Update module dependencies ```bash composer require spryker/oauth-api:"^X.Y.Z" ``` {% info_block infoBox "Version" %} Use the version that ships the API Platform resources. Check the module changelog for the exact version. {% endinfo_block %} ## 2. Remove OauthApiTokenResource from GlueStorefrontApiApplicationDependencyProvider In `src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php`, remove the following plugin from `getResourcePlugins()`: | Plugin to remove | Fully qualified class name | |---|---| | `OauthApiTokenResource` | `Spryker\Glue\OauthApi\Plugin\GlueApplication\OauthApiTokenResource` | Also remove the matching `use` import at the top of the file. Keep the other `OauthApi` plugins registered in the same file — they continue to wire authentication into the storefront API application: - `Spryker\Glue\OauthApi\Plugin\AccessTokenValidatorPlugin` - `Spryker\Glue\OauthApi\Plugin\CustomerRequestBuilderPlugin` - `Spryker\Glue\OauthApi\Plugin\GlueApplication\CustomerRequestValidatorPlugin` ## 3. Exclude OauthApi from the legacy Glue application The legacy Glue application serves `/token` through the `AuthRestApi` module. To prevent the `OauthApi` schema from registering a duplicate `/token` route there, exclude it from the legacy Glue application's generator. In `config/Glue/packages/spryker_api_platform.php`, add `OauthApi` to the `excludedPathFragments` list: ```php $sprykerApiPlatform->excludedPathFragments([ 'src/Spryker/OauthApi/resources/api/', // ...other entries ]); ``` The `GlueStorefrontApiApplication` continues to discover `OauthApi` schemas via `config/GlueStorefront/packages/spryker_api_platform.php` — do not exclude `OauthApi` there. ## 4. Regenerate transfers and API resources ```bash docker/sdk cli console transfer:generate docker/sdk cli glue api:generate docker/sdk cli glue cache:clear ``` ## Relationship plugin status The `OauthApi` module did not register any relationship plugins. No relationship changes are needed.

Migrate AuthRestApi to API Platform

Fri, 24 Apr 2026 12:48:49 +0000

This document describes how to migrate the `AuthRestApi` Glue module to API Platform. The `AuthRestApi` module now ships API Platform resources in-place — the Provider/Processor classes and resource schemas live inside the `AuthRestApi` module itself, reusing the existing `AuthRestApiClient` for OAuth2 token issuance. ## Prerequisites Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. ## Overview The `AuthRestApi` module provided the following storefront endpoints on the legacy Glue stack. They are now served by API Platform: | Endpoint | Operation | Legacy plugin | |---|---|---| | `POST /access-tokens` | Create an access token via the password grant | `AccessTokensResourceRoutePlugin` | | `POST /refresh-tokens` | Exchange a refresh token for a new access token | `RefreshTokensResourceRoutePlugin` | | `DELETE /refresh-tokens/{refreshToken}` | Revoke a single refresh token or all tokens for the current user | `RefreshTokensResourceRoutePlugin` | | `POST /token` | OAuth2 token endpoint supporting `password` and `refresh_token` grant types | `TokenResourceRoutePlugin` | The `/token` endpoint is served by `AuthRestApi` only in the legacy Glue application. In the `GlueStorefrontApiApplication`, `/token` is served by the `OauthApi` module — see [Migrate OauthApi to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.html). ## 1. Update module dependencies ```bash composer require spryker/auth-rest-api:"^X.Y.Z" ``` {% info_block infoBox "Version" %} Use the version that ships the API Platform resources. Check the module changelog for the exact version. {% endinfo_block %} ## 2. Remove route plugins from GlueApplicationDependencyProvider In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: | Plugin to remove | Fully qualified class name | |---|---| | `AccessTokensResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\AccessTokensResourceRoutePlugin` | | `RefreshTokensResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\RefreshTokensResourceRoutePlugin` | | `TokenResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\GlueApplication\TokenResourceRoutePlugin` | Also remove the matching `use` imports at the top of the file. Keep the other `AuthRestApi` plugins registered in the same file — these continue to serve authentication for unmigrated endpoints: - `Spryker\Glue\AuthRestApi\Plugin\FormatAuthenticationErrorResponseHeadersPlugin` - `Spryker\Glue\AuthRestApi\Plugin\GlueApplication\AccessTokenRestRequestValidatorPlugin` - `Spryker\Glue\AuthRestApi\Plugin\GlueApplication\FormattedControllerBeforeActionValidateAccessTokenPlugin` - `Spryker\Glue\AuthRestApi\Plugin\GlueApplication\SimultaneousAuthenticationRestRequestValidatorPlugin` - `Spryker\Glue\AuthRestApi\Plugin\RestUserFinderByAccessTokenPlugin` ## 3. Exclude AuthRestApi from the storefront API application In the `GlueStorefrontApiApplication` (new storefront app), the `/token` endpoint is served by `OauthApi`. To prevent duplicate route definitions, exclude `AuthRestApi` resource schemas from that application's generator. In `config/GlueStorefront/packages/spryker_api_platform.php`, add `AuthRestApi` to the `excludedPathFragments` list: ```php $sprykerApiPlatform->excludedPathFragments([ 'src/Spryker/AuthRestApi/resources/api/', // ...other entries ]); ``` The legacy Glue application continues to discover `AuthRestApi` schemas via `config/Glue/packages/spryker_api_platform.php` — do not exclude `AuthRestApi` there. ## 4. Regenerate transfers and API resources ```bash docker/sdk cli console transfer:generate docker/sdk cli glue api:generate docker/sdk cli glue cache:clear ``` ## Relationship plugin status The `AuthRestApi` module did not register any relationship plugins. No relationship changes are needed.

AI Dev SDK Overview

Thu, 23 Apr 2026 07:22:30 +0000

Experimental module

The AiDev module is experimental and not stable. There is no backward compatibility promise for this module. We welcome your feedback and contributions as we continue to develop and improve this module.

Prerequisites

This module requires ^1.71.0 version of docker/sdk for proper usage. Make sure your development environment is up to date before installing the AiDev module.

This document describes how to integrate and use the AiDev module to connect your Spryker application to AI development tools through the Model Context Protocol (MCP).

Overview

The AiDev module provides an MCP server that enables AI assistants to interact with your Spryker application. It exposes Spryker-specific information through MCP tools and prompts, allowing AI assistants to better understand and work with your codebase.

The module includes:

MCP Server: A console command that runs an MCP server to communicate with AI assistants
Extension Points: Plugin interfaces for adding custom MCP tools and prompts
Built-in Tools: Pre-configured tools for accessing Spryker transfers, interfaces, and OMS information
Prompt Generation: Automatic generation of context-aware prompts from documentation

Console commands

The AiDev module provides the following console commands:

MCP Server Command

The ai-dev:mcp-server command starts an MCP server that allows AI assistants to interact with your Spryker application.

docker/sdk console ai-dev:mcp-server -q

This command:

Starts an MCP server using stdio transport
Registers all configured MCP tool and prompt plugins
Automatically generates prompts if they don’t exist
Listens for requests from AI assistants

Usage: This command is typically configured in AI assistant tools (like Claude Desktop) to enable them to access Spryker-specific information.

Setup Command

The ai-dev:setup command sets up AI tooling for your Spryker project. It generates rules, an agents/context file, and skills — all tailored to the selected AI tool.

docker/sdk console ai-dev:setup

The command automatically detects the AI tool installed in your project and prompts you to confirm or select a different one. It then generates the following for the selected tool:

Rules: Coding conventions and architectural guidelines.
Agents/context file: Project-specific context for AI agents.
Skills: Reusable task-specific AI skill files.

Output modes

The command supports two output modes:

Ready to use: Files are generated directly in the tool-specific directories listed in the table below.
Example: Files are generated in example directories — for example, .claude/rules-example/ instead of .claude/rules/. Rename the directories when ready to use.

Output locations by AI tool

AI tool	Rules directory	Agents/context file	Skills directory
Claude Code	`.claude/rules/`	`CLAUDE.md`	`.claude/skills/`
Windsurf	`.windsurf/rules/`	`.windsurfrules`	`.windsurf/skills/`
GitHub Copilot	`.github/instructions/`	`.github/copilot-instructions.md`	`.github/skills/`
Cursor	`.cursor/rules/`	`AGENTS.md`	`.cursor/skills/`
OpenCode	`.opencode/rules/`	`AGENTS.md`	`.agents/skills/`
Codex CLI	Not supported — see below	`AGENTS.md`	`.agents/skills/`

Codex CLI does not have a native rules format. When you select it, the command offers to generate rules in another tool’s format instead and places them in that tool’s rules directory.

GitHub Copilot and Docker sync

If you use Docker sync, the /.git* entry in .dockersyncignore also excludes the .github folder, which prevents Copilot-generated files from being available inside the container. To fix this, add the following line to .dockersyncignore after the /.git* entry:

!/.github

Usage: Run this command once when setting up AI tooling for a project.

Generate Prompts Command

The ai-dev:generate-prompts command generates MCP prompts from a configured Prompt Library.

docker/sdk console ai-dev:generate-prompts

This command:

Fetches prompts
Generates PHP-based prompt classes
Stores generated prompts in the configured directory

Usage: Use this command when you need to regenerate prompts from updated documentation or when initializing the module for the first time.

Extension points

The AiDev module provides plugin interfaces for extending the MCP server with custom functionality:

AiDevMcpToolPluginInterface

Implement this interface to add custom MCP tools that AI assistants can use to query or interact with your application.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface

Integration: Register your tool plugins in AiDevDependencyProvider::getMcpToolPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpToolPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface>
     */
    protected function getMcpToolPlugins(): array
    {
        return array_merge(parent::getMcpToolPlugins(), [
            new CustomAiDevMcpToolPlugin(),
        ]);
    }
}

AiDevMcpPromptPluginInterface

Implement this interface to add custom MCP prompts that provide context or instructions to AI assistants.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpPromptPluginInterface

Integration: Register your prompt plugins in AiDevDependencyProvider::getMcpPromptPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpPromptPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpPromptPluginInterface>
     */
    protected function getMcpPromptPlugins(): array
    {
        return [
            new CustomAiDevMcpPromptPlugin(),
        ];
    }
}

Configuration

The AiDev module can be configured through the AiDevConfig class. Key configuration options include:

Prompt Directory: Set the directory where generated prompts are stored

Refer to the module’s configuration class for available options and their default values.

Debugging the MCP server

Before connecting your MCP server to AI assistants, you can test and debug it using the MCP Inspector tool. The inspector provides a web interface to interact with your MCP server, test tools, and verify that everything works correctly.

Using the MCP Inspector

Navigate to your Spryker project directory and run:

npx @modelcontextprotocol/inspector docker/sdk console ai-dev:mcp-server -q

This command will:

Start the MCP Inspector in your browser
Connect to your local MCP server
Display all available tools and prompts
Allow you to test tool calls interactively

With Xdebug

npx @modelcontextprotocol/inspector docker/sdk cli -x console ai-dev:mcp-server

Node.js required

The MCP Inspector requires Node.js to be installed on your system. The npx command will automatically download and run the inspector tool without requiring a global installation.

AI Dev SDK

Thu, 23 Apr 2026 07:15:42 +0000

Warning

Before you use AI-related tools, consult your legal department.

Overview

When you use AI tools to write code, they rely on general patterns, which leads to mistakes and requires you to repeatedly explain your project structure.

The AI Dev SDK provides an MCP server, which is a console command that your AI tool runs in your project’s Docker container and helps it to increase Spryker-context awareness. MCP (Model Context Protocol) is a standard protocol that lets AI tools request specific information from external sources, similar to how a browser requests data from an API.

How it works

After you install the SDK, add a simple configuration to your AI tool. When your Spryker project is running, your AI tool can access Spryker-specific information and prompts through the MCP server.

Result

AI generates better code faster and with fewer errors. You spend less time correcting mistakes and explaining Spryker concepts.

Key capabilities

Faster Spryker-specific answers

AI can search Spryker documentation instead of requiring you to explain basic concepts or guessing how features work.

Smarter code generation

AI can look up your actual transfer objects, module dependencies, and interface methods so that the generated code matches your project structure instead of relying on assumptions.

OMS debugging made easy

AI can analyze your OMS flows to find possible next states, transitions, conditions, and timeouts for any order or state. This capability is especially helpful when you work with complex OMS schemas. You no longer need to manually follow arrows in large diagrams.

Working with complex data imports

AI can analyze, modify, and transform multi-column CSV files correctly. This task normally requires significant manual effort.

The SDK includes access to the Spryker prompt library, and you can add your own project-specific prompts. This means your team can reuse effective prompts instead of everyone writing their own.

Database queries

AI can execute read-only database queries to inspect data when debugging issues.

Extensible for your project

You can extend the MCP server by creating custom plugins (to add new tools) and custom prompts.

Install the AI Dev SDK

Prerequisites

Ensure that you have a Spryker project with Composer installed.

Installation steps

Require the package as a development dependency:
```
composer require spryker-sdk/ai-dev --dev
```
Generate the transfer objects:
```
console transfer:generate
```

use SprykerSdk\Zed\AiDev\Communication\Console\AiToolSetupConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\GeneratePromptsConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\McpServerConsole;

protected function getConsoleCommands(Container $container): array
{
    ...
    if (class_exists(McpServerConsole::class)) {
        $commands[] = new McpServerConsole();
    }

    if (class_exists(GenerateSkillsConsole::class)) {
        $commands[] = new AiToolSetupConsole();
    }

    if (class_exists(GeneratePromptsConsole::class)) {
        $commands[] = new GeneratePromptsConsole();
    }
    ...
}

Connect the AI Dev SDK to your AI agent. For detailed configuration instructions, see Configure the AiDev MCP server.

Next steps

Configure the AiDev MCP server - Set up the connection to your AI tool
AI Dev SDK Overview - Learn more about the AI Dev SDK features and capabilities

Test console commands

Wed, 22 Apr 2026 12:15:12 +0000

Spryker supports several [test helpers](/docs/dg/dev/guidelines/testing-guidelines/test-helpers/test-helpers.html) to assist you in testing your project. This article provides details of how to test console commands with ConsoleHelper. To test console commands, do the following: 1. Add `\SprykerTest\Zed\Console\Helper\ConsoleHelper` to the `codeception.yml` file: ```yml suites: Communication: path: Communication actor: {ModuleName}CommunnicationTester modules: enabled: - \SprykerTest\Zed\Console\Helper\ConsoleHelper - ... ``` For more information about the `codeception.yml` file, see [Test framework](/docs/dg/dev/guidelines/testing-guidelines/test-framework.html). 2. Create the test directory `tests/PyzTests/Zed/FooModule/Communication/Plugin/Console/`, if it's not available yet. 3. Add the test class: ```php tester->getConsoleTester($command); $input = [ MyConsoleCommand::ARGUMENT_FOO => 'foo-argument', '--' . MyConsoleCommand::OPTION_BAR => 'bar-option', ]; $commandTester->execute($input); $this->assertSame(MyConsoleCommand::CODE_SUCCESS, $commandTester->getStatusCode()); // When you expect some output from the console command you can assert it with: $this->assertStringContainsString('My console command output.', $commandTester->getDisplay()); } ``` That's it. You are all set to test the console commands.

New Relic transactions grouping by queue names

Wed, 22 Apr 2026 12:15:12 +0000

By default, the `spryker/monitoring` module groups all New Relic transactions generated from a console command by the command's name. For example, `ooms:check-timeout`. This strategy works in most cases, and you can still query the data from a needed queue using [NRQL](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions/). But you might want to override this behavior. For example, you run multiple commands like `queue:task:start publish.product_abstract` and `queue:task:start sync.storage.url`. With the default naming strategy, all the calls of the command will be grouped together by `queue:task:start`. Transaction data is aggregated under the same name for all types of queue processors. In New Relic dashboard, this looks as follows: ![Transactions under the same name](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/guidelines/performance-guidelines/elastic-computing/enable-queue-task-flow-in-new-relic.md/transactions-under-the-same-name.png) ## Group transactions by queue name As queue name usually comes as the first argument of a command, to enable grouping by names, you need to need to enable grouping by the first argument as follows: 1. Integrate the `spryker/monitoring` module. 2. Provide an advanced extendable infrastructure for [New relic monitoring transaction](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/) naming strategies. This lets you implement, configure, and override the default transaction naming behavior. 3. Implement the strategy that enables configured console commands to apply naming that groups transaction by command name and first argument. 4. Enable the new strategy for `queue:task:start` on the project level. As a result, the transactions are displayed as follows: ![Aggregation of transactions](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/guidelines/performance-guidelines/elastic-computing/enable-queue-task-flow-in-new-relic.md/aggregation-of-transactions.png) ## Integrate New Relic transactions grouping by queue names For instructions, see [Integrate New Relic transactions grouping by queue names](/docs/dg/dev/integrate-and-configure/integrate-elastic-computing.html#integrate-new-relic-monitoring). ## Implementation details ![New Relic transaction grouping by name implementation details](https://confluence-connect.gliffy.net/embed/image/59eaf32b-df1e-4fb9-a5e7-64b77c8ab870.png?utm_medium=live&utm_source=custom)

E2E Testing with Cypress

Wed, 22 Apr 2026 12:15:12 +0000

Cypress is an end-to-end testing framework that provides a modern approach to testing web applications. Spryker provides a Cypress boilerplate project with pre-configured setup, best practices, and examples for testing Spryker-based applications.

Cypress boilerplate

For comprehensive information on setting up and using Cypress with Spryker, refer to the cypress-boilerplate repository.

The boilerplate includes:

Pre-configured Cypress setup optimized for Spryker projects
Example test cases and patterns
Documentation and best practices
Integration guides

The boilerplate does NOT include:

Complete test coverage - you should add and adjust example tests to fit your project
Correct locators - the locators in the boilerplace are based on Spryker demo shops, adjust the locators in accordance with your project

Internal Cypress tests

Cypress tests are used by Spryker for internal testing of the core Spryker features as well. You should remove the mentions of cypress-tests from composer.json. You can re-use and customize these tests for your project, however, Spryker does not guarantee these tests will work on your project, if you keep them. Spryker recommends you use the boilerplate instead.

Resources

Repository: spryker-projects/cypress-boilerplate
Wiki: cypress-boilerplate Wiki

Architecture

Wed, 22 Apr 2026 12:15:12 +0000

One of the main tasks of a commerce platform is the possibility to customize, extend, and integrate it with external services, such as payment providers, order processors, and the like. To provide a clear path for the Spryker Commerce OS development and extension, its architecture is based on strict modularity and separation. These principles are strongly supported by the OS architecture. This architecture guide helps you understand how they are implemented on different levels.

In this section, you can learn the following topics:

The Spryker architecture and concepts.
What technologies we use.
What applications the Spryker Commerce OS is composed of.
How we enable the development of high-performance applications and their scalability.

Also, this guide is especially useful for developers, architects, and integrators dealing with Spryker Cloud Commerce OS.

Architecture as Code

Wed, 22 Apr 2026 12:15:12 +0000

Well-documented project architecture enables faster internal and external onboarding, passes audits cleanly and aligns teams on requirements. Without it, your system becomes a black box that only the original developers understand.

Architecture as Code treats architecture documentation like code, similarly to the Infrastructure-as-Code concept. Instead of storing architecture in binary formats or external tools (Word, PowerPoint, Visio, Confluence) that become outdated quickly, you store and maintain architecture documentation in version control alongside your implementation.

Spryker ships the architecture/ folder with a complete Architecture as Code structure with its demoshop codebase. You can refer to architecture/README.md that describes how to work with it. Below, you find all the general information about the structure and principles. We go into the details of each aspect to help you understand and extend this architecture documentation in your project.

Existing projects

If your project is based on a Spryker release before 202602.0, refer to the Spryker B2B Demo Marketplace master branch source code to see how the Architecture as Code structure is implemented and to copy the “architecture/” folder into your project.

Why Architecture as Code

Traditional architecture documentation suffers from several challenges:

Documentation drift - Binary formats stored separately from code become outdated quickly
Version control gaps - Specialized tools do not integrate with Git workflows
Collaboration barriers - Requires specialized software and binary file merging
AI limitations - AI tools understand code and Markdown effectively but struggle with proprietary formats and binary documents

Architecture as Code solves these problems:

Version controlled - Store in Git alongside implementation. Track every change with full history.
AI-ready - Markdown and diagrams-as-code enable AI assistance, automated validation, and intelligent analysis.
Standard formats - Use industry standards (arc42, C4, ADRs, Mermaid) that external teams understand immediately.
Collaborative - Review through pull requests. No special tools required — only a text editor.
Living documentation - Update during development, not after. Documentation evolves with your system.

Core Principles

Standards over invention - Use industry-proven formats and standards (arc42, C4, ADRs, Mermaid) instead of custom documentation.

Minimal but sufficient - Start simple. Prioritize clarity and expansion over completeness on day one.

Architecture is code - Write in plain text, store in Git, review through pull requests, deploy automatically.

Concepts and Choices

arc42

arc42 is a proven template for architecture documentation used globally across industries.

Why arc42 fits Spryker projects:

Spryker projects vary dramatically in complexity — from simple B2C shops to complex B2B marketplaces with extensive integrations and order management systems. arc42 is flexible enough to cover architecture of any complexity and scales as your Spryker implementation grows. You can start simple with minimal sections and expand as your architecture requires more detail.

The template includes 12 sections (described below) covering all architectural aspects. Section 4 (Solution Designs) provides RFC-style exploration templates. Section 9 (Architecture Decisions) uses ADRs to document decisions with context and consequences. This workflow — explore with Solution Designs, then document decisions with ADRs — ensures thoughtful architecture evolution.

C4 Model

C4 Model provides a hierarchical approach to system visualization with four levels of abstraction.

Why C4 fits Spryker architecture:

Spryker architecture unfolds naturally through C4 layers — start with the system context, zoom into containers (Yves, Zed, Client, databases, services), then dive deeper into layers and components as needed. This progressive detail matches how Spryker complexity reveals itself. The entire Spryker feature set can be shown using this unfolding approach.

Flexibility advantage:

You control the depth. Start at C1 (context) and continue only as deep as your documentation needs require. Given limited architect time, this flexibility is essential — stop at the level appropriate for your stakeholders and complexity.

Mermaid and PlantUML

Mermaid - Our primary choice for diagramming-as-code:

Renders automatically in GitHub and GitLab, and can be rendered via plugins in popular IDEs
No proprietary tools required
Covers 90% of diagram needs: flowcharts, sequences, C4 diagrams
Online editor at mermaid.live for convenient editing and better visualization than most IDEs

PlantUML - For precision when needed:

Essential for Entity-Relationship Diagrams where field-level precision matters
Online editor at plantuml.com for live editing and preview

What Comes Out of the Box

We provide templates with clear structure and minimal context, plus examples of the most common diagram types (C4, data flow, integration, sequence) and documentation patterns (ADRs, Solution Designs). AI tools work most efficiently when they see the methodology (like arc42), understand the structure, and have examples to follow. This approach enables you to generate architecture documentation much faster with AI assistance.

Templates provide examples and structural guidance — you should adapt content to your project’s context. You do not need to implement all sections immediately; remove or keep unused sections based on your documentation strategy.

Folder Structure

architecture/
├── 01-introduction-and-goals.md           # Requirements, quality goals, stakeholders
├── 02-constraints.md                      # Technical, organizational constraints
├── 03-system-scope-and-context.md         # System boundaries, external interfaces
│                                          # Includes: External systems and integration tables
├── 04-solution-designs/                   # RFC-style exploration documents
│   ├── README.md                          # Workflow explanation
│   └── sd-000-template.md                 # Solution design template
├── 05-building-block-view.md              # System decomposition
├── 06-runtime-view.md                     # Behavior and interactions
├── 07-deployment-view.md                  # Infrastructure topology
├── 08-crosscutting-concepts.md            # Patterns spanning components
├── 09-architecture-decisions/             # Architecture decision records
│   ├── README.md                          # ADR workflow and sources
│   └── adr-000-template.md                # ADR template
├── 10-quality-requirements.md             # Performance, scalability, testing
│                                          # Includes: Volume planning, testing strategy
├── 11-risks-and-technical-debt.md         # Known issues and mitigation
├── 12-glossary.md                         # Domain terminology
├── diagrams/
│   ├── c4/
│   │   ├── c1-system-context.mmd          # System context diagram
│   │   ├── c2-spryker-container.mmd       # Container diagram
│   │   └── c3-component-diagram.mmd       # Component diagram
│   ├── data-flow/
│   │   └── product-price-data-flow.mmd    # Price data flow example
│   ├── integration/
│   │   └── product-price-integration.mmd  # Integration overview with protocols
│   ├── sequence/
│   │   ├── api-payment.mmd                # Payment flow
│   │   ├── publish-sync.mmd               # Publish and Sync process
│   │   └── punchout-greenwing-integration.mmd  # PunchOut example
│   └── erd/                               # Entity-relationship diagrams (PlantUML)
└── README.md                              # Quick start and overview

Diagram Organization and Best Practices

You have two approaches to managing diagrams. Choose based on your documentation use case.

Approach 1: Inline Diagrams

Write diagram code directly in markdown using code fences:

>flowchart LR
    A --> B

Pros: Diagrams are visible immediately; self-contained

Cons: Increases file size; duplicates code if reused

Approach 2: External Diagram Files

Store diagram code in /diagrams/ folder and reference via links:

[C1 System Context](diagrams/c4/c1-system-context.mmd)

Pros: Single source-of-truth; cleaner markdown; scalable

Cons: Requires clicking to view (less immediate)

Choosing Your Approach

This template uses Approach 2 for scalability and maintainability, but projects can mix both — use external files for core views, inline for one-off diagrams.

Universal Color Scheme:

All diagrams use colors optimized for both light and dark modes:

Orange #E67E22 - Communication layer
Blue #2980B9 - Backend services, APIs
Green #27AE60 - Web apps, external systems
Purple #9B59B6 - Storage (databases, caches)
Gray #95A5A6 - Infrastructure

Templates and Guidelines

Solution Design Template (04-solution-designs/sd-000-template.md):

Metadata section (status, date, stakeholders)
Problem statement
Goals and requirements
Proposed solution with diagrams
Implementation plan
Trade-offs and alternatives

ADR Template (09-architecture-decisions/adr-000-template.md):

Standard ADR structure
Status tracking
Context, decision, consequences
Links to related decisions

Volume Planning Table (Section 10):

Pre-structured table for capacity planning covering:

Catalog entities (products, categories, prices)
Cart constraints
User load projections
B2B customers structure
Marketplace metrics
Internationalization requirements
Orders and infrastructure

Getting Help

Resources

arc42 Documentation: https://arc42.org/
C4 Model Guide: https://c4model.com/
Mermaid Syntax: https://mermaid.js.org/
ADR Guidelines: https://adr.github.io/

Common Questions

Q: Do I need to fill in every arc42 section?

A: No. Fill in what is relevant for your project. Some sections may remain minimal.

Q: Can I add custom sections?

A: First, check all 12 arc42 sections — the standard format covers most architectural concerns. If no existing section fits your content, you can add a custom section. Ensure the section purpose is clear and describe it in the README.md file.

Q: How detailed should diagrams be?

A: For C4 diagrams, follow the levels: Context (high-level), Container (more detail), Component (detailed). For other diagram types (data flow, integration, sequence), follow industry standards for that specific notation.

Q: When should I create an ADR vs Solution Design?

A: Use Solution Design for exploration. Use ADR for documenting the final decision.

Q: Can I use different diagram notations?

A: Yes. The choice is yours — we do not limit you to Mermaid or PlantUML. Ensure your notation follows the core principles: viewable by people, understandable by AI tools, and ideally diagrams-as-code (text-based format in version control).

Q: Will diagrams-as-code replace whiteboards and visual editing tools?

A: No. The art of creating and drawing diagrams — whether on whiteboards, visual tools, or pen and paper — remains valuable. Diagrams-as-code is for documenting what you have drawn and decided. Use whatever tools help you think and collaborate, then capture the final result as code for version control and documentation.

Q: Can I use images as diagrams instead of diagrams-as-code?

A: Yes, it is better to have image diagrams than no diagrams at all, but understand the trade-off. Hand-drawn or visually edited diagrams often look more polished than generated ones. However, images are not as understandable or generable by AI (at least currently) and lack version control benefits. You can use both: include beautiful images for presentations and stakeholder communication, alongside diagrams-as-code for AI assistance and documentation processes.

AI workflow orchestration with state machines

Wed, 22 Apr 2026 12:15:12 +0000

This guide shows you how to build multi-step, multi-agent AI workflows using Spryker state machines. By combining state machines with the AiFoundation module, you can orchestrate complex AI processes where agents execute tasks, make decisions based on results, and trigger subsequent steps.

Overview

Spryker state machines provide a powerful framework for orchestrating AI workflows:

States: Represent stages in your workflow (for example, “analysis_done”, “awaiting_review”)
Events: Trigger state transitions (for example, “analyze_agent” executes an AI call)
Commands: Execute AI operations, tool calls, or business logic
Conditions: Evaluate workflow item data to decide the next state (for example, “is_successful?”)
Context data: Passed through the workflow to accumulate results and drive decisions

This creates a directed graph where conditions act as edges determining the next state based on AI-generated outputs.

Key concepts

Context data: A key-value array that flows through the state machine, allowing commands to read input and write results for conditions to evaluate
Structured response: AI responses converted to structured data, enabling deterministic decision-making
Command plugins: Execute AI calls and update context with results
Condition plugins: Evaluate context data to determine workflow progression
Process name: Links XML definition to PHP configuration and state machine execution

Create a workflow process example

1. Define the state machine XML

Example: IntelligentTask01

Create config/Zed/StateMachine/AiWorkflow/IntelligentTask01.xml:

<?xml version="1.0"?>
<statemachine
    xmlns="spryker:state-machine-01"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="spryker:state-machine-01 http://static.spryker.com/state-machine-01.xsd">

    <process name="IntelligentTask01" main="true">
        <states>
            <state name="new"/>
            <state name="analysis done"/>
            <state name="analysis successful"/>
            <state name="analysis failed"/>
        </states>

        <events>
            <!-- onEnter="true" triggers the command automatically when entering source state -->
            <event name="analyze agent" onEnter="true" command="OryxAgent/Analyze"/>
            <event name="pass" onEnter="true"/>
            <event name="restart" manual="true"/>
        </events>

        <transitions>
            <!-- Initial transition: execute command on entry -->
            <transition happy="true">
                <source>new</source>
                <target>analysis done</target>
                <event>analyze agent</event>
            </transition>

            <!-- Happy path: condition passes -->
            <transition happy="true" condition="OryxAgent/Success">
                <source>analysis done</source>
                <target>analysis successful</target>
                <event>pass</event>
            </transition>

            <!-- Unhappy path: condition fails (no condition = default) -->
            <transition>
                <source>analysis done</source>
                <target>analysis failed</target>
                <event>pass</event>
            </transition>

            <!-- Recovery: manual restart from failed state -->
            <transition>
                <source>analysis failed</source>
                <target>new</target>
                <event>restart</event>
            </transition>
        </transitions>
    </process>
</statemachine>

2. Create command plugins

Command plugin example: Analyze data with Oryx Agent

<?php

use Generated\Shared\Transfer\AiWorkflowItemCollectionRequestTransfer;
use Generated\Shared\Transfer\StateMachineItemTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Spryker\Zed\StateMachine\Dependency\Plugin\CommandPluginInterface;

class OryxAgentAnalyzeCommandPlugin extends AbstractPlugin implements CommandPluginInterface
{
    public function run(StateMachineItemTransfer $stateMachineItemTransfer): void
    {
        $aiWorkflowItemTransfer = $this->loadWorkflowItem($stateMachineItemTransfer);

        $this->executeAnalysis($aiWorkflowItemTransfer);

        $request = (new AiWorkflowItemCollectionRequestTransfer())
            ->setIsTransactional(true)
            ->addAiWorkflowItem($aiWorkflowItemTransfer);

        $this->getAiFoundationFacade()->updateAiWorkflowItemCollection($request);
    }

    protected function loadWorkflowItem(
        StateMachineItemTransfer $stateMachineItemTransfer
    ): AiWorkflowItemTransfer {
        $idAiWorkflowItem = $stateMachineItemTransfer->getIdentifierOrFail();

        $aiWorkflowItemConditionsTransfer = (new AiWorkflowItemConditionsTransfer())
            ->addAiWorkflowItemId($idAiWorkflowItem);

        $aiWorkflowItemCriteriaTransfer = (new AiWorkflowItemCriteriaTransfer())
            ->setAiWorkflowItemConditions($aiWorkflowItemConditionsTransfer);

        $aiWorkflowItemCollection = $this->getAiFoundationFacade()
            ->getAiWorkflowItemCollection($aiWorkflowItemCriteriaTransfer);

        return $aiWorkflowItemCollection->getAiWorkflowItems()->offsetGet(0);
    }

    protected function executeAnalysis(AiWorkflowItemTransfer $aiWorkflowItemTransfer): void
    {
        $contextData = $aiWorkflowItemTransfer->getContextData();
        $promptMessage = $contextData['prompt'] ?? 'Please analyze this data.';

        $promptRequestTransfer = (new PromptRequestTransfer())
            ->setPromptMessage($promptMessage);

        $promptResponseTransfer = $this->getAiFoundationFacade()->prompt($promptRequestTransfer);

        $contextData['analysis_result'] = $promptResponseTransfer->getMessage();
        $contextData['success'] = $promptResponseTransfer->getIsSuccessful();
        $contextData['analyzed_at'] = time();

        $aiWorkflowItemTransfer->setContextData($contextData);
    }
}

3. Create condition plugins

Condition plugin example: Check Oryx Agent success flag

<?php

namespace Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Condition;

use Generated\Shared\Transfer\StateMachineItemTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Spryker\Zed\StateMachine\Dependency\Plugin\ConditionPluginInterface;

class OryxAgentSuccessConditionPlugin extends AbstractPlugin implements ConditionPluginInterface
{
    public function check(StateMachineItemTransfer $stateMachineItemTransfer): bool
    {
        // Load workflow item
        $aiWorkflowItemTransfer = $this->loadWorkflowItem($stateMachineItemTransfer);

        // Read success flag set by command
        $contextData = $aiWorkflowItemTransfer->getContextData();
        return $contextData['success'] ?? false;
    }
}

4. Register plugins in AiFoundation dependency provider

<?php

namespace Pyz\Zed\AiFoundation;

use Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Command\OryxAgentAnalyzeCommandPlugin;
use Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Condition\OryxAgentSuccessConditionPlugin;
use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    protected function getAiWorkflowCommandPlugins(): array
    {
        return [
            'OryxAgent/Analyze' => new OryxAgentAnalyzeCommandPlugin(),
        ];
    }

    protected function getAiWorkflowConditionPlugins(): array
    {
        return [
            'OryxAgent/Success' => new OryxAgentSuccessConditionPlugin(),
        ];
    }
}

5. Configure active processes

Create or update src/Pyz/Zed/AiFoundation/AiFoundationConfig.php:

<?php

namespace Pyz\Zed\AiFoundation;

use Spryker\Zed\AiFoundation\AiFoundationConfig as SprykerAiFoundationConfig;

class AiFoundationConfig extends SprykerAiFoundationConfig
{
    public function getAiWorkflowActiveProcesses(): array
    {
        return [
            'IntelligentTask01',
        ];
    }

    protected function getAiWorkflowInitialStateMapForProcess(): array
    {
        return [
            'IntelligentTask01' => 'new',
        ];
    }
}

6. Enable state machine handler

Update src/Pyz/Zed/StateMachine/StateMachineDependencyProvider.php:

<?php

use Pyz\Zed\StateMachine\Communication\Plugin\StateMachine\AiWorkflowStateMachineHandlerPlugin;

protected function getStateMachineHandlerPlugins(Container $container): array
{
    return [
        new AiWorkflowStateMachineHandlerPlugin(),
    ];
}

7. Set up cron jobs to process state machine events

Update config/Zed/cronjobs/jenkins.php:

$jobs[] = [
    'name' => 'check-ai-workflow-conditions',
    'command' => '$PHP_BIN vendor/bin/console state-machine:check-condition AiWorkflow',
    'schedule' => '* * * * *',
    'enable' => true,
];

$jobs[] = [
    'name' => 'check-ai-workflow-timeouts',
    'command' => '$PHP_BIN vendor/bin/console state-machine:check-timeout AiWorkflow',
    'schedule' => '* * * * *',
    'enable' => true,
];

$jobs[] = [
    'name' => 'clear-state-machine-locks',
    'command' => '$PHP_BIN vendor/bin/console state-machine:clear-locks',
    'schedule' => '0 6 * * *',
    'enable' => true,
];

8. Trigger a workflow with state machine

To start a workflow, create a workflow item with initial context data and trigger the state machine for it.

Create a workflow item and trigger the state machine:

<?php

use Generated\Shared\Transfer\AiWorkflowItemCollectionRequestTransfer;
use Generated\Shared\Transfer\AiWorkflowItemTransfer;
use Generated\Shared\Transfer\StateMachineProcessTransfer;
use Spryker\Shared\AiFoundation\AiFoundationConstants;

// 1. Create a workflow item with initial context data
$request = (new AiWorkflowItemCollectionRequestTransfer())
    ->setIsTransactional(true)
    ->addAiWorkflowItem(
        (new AiWorkflowItemTransfer())->setContextData([
            'prompt' => 'Analyze this data.',
            'status' => 'initialized',
        ]),
    );

$response = $this->aiFoundationFacade->createAiWorkflowItemCollection($request);
$workflowItem = $response->getAiWorkflowItems()->offsetGet(0);

// 2. Trigger the state machine for the newly created item
$processTransfer = (new StateMachineProcessTransfer())
    ->setProcessName('IntelligentTask01')
    ->setStateMachineName(AiFoundationConstants::AI_WORKFLOW_STATE_MACHINE_NAME);

$this->stateMachineFacade->triggerForNewStateMachineItem($processTransfer, $workflowItem->getIdAiWorkflowItem());

Trigger a manual event:

<?php

use Generated\Shared\Transfer\StateMachineItemTransfer;

$stateMachineItemTransfer = (new StateMachineItemTransfer())
    ->setIdentifier($workflowItem->getIdAiWorkflowItem())
    ->setStateMachineName(AiFoundationConstants::AI_WORKFLOW_STATE_MACHINE_NAME)
    ->setProcessName('IntelligentTask01');

$this->stateMachineFacade->triggerEvent('restart', $stateMachineItemTransfer);

Multi-agent orchestration patterns

There are many possible patterns for multi-agent orchestration. The following are a couple of examples implemented using the Spryker AiWorkflow state machine.

Multi-agent routing workflow

Multi-agent supervision workflow

To enable navigation to the Workflows in the Zed admin panel, add navigation items to your config/Zed/navigation.xml file.

Update config/Zed/navigation.xml to include the Workflows menu:

<config>
    <ai-foundation>
        <label>Intelligence</label>
        <title>Intelligence</title>
        <icon>network_intel_node</icon>
        <pages>
            <ai-workflow>
                <label>Workflows</label>
                <title>Workflows</title>
                <bundle>ai-foundation</bundle>
                <controller>ai-workflow</controller>
                <action>index</action>
            </ai-workflow>
        </pages>
    </ai-foundation>
</config>

This navigation configuration:

Adds an Intelligence menu item in the Zed admin panel
Includes a Workflows submenu to access the workflows monitoring interface
Sets the icon and labels for improved user experience
Defines URLs to route to the workflows overview and detail pages

Monitoring

You can monitor AI workflows in the Spryker Zed administration panel. The monitoring interface provides visibility into workflow execution, state transitions, and context data.

View workflow details

To view detailed information about a specific workflow item, click the View button in the actions column. The detail page displays the following information:

Current State: Shows the workflow item ID, process name, and current state
Context Data: Displays the JSON context data that flows through the workflow, including input data and results from executed commands
State History: A table showing all states the workflow item has passed through and the timestamps when each state was entered
Manual Events: If manual events are available for the current state, you can trigger them directly from the admin panel (useful for testing or recovery scenarios)
Process Graph: A visual representation of the state machine process with the current state highlighted

Trigger manual events

If a workflow is waiting for a manual event or you need to change its course, you can trigger manual events from the workflow detail page. Manual events appear as buttons under the Manual Events section. Only events that are valid for the current state are displayed.

Best practices

Keep context simple: Store only the data that conditions need to evaluate the next step and that subsequent commands need to process
Use structured responses: Convert AI responses to structured data before storing in context
Name explicitly: Use descriptive command and condition names matching the process name
Document context schema: Define what keys each command and condition expects in context data

Spryker Documentation

Migrate OauthApi to API Platform

Migrate AuthRestApi to API Platform

AI Dev SDK Overview

Overview

Console commands

MCP Server Command

Setup Command

Generate Prompts Command

Extension points

AiDevMcpToolPluginInterface

AiDevMcpPromptPluginInterface

Configuration

Debugging the MCP server

Using the MCP Inspector

AI Dev SDK

Overview

How it works

Result

Key capabilities

Faster Spryker-specific answers

Smarter code generation

OMS debugging made easy

Working with complex data imports

Sharing prompts across your team

Database queries

Extensible for your project

Install the AI Dev SDK

Prerequisites

Installation steps

Next steps

Test console commands

New Relic transactions grouping by queue names

E2E Testing with Cypress

Cypress boilerplate

Internal Cypress tests

Resources

Architecture

Architecture as Code

Why Architecture as Code

Core Principles

Concepts and Choices

arc42

C4 Model

Mermaid and PlantUML

What Comes Out of the Box

Folder Structure

Diagram Organization and Best Practices

Templates and Guidelines

Getting Help

Resources

Common Questions

AI workflow orchestration with state machines

Overview

Key concepts

Create a workflow process example

1. Define the state machine XML

2. Create command plugins

3. Create condition plugins

4. Register plugins in AiFoundation dependency provider

5. Configure active processes

6. Enable state machine handler

7. Set up cron jobs to process state machine events

8. Trigger a workflow with state machine

Multi-agent orchestration patterns

Multi-agent routing workflow

Multi-agent supervision workflow

Navigation configuration

Add navigation XML

Monitoring

View workflow details

Trigger manual events

Best practices