We developed and maintained a product data API for Migros for 10 years, fully embracing agile development. We went live with the initial version within six months, and then continued adding features and adjusted to the changing requirements and third-party systems.

After 10 years, Migros created an in-house team to in-source further development. In the last two years of Liip's involvement with the project, our developers collaborated closely with the growing internal team, gradually transferring the know-how and responsibilities. By 2024, Migros had fully taken over the project.

The application is a central system that provides real-time access to all product data. It collects information from almost 30 business applications, ranging from SAP systems and REST APIs to CSV files. The collected data is filtered, prepared and stored in an Elasticsearch cluster. Consumers can use REST calls to query for data in real time or subscribe to a company-wide message bus to synchronise updates within their own applications.

Strategy

From the very beginning, we had a clear architectural vision for building the API. We managed to keep the code base modern and manageable thanks to refactorings where we modernised the codebase as necessary. This was greatly helped by adopting modern coding practices, including:

  • Unit and functional tests - without these, it would have been difficult to confidently refactor the code.
  • PHPStan: Static analyser to detect potential bugs and impossible code conditions.
  • Typed code: Since PHP 7, the language allows to use typed variables. This greatly increases the robustness of the code.
  • Rector: Automated code refactoring to modernise the code to best practices and new language features.
  • PHP-CS-Fixer: Automated codestyle formatter for visual consistency.

This thorough approach to software quality was also backed by the customer. I remember a key moment at an early backlog refinement meeting: The developers had a discussion about whether a story should be done with a quick solution or include a refactoring to solve the issue properly. The customer PO told us to do the refactoring to make sure the application will remain maintainable in the long run. This mindset shaped the projectā€™s development.

We kept refactoring the code in a logical way. This kept a high consistency of the code, and made it easy to find where in the codebase a specific part of the application should be placed. This, in turn, prevents redundancy because developers can find existing code and don't reimplement functionality.

In a long-term projects, developers spend much more time reading and re-understanding code than writing new code. Therefore, caring for the existing code becomes important.

Tools

Now, letā€™s explore some of the tools we used to maintain the application in this fast-changing environment.

Testing
To me, legacy code is simply code without tests.
ā€”Michael C. Feathers

We implemented automated tests from the very beginning. This is the best time to establish tests, as they ensure the quality of the applicationā€™s foundation. Adding tests later is also a large effort that is often never taken. We implemented several layers of tests:

  • PHPUnit for unit tests
  • PHPUnit for functional tests, e.g. database repositories or API endpoints.
  • Behat for end-to-end tests (very powerful but fragile because they depend on real data)

Additionally, we employed the static analyser PHPstan. This tool combines the actual code with documentation comments and spots whole categories of potential mistakes or runtime errors before the code is executed. This tool pushes developers to write cleaner code and better documentation comments. By complaining about meaningless constructs, it either helps simplify the code, or lets the developer spot logic mistakes in the code.

Documentation

We documented the project on different layers.

  • A wiki with general concepts and business decisions, used and collaboratively maintained by product owners, developers and stakeholders.
  • An interactive online API documentation, generated from the code and documentation comments in the code
  • Documentation comments in the code, with additional README files and text files in a documentation folder in the git repository for technical documentation. Having the technical documentation close to the code made it easier to keep it up to date than having it in a wiki.
  • ADR (Architecture Decision Record), a formal way to document architecture decisions to keep all developers aligned.

We also use an automated codestyle fixer. Making the code look consistent reduces mental overhead, and helps prevent non-functional formatting changes mixed with functional changes. The tool would allow customising which rules to apply or even adding custom rules. We agreed on the default ruleset from Symfony. We care less about the exact style, but do care about the style being consistent.