3 min. read
Categories: Technical
Architecture Decision Records in Sylius
We decided to be more transparent with the Sylius Community about our choices. Eventually, they affect Sylius users the most. To achieve this goal, we commenced a new approach to technical documentation - Architecture Decision Records.

Read how we have implemented ADRs in Sylius development and what good it brings.

Hello everyone! Being a Sylius Core Team member is fun – there is no doubt about that. Of course, we also need to make a lot of difficult decisions and actions regarding Sylius architecture, features, bug fixes, etc. The first of these is especially important, as it defines the foundation for all other technical decisions. Therefore, we decided that we need to be more transparent with the Sylius Community about our choices. Eventually, they affect Sylius users the most. To achieve this goal, we commenced a new approach to technical documentation – Architecture Decision Records.

(Recent) Past

Many Core Team members made architecture decisions in Sylius over the last few years. They were usually useful and well-received (three layers of Order-related entities, usage of the state machine concept, Resource and Grid). However, it can be hard for newcomers (or sometimes even for the existing Sylius developers) to comprehend the reasoning of these decisions. Of course, you can also ask us, and you’ll get the vast explanation… But we can do better, can’t we?

As you probably already know, we started a huge new feature recently – integration with ApiPlatform. New Sylius API is a big undertaking and it obliged us to rethink our approach to multiple development processes, from the testing to the implementation itself. We decided that, as with the roadmap and the whole code, we also want to be transparent with our architectural decisions. The inspiration was also architectural courses and conferences that some of us attended in the last months. 

We’re also aware that documenting decisions allows easier iterations over the provided value. Hence, as we explain Sylius features with Behat scenarios, we’ve started documenting architectural decisions with Architecture Decision Records (ADRs). 


We started simple, with the first ADRs prepared for the API for Product Options (consisting of some information about handling translations and options’ values). They were good, but we knew it’s just the beginning. To keep track of all architectural decisions we take, we have to iterate quickly over them and adapt them smoothly. We also had the feeling that what we need from the very beginning is some standard for this new kind of documentation. The standard that ideally would be both easy to read and sufficiently explainable. 

We decided to use the MADR template, which provides comprehensive information about a taken decision, as well as is well prepared to be used with the Markdown notation. We also adjusted it a little bit, e.g. removing “Pros and Cons of the Options” section, or simplifying the introductory description. We also explained the conventions for our ADRs, to be transparent about our transparency.

You can check out all these changes in this Pull Request.


“What’s next?” you can ask. A pretty good question that definitely needs an answer. The most important thing which we want to focus on now is to carefully explain all the important architecture-related decisions with ADRs. Naturally, the new API will be the first one covered by them (as we concentrate on API development as well). However, we also plan to describe all essential architectural choices taken in the last few years.

Of course, there is a trap. We often see that when excited with a new tool, one is looking for the possibilities to use it EVERYWHERE.

It’s also something we’ve already seen with ourselves. So the challenge for the upcoming weeks (or months) would be not only introducing this amazing convention in Sylius but also not to overuse it. We’ll do our best :). Right now, you can find all the existing ADRs in this section of the Sylius/Sylius repository. 

As always, we are looking forward to your feedback. Feel welcomed to contribute not only to the Sylius code but also to the documentation. Stay healthy and see you online!

Mateusz Zalewski
Long-time Core Team member and the main Trainer in the Sylius company with the current focus on improving training programs to make them as fun and developing for the Sylius newcomers as possible. He's also hung up on enhancing Sylius' architecture and its plugins' system. Privately, a huge enthusiast of history and astronomy.
More from our blog
Business News Technical 3 min read 28.09.2020
Get ready for global sales & operations with the most advanced payment solution from the famous fintech giant, now available in Sylius out of the box. Read More
Business News 3 min read 14.09.2020
We proudly present to you the latest version of the Sylius eCommerce Platform – 1.8, which comes with a brand new, unified API powered by API Platform, Loyalty points system for Sylius Plus, and as you can probably see, a brand new sylius.com website! Numbers This new release is a… Read More
Business Ecosystem News 3 min read 13.08.2020
Read why the French market leader trusted Sylius in a strategic re-platforming process to get a competitive eCommerce advantage. Read More