Software architecture in an unknown domain.

At the end of 2022, I started a greenfield project with my current company, it is still under development, and I need to lead the tech, it has a really interesting but complex domain background.

In the beginning, there was no good governance of the problem, the product manager, even though amazing, didn’t have previous experience in that area, and the only reference is a consultant who told us how he did a similar system more than 10 years ago.

The nature of the problem makes the system dependent on external data sources that were a big black hole of misinformation, It was impossible to get requirements for all dependencies. I decided to start working and focus on pure business logic and delay those integrations for later, we started with the most simple and obvious part.

After several iterations, we moved to the next piece of logic that required no external interaction, it was finished after a couple of weeks. At this moment, we were in the fourth or fifth week, and it was time to look into how to define those external data sources.

We set our internal model, and I built in-memory wrappers and fake clients, it was hard to understand the dependencies as there was no clear ownership of the data, and it didn’t exist at that moment, so, I advised the team just to start writing the code, those clients and wrappers are there to die eventually, and putting in a big effort didn’t make any sense. It was more important to define a good domain model.

Here is where things got bad for me. After some days, I received bad feedback from my manager, the VP of engineering was looking into the project, and he gave the feedback to the head of my department, who told my manager, who then told me, the comment was horrible and destructive. I went on a call with the VP, and he ended up giving me reasons why I should start all projects with hexagonal architecture and that I should use it now.

There were several bad things in the entire story. I will focus on each one of them in different posts, but for now, I will just explain what happened with the architecture of the project.

By the team I received the comment, I had already identified how to refactor the codebase to make sense of what the project does, the idea was to follow the onion architecture and split several packages to define essential components.

I decided not to use hexagonal architecture for a while. The project was still in an early stage, and we were still learning about the domain, every new change came with refactors at all levels, and with every new step we took, I was able to get a better understanding of the problem. Locking the project to an early design with a lot of boilerplates, such as hexagonal architecture, would make it hard to do those refactors. A more linear structure, but with good separation through interfaces, was a better idea.

At this point, I don’t regret my decision. The project can grow, and changes are easy. Nevertheless, if I would like to slowly introduce a different architecture, it should be easy as well. Right now, it makes sense to introduce hexagonal architecture. the nature of the project and its high dependency on external sources deserve it, but it will not make a difference.

There’s a big lesson to be learned here: it’s extremely important to have good architecture for your project from day one. Hexagonal architecture is a great solution for separating business logic from external services, but it comes at the cost of more code. If you don’t know the domain very well, it can make changes harder. On the other hand, if I were to build another system like this one, I see no reasons to don’t use hexagonal architecture from day one, now that I know all the requirements for the system, I can architect it in a better way.