# adobe/adobe-commerce-samples architecture

> Architecture diagram of the GitHub repository adobe/adobe-commerce-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adobe/adobe-commerce-samples
- Repository: https://github.com/adobe/adobe-commerce-samples

## Overview

##### Project Type and Purpose
- This is a “sample-code” monorepo for Adobe Commerce extensibility.
- It is not a single running application but a set of independent extension examples:
- admin-ui-sdk (front-end and serverless actions for Admin UI)
- api-mesh (GraphQL mesh proxies for Commerce and external APIs)
- events (serverless event-triggered actions)
- webhooks (serverless webhook handlers)
- starter-kit (end-to-end sample projects combining events, ingestion, scripts)

##### File-Structure Analysis
- Top-level directories each represent a “sample category.”
- Under admin-ui-sdk are multiple “extension packages.” Each package has:
- app.config.yaml & extension-manifest.json (deployment metadata)
- actions/commerce-backend-ui-1 (serverless registration code)
- web-src (React UI code loaded into Admin UI)
- api-mesh modules contain meshConfig.json, GraphQL schemas and resolvers, sample.env for environment variables.
- events and webhooks subdirectories follow a similar pattern:
- actions/<type> containing registration/config and index.js.
- tests or jest.setup.js for unit tests.
- starter-kit is a self-contained sample project:
- actions (customer, order, external, email, stock, etc.)
- app.config.yaml, hooks/, scripts/, utils/, test/

##### README Insights
- The repo is educational, meant to teach Adobe Commerce extension patterns.
- No single architecture is “running” here; instead there are dozens of small runtime modules deployable to Adobe I/O Runtime (Apache OpenWhisk).

a. Main Components
- Developer Workstation (AIO CLI & Git)
- Adobe I/O Runtime (serverless environment)
- Adobe Commerce Admin UI (host for web-src bundles)
- API Mesh Gateway (GraphQL proxy layer)
- External Services (e.g., third-party APIs, Adobe I/O Events)
b. Relationships and Data Flows
1. Developer uses AIO CLI to deploy each sample to Adobe I/O Runtime and register extension manifest with Commerce.
2. Admin UI loads web-src bundles (React UI) per extension-manifest.json.
3. UI code invokes serverless “actions” (commerce-backend-ui-1) via Adobe I/O Runtime endpoints.
4. Actions either call Commerce REST/GraphQL APIs or forward data to the API Mesh.
5. API Mesh merges Commerce GraphQL with external APIs and returns unified responses.
6. Event-triggered and webhook modules subscribe to Commerce event bus or webhook endpoints; they run actions on triggers.
7. starter-kit scripts and on-deploy hooks configure event subscriptions and back-office providers.
c. Architectural Patterns
- Micro-frontends: each admin-ui-sdk package is a small React app loaded at specific UI extension points.
- Serverless “actions”: discrete OpenWhisk functions registered with Adobe Commerce event bus.
- API Gateway / GraphQL Mesh: decouples client from multiple REST/GraphQL back-ends.
- Event-driven architecture: commerce events → event actions or webhook actions.
d. Key Technologies
- React (web-src)
- Node.js serverless actions
- Adobe I/O Runtime (OpenWhisk)
- GraphQL Mesh (api-mesh)
- YAML configs (app.config.yaml, meshConfig.json)
- AIO CLI (deployment)

