Onboarding a legacy project mix monolith and microservices (1/N)
We don't always start from scratch. Often, Software Engineers find themselves tasked with improving a legacy system that wasn't created by us and isn't in the best shape. Where should we begin?
A friend of mine, let’s anonymize her/him as S.S., recently accepted a position as Tech Lead at another company. S.S. described to me the project that will be joining, which consists of a system that is part monolith and part microservices. Her/His goal is to transform the entire system into a fully scalable microservices architecture.
S.S. asked me at some point:
Marcos, if you would have to address this challenge
Where would you start to transform the monolith into microservices?
Would you refactor gradually, or would you start new microservices from scratch?
Would you refactor and improve the testing of the monolith before making any changes?
Maybe this is the same situation you might have to face in the future and that’s why I wanted to invest today’s issue in explaining how to address some of those concerns.
This is the first issue of a series in which I will cover those open questions, not only at a high level but also in the details. Today, I will cover the starting point. In future issues, I will cover the rest of the questions above.
☝🏻First things first
Before jumping into the code for each of the applications, services, and microservices, what I like to do is understand the business logic. You have to understand what the system is meant to do. Otherwise, you will not have the full picture and you could make the mistake to implement something that is wrong. How to understand the business logic? ask, ask, and ask as many times as necessary to your colleagues, to your product group, to sales people, to the CPO/CTO… whoever could give you the answers you need. Besides what many people could think, asking for information is the most healthy signal that you are interested and committed, for real, to your journey.
Once you have clarity at business level, what I like to do is understand the whole system and the infrastructure. You need to have on paper and in your mind all the systems, sub-systems, components, services, etc, and, even more importantly, the role, that each of them have, in the whole thing. Here you can use powerful questions, like “What is the purpose of X?” or “What was the intention of doing “that”? Important: play nice; you just arrived at your new team/company, the people you are asking most likely implemented that code and you don’t want to hurt anyone’s feelings. Here I share with you an interesting issue from
about how to interact in Code Reviews, but I think it applies as well for this case. And you just subscribe to his newsletter and thank me later 😉👇🏻
Drawing and writing all the inputs you got at the business level and at the engineering level will give you a good picture from which you can start thinking and find the initial spots to focus on.
Last but not least, it’s important for you to understand where you are heading. I mentioned at the beginning of this issue:
Her/His goal is to transform the entire system into a fully scalable microservices architecture
Maybe (indeed) that’s too vague.
What do we want to achieve?
What problem do we want to solve?
What is the benefit we will get?
What is the priority?
What…
WHAT is considered a "powerful question” because it’s open and makes the other person think… which is exactly what you need to have valid answers and so understand how the end of the road looks like. Just keep in mind that, in Software Engineering, “end of the road” is a strong word and, on many occasions, there is not such a thing, but a milestone, and then another milestone, and so on.
🗺️ Make a plan, drop the plan, make a plan
Once you have as much information as possible think that, most likely, there are still things you do not know. This is ok; embrace that uncertainty and take it into account when you do your plan.
And yes, you have to make a plan. If you never had to do a plan at this level, my recommendation is to do what we (engineers) do all the time when a problem is too big: split it into smaller problems.
To start, what I used to do is put into stickers (or tools like Miro as well) the first thoughts, those first ideas that your brain has held from the beginning and that it is eager to spit out as soon as possible. A sticker is too big? Chop it down into something smaller; iterate until you have something you think can be deliverable somehow.
Sign your plan. This might sound a bit “different” but it works for me that, once I have my high-level technical roadmap, I start to say it out loud, to listen to myself. The benefit I get from this exercise is that it helps me to find hidden spots, things that are not aligned, not clear, and points of risk.
It’s important as well that you share the plan with other engineers, with experience in the company and with the system, to get their input. Your goal here is to share it, not to find what is wrong or good, but just to get their feedback, for you to adapt the plan if necessary.
After signing and sharing the plan, it could happen that you conclude that you have to drop the plan. That’s fine. You did not waste your time, you learned, you evolved, and now you know better what is the right direction.
Now, make a plan again, following exactly the same steps mentioned before until you have something you feel comfortable explaining and defending, capable of explaining why you are taking each of the decisions that are present in your plan.
✨ Final words
Possibly you were expecting direct answers to the initial questions. If you are in a situation like my friend, starting the new Tech Lead position just in 2 weeks, you are hungry to have the final answers: Trust me when I say that what I shared with you should be the start of the journey. And it will take an important amount of your time. Just jumping into the code, making changes, or creating new beautiful microservices, will lead you into a possible disaster. Maybe this sounds very opinionated but, from my experience, what I wrote in today’s issue are the initial steps that will help you to be far away from failure.
In the incoming issues of this newsletter, I will continue with this journey and share my vision to answer the questions we kicked off today, not only at a high level but also in detail. Stay tuned!
This is what worked for me. Let me know your experience about a situation like this.
Finally, I want to wish all the best to my friend S.S. on the new journey as Tech Lead. You will rock!
Best,
Marcos