Global Reference Architecture Patterns

Next to “no GRA pattern” there are four styles of GRA patterns.

5 icons of GRA patterns: no GRA, split, bulk, separate and monorepo.

No GRA pattern

An icon that depicts "no GRA"

When a GRA pattern is not used, each Adobe Commerce instance is a unique application. There is no code reuse, except by manually moving code from one instance to another. These copies always diverge. The amount of effort to ensure that each instance has the same changes but still works as expected can become overwhelming. In this scenario, three instances need three times the maintenance effort of one instance.

A diagram depicting 3 stores, where each is a copy from the former, with unique development happening in all 3 copies.

The split Git GRA pattern

An icon depicting the "split" GRA pattern

This pattern consists of Git repositories for development and one Git repository per instance. Each file in the instance is maintained in one of the development repositories. They come together as a braid forming the whole GRA. Each line of code only exists in a single development repository and is installed to the instances using the braiding technique, leading to code reuse.

A diagram showing where code is stored in a split GRA pattern

The bulk packages GRA pattern

An icon representing the "bulk" GRA pattern

The Adobe Commerce core and third-party modules are directly installed through Composer repositories. Git repositories can be used as Composer repositories. In this pattern, the entire GRA shared codebase is hosted in a single or a few Git repositories and installed through Composer. The key characteristic is that multiple modules, language packs or themes are hosted in a single composer package, simplifying development.

A diagram showing where code is stored in a bulk packages GRA pattern

The separate packages GRA pattern

An icon representing the "separate packages" GRA pattern

Each Adobe Commerce module, language pack or theme is installed as a separate composer package. Each customization has its own Git repository. This means ultimate flexibility in the composition of the instances and has reliable Composer dependency management. For performance optimization, all packages are mirrored in a single private composer repository.

A diagram showing where code is stored in a separate packages GRA pattern

The monorepo GRA pattern

An icon representing the "monorepo" GRA pattern

All development takes place in a single code repository. Automation generates packages for new versions and publishes them to a composer repository. The pattern combines the low development overhead of the bulk packages approach with the flexibility of the separate packages approach. The monorepo pattern is also ideal for running automated functional tests.

A diagram showing where code is stored in a monorepo GRA pattern

Choosing a GRA pattern

The choice for a GRA pattern is made by assessing the project complexity, the need for flexibility, and the development team’s ability to adapt.

Teams with little Adobe Commerce experience best start simple. However, if the project demands a more complex GRA pattern due to its characteristics, do not compromise.

Common project characteristics related to each pattern:

  1. No GRA pattern: Single instance of Adobe Commerce without plans to extend. Multiple instances of Adobe Commerce with minimal commonality between them.

  2. Split Git GRA pattern: Teams that wish to avoid Composer for their customizations, in most cases Bulk packages pattern is a preferred pattern to Split Git.

  3. Bulk package GRA pattern: Customization codebase with high interdependency. Instances all have very similar combinations of custom packages. No frequent promotion or demotion of individual packages. Teams with little experience in code management and in need of simplicity.

  4. Separate packages GRA pattern: Flexible release scope management needed. 50 or less custom packages are anticipated in the next 5 years. Potentially, global and regional layers of common code. No plans to migrate to a Monorepo pattern. The team is technically adept and has strict process adherence.

  5. Monorepo GRA pattern: All characteristics of the Separate packages GRA pattern. More than 50 packages are anticipated in the next 5 years. Need for extensive automated testing. Support for ephemeral environments. Enterprise scale complex codebase that needs to scale without scaling maintenance cost at an equal rate.

The cost of a wrong choice

Migration from one pattern to another is possible. The diagram below shows the level of impact of moving from one pattern to another. Green lines show low impact, yellow and amber lines show moderately complex to complex migrations.

A diagram showing colored arrows between all 4 GRA patterns, indicating the level of difficulty of moving from one to the other.

Previous pageRetry mechanism
Next pageSplit Git

Commerce