##### Elements
- CLI → I/O Runtime (Deploy)
- Admin UI → web-src bundles
- UI → Serverless Actions
- Actions → Commerce APIs / API Mesh
- Event Source → Event Actions
- Blue for front-end (React)
- Green for serverless actions
- Orange for API Mesh components
- Gray for external services/config

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global Entities
    Developer["Developer Workstation<br>(AIO CLI & Git)"]:::developer
    IORuntime["Adobe I/O Runtime<br>(Serverless Env)"]:::runtime
    AdminUI["Adobe Commerce Admin UI"]:::ui
    APIMeshGateway["API Mesh Gateway"]:::apimesh
    ExternalServices["External Services<br>(3rd Party APIs,<br>Adobe I/O Events)"]:::external
    EventBus["Commerce Event Bus / Webhook Endpoints"]:::external

    %% Admin-UI-SDK Samples
    subgraph "admin-ui-sdk/*" 
        direction TB
        BannerMeta["app.config.yaml &<br>extension-manifest.json"]:::config
        RegCode["Serverless Action Registration"]:::actions
        WebSRC["React UI Bundle"]:::frontend
    end

    %% API-Mesh Modules
    subgraph "api-mesh/*"
        direction TB
        MeshConfig["meshConfig.json"]:::config
        Schemas["GraphQL Schemas/Queries"]:::apimesh
        Resolvers["Custom Resolvers"]:::apimesh
    end

    %% Event-Triggered Actions
    subgraph "events/*"
        direction TB
        EventMeta["app.config.yaml"]:::config
        EventHandler["Event Action Handler"]:::actions
    end

    %% Webhook Handlers
    subgraph "webhooks/*"
        direction TB
        WebhookMeta["app.config.yaml"]:::config
        WebhookHandler["Webhook Action Code"]:::actions
    end

    %% Starter Kit Samples
    subgraph "starter-kit/*"
        direction TB
        StarterMeta["app.config.yaml"]:::config
        Hooks["On-Deploy Hook"]:::config
        SKActions["End-to-End Actions"]:::actions
        Scripts["Utility Scripts"]:::actions
    end

    %% Connections
    Developer -->|"Deploy via AIO CLI"| IORuntime
    Developer -->|"Deploy Starter Samples"| StarterMeta
    IORuntime -->|"Hosts Serverless Actions"| RegCode
    IORuntime -->|"Hosts Event Actions"| EventHandler
    IORuntime -->|"Hosts Webhook Actions"| WebhookHandler
    IORuntime -->|"Hosts Starter Actions"| SKActions

    AdminUI -->|"Loads UI Bundles"| WebSRC
    BannerMeta -->|"Configures UI Extension"| AdminUI

    WebSRC -->|"Invokes Actions"| IORuntime
    RegCode -->|"Calls Commerce APIs/<br>API Mesh"| IORuntime
    RegCode -->|"Calls API Mesh"| APIMeshGateway

    APIMeshGateway -->|"Unifies GraphQL Responses"| IORuntime
    APIMeshGateway -->|"Fetches from"| ExternalServices
    MeshConfig --> APIMeshGateway
    Schemas --> APIMeshGateway
    Resolvers --> APIMeshGateway

    EventBus -->|"Triggers"| EventHandler
    EventBus -->|"Triggers"| WebhookHandler
    Hooks --> EventBus

    StarterMeta -->|"Defines Full-Stack Flow"| AdminUI
    Scripts --> EventBus

    %% Click Events
    click Developer "https://github.com/adobe/adobe-commerce-samples/blob/main/.devcontainer/devcontainer.json"
    click BannerMeta "https://github.com/adobe/adobe-commerce-samples/blob/main/admin-ui-sdk/banner-notification/custom-mass-actions/app.config.yaml"
    click RegCode "https://github.com/adobe/adobe-commerce-samples/blob/main/admin-ui-sdk/banner-notification/custom-mass-actions/src/commerce-backend-ui-1/actions/registration/index.js"
    click WebSRC "https://github.com/adobe/adobe-commerce-samples/blob/main/admin-ui-sdk/banner-notification/custom-mass-actions/src/commerce-backend-ui-1/web-src/src/index.js"
    click MeshConfig "https://github.com/adobe/adobe-commerce-samples/blob/main/api-mesh/commerce-and-catalog/meshConfig.json"
    click Schemas "https://github.com/adobe/adobe-commerce-samples/tree/main/api-mesh/commerce-and-catalog/queries"
    click Resolvers "https://github.com/adobe/adobe-commerce-samples/blob/main/api-mesh/custom-field/resolvers.js"
    click EventMeta "https://github.com/adobe/adobe-commerce-samples/blob/main/events/commerce-customer-login/app.config.yaml"
    click EventHandler "https://github.com/adobe/adobe-commerce-samples/blob/main/events/commerce-customer-login/actions/customer-login/index.js"
    click WebhookMeta "https://github.com/adobe/adobe-commerce-samples/blob/main/webhooks/add-to-cart-stock-validation/app.config.yaml"
    click WebhookHandler "https://github.com/adobe/adobe-commerce-samples/blob/main/webhooks/add-to-cart-stock-validation/actions/commerce/product-validate-stock.js"
    click StarterMeta "https://github.com/adobe/adobe-commerce-samples/blob/main/starter-kit/order-bidirectional-integration-sample-prj/app.config.yaml"
    click Hooks "https://github.com/adobe/adobe-commerce-samples/blob/main/starter-kit/order-bidirectional-integration-sample-prj/hooks/post-app-deploy.js"
    click SKActions "https://github.com/adobe/adobe-commerce-samples/blob/main/starter-kit/add-ingestion-scheduler/actions/ingestion/scheduler/index.js"
    click Scripts "https://github.com/adobe/adobe-commerce-samples/blob/main/starter-kit/customize-registrations-and-events/scripts/commerce-event-subscribe/index.js"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef actions fill:#d4edda,stroke:#28a745,color:#000;
    classDef apimesh fill:#ffe5cc,stroke:#ff9900,color:#000;
    classDef config fill:#f0f0f0,stroke:#aaa,color:#000;
    classDef developer fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef runtime fill:#d4edda,stroke:#28a745,color:#000;
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#000;
```
