Transitioning to a miniservice architecture

Embedded software engineer
Transitioning to a miniservice architecture
Imagine this: you have made the wise choice of taking the monolith-first approach, setting up an application. You have read my previous article about the pros and cons of miniservices. And now, the time has come to start the transition to a miniservice architecture. How do you go about that?

Below are a couple of things to be aware of as well as a number of steps that can be taken in order to migrate a monolith to a miniservice architecture.

This article is the second part in a series of three, the first being 'From monolith to miniservices', the third 'The persistent microservice'


  • No common understanding and goal between teams and their individual members For the transition to succeed, it's vital for teams and their individual members to work towards the same goal as well as use the same strategy to get there. Think about what exactly you want to accomplish by transitioning to a miniservice architecture. Do you want shorter release cycles? Replaceability? Or do you just want to go with the latest fashion in architecture? Also, assess whether your team members possess enough knowledge about miniservices and their goals.

  • Keeping in mind Conway's law, you should take a careful look at your organisation and update any process or structure that wouldn't work well with running many independent teams.

  • Too-tightly-coupled parts If the monolith is not already set up in a modular way, transitioning to a miniservice architecture can become very hard. Refactoring the monolith to more clearly separate modules should be done first. Where possible, a module should only cover a single domain. Take care, though, as refactoring usually introduces unforeseen bugs.

  • Stateful to stateless transition Miniservices should not depend on persistent state and as such the monoliths functionalities should not depend on persistent state, apart from a loosely coupled database system or an abstracted-away cloud storage service. Miniservices depending on local storage are hard to scale horizontally, as that storage would need to be kept in sync. Miniservices should only access each other's data via APIs, so that each miniservices has clear ownership of their domain.

  • Integration testing after each split If a monolithic application is not already being integration tested before transitioning, these tests should be set up in advance. As refactoring oftentimes introduces bugs, you should assure yourself that the system works well in its entirety, before deploying. Where possible, automate these tests. Computers don't get bored with testing, humans might become less accurate over time.

  • Starting from scratch One might think it's always a good idea to throw away all legacy code in favor of a new architecture. It does give you the advantage that you don't have to live with the consequences of past decisions. However, accurately estimating the amount of work rebuilding a (large) application is hard and often very much underestimated. It's vital that the transition be manageable for it to succeed.

Steps to enlightenment

  1. Set up integration tests As the application will be quite heavily in flux during the transition, a large amount of certainty in the correct functioning of the application as a whole should be created by systematically testing the system as a whole.

  2. Gradually refactor the monolith, decoupling more functionalities within Decouple modules and domains as much as possible.

  3. Select a simple and easy-to-isolate functionality of the monolith Don't go big. Single out fairly loosely coupled modules that are not too critical. Work in atomic steps: have only one module or domain be transitioned at a time. Give yourself time to learn how to migrate a part successfully.

  4. Create a miniservice that has that same functionality Having identified a single task that can be transitioned, build a new miniservice that has this task as its single responsibility. Some guidelines to take into consideration:

  5. Test the miniservice and test it thoroughly This is vital: as monoliths might have a lot of interconnected functionality, finding out about introduced bugs should be done as early and thoroughly as possible.

  6. Deploy miniservices somewhere deployment is easy Once the monolith is split up into many smaller services, running deployments becomes much more frequent. This should be taken into consideration from the start of the transition. Choose a simple per-service process and automate each step. You could look into setting up a kubernetes cluster, for example.

  7. Connect the monolith with miniservice, and remove the functionality from the monolith in one go Omitting the removal of legacy code results in a harder to maintain the system as a whole.

  8. Run the integration tests and update Test before deploying, and if possible, test the system with a limited number of real-world users as well before deploying to the whole user base.

  9. Reflect on the process Make it easier for yourself and your team members to learn from your mistakes, in order to be able to tackle more elaborate transitions. Keep a list of problems you encountered and precautions you'll take to avoid them in the future.

  10. Go back to step 2, until there is no more monolith left

  11. Profit!


We think that the monolith-first approach to setting up a system of miniservices is best. This approach gives you time to stabilize the requirements and identify the domains in which an application can be separated. Having established clear, small steps and beginning with easy migrations, gradually transitioning a monolith to a miniservice architecture seems the most sensible way.

Introducing a miniservice architecture involves a possibly drastic change in the way databases are operated. In my next blog post, this will be elaborated on in more detail.

Embedded software engineer

Stay up-to-date

Stay up-to-date with our work and blog posts?

Related articles

David is Tweede golf's newest addition, and not just any addition, he combines his work as a software engineer with a PhD in theoretical high energy physics. Specialized in the field of privacy and security, David brings a lot of knowledge to the team. For 2021 we were on the look-out to strengthen our expertise in this domain. David joining the team is just that!
KubiKey as a project started out with one main goal: streamline and make more secure the process of accessing the kubernetes cluster used by Tweede golf.
The point of setting up a miniservice architecture is to enable horizontal scaling, improve reusability and to speed up development by separating each domain into an independent application. Miniservices depending on a database pose a number of challenges. We'll explore a couple of them.