Global reference architecture examples

This topic describes common ways of organizing a global reference architecture (GRA) code base. Although the separate packages option is preferred, some situations require one of the other options described below.

Definitions

Option 1: Separate packages

See Composer project structure best practices for setting up this method.

The most flexible way to manage GRA Composer packages is through metapackages. Metapackages contain a composer.json file only, which defines other package dependencies. Create metapackages using Private Packagist repositories.

Main project composer.json

{
    "name": "example-client/region-1",
    "description": "Example Client Region 1",
    "type": "project",
    "require": {
        "magento/product-enterprise-edition": "2.3.5",
        "example-client/meta-region-1": "~1.0"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "repositories": [
        {"type": "composer", "url": "https://repo.packagist.com/example-client/"},
        {"packagist.org": false}
    ]
}

example-client/meta-region-1 composer.json

{
    "name": "example-client/meta-region-1",
    "description": "Region 1 meta package",
    "type": "metapackage",
    "require": {
        "example-client/meta-gra": "~1.0",
        "example-client/theme-frontend-region1",
        "example-client/language-es-es",
        "ingenico/ogone-client"
    }
}

example-client/meta-gra composer.json

{
    "name": "example-client/meta-gra",
    "description": "GRA meta package",
    "type": "metapackage",
    "require": {
        "geoip2/geoip2": "~2.0",
        "magento-services/module-stackify-logger": "~1.1",
        "example-client/sap-connector",
        "example-client/service-chat",
        "example-client/store-locator"
    }
}

Each module, language pack, theme, and library has its own Git repository. Each Git repository synchronizes to the Private Packagist repository automatically and generates a package there as long as there is a composer.json file in the root of the Git repository.

Options 2: Bulk packages

Below is an example of multiple modules inside a single Composer package.

A bulk package can only include packages of the same type. For example, if you have multiple packages for Adobe Commerce modules, themes, language packs, and libraries, you must create separate bulk packages for each type.

The file structure inside the vendor directory should look like the following example. However, check your project to see what should be included in your Git repository):

.
└── example-client/
    └── gra/
        └── src/
            ├── SapConnector/
            │   ├── etc/
            │   └── registration.php
            ├── ServiceChat/
            │   ├── etc/
            │   └── registration.php
            ├── StoreLocator/
            │   ├── etc/
            │   └── registration.php
            └── composer.json

The composer.json file should look like this:

{
    "name": "example-client/gra",
    "description": "GRA Modules",
    "require": {
        "magento/magento-composer-installer": "*"
    },
    "type": "magento2-module",
    "autoload": {
        "files": [
            "src/SapConnector/registration.php",
            "src/ServiceChat/registration.php",
            "src/StoreLocator/registration.php"
        ],
        "psr-4": {
            "ExampleClient\\SapConnector\\": "src/SapConnector",
            "ExampleClient\\ServiceChat\\": "src/ServiceChat",
            "ExampleClient\\StoreLocator\\": "src/StoreLocator"
        }
    }
}

Option 3: Split Git

This architecture uses four Git repositories to store code:

To set up this option:

Option 4: Monorepo (recommended)

This strategy closely mimics the way that the Magento Open Source Git repository works.

All code is developed and tested in a single repository. Automation distills packages from this single repository, which can be installed on UAT and production environments using Composer.

The monorepo option offers you the ease of working in a single repository, while also providing the flexibility of composing instances with packages.

Versioning and package distillation is done through automation, using GitHub Actions or GitLab Actions.

See the following resources for more information about this automation:

Do not mix strategies

It is not advisable to use a combined approach using Composer for GRA packages and the app/ directory for brand or region packages.

You not only get all advantages but also all disadvantages of both methods. You should pick one or the other (Git or Composer), to work optimally.

Solutions to avoid