I love it when a plan comes together.
The odds were stacked against the team. The business owner was already in discussions with a third-party service provider to take over the reporting solution if the team didn’t meet the mandate of reducing the project delivery timelines this time around. If you recall in my previous post, our business wanted to roll out the solution to 5 countries within 2 years. The problem was a single implementation was taking over a year to roll out. Needless to say, at this rate we would roll out the solution in 5 countries in 5 years, which was clearly untenable. There were already 2 implementations running in production and the business owner didn’t understand why rollouts took so long and cost so much. The next few months were critical.
There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult. — C.A.R. Hoare
The Principle of Conceptual Integrity
The fact that there were two separate codebases for the same reporting solution was one of the warning signs I spotted during my initial investigation. I examined both codebases and I discovered that they shared more than 80% of the same code. The remaining portion of the code that was different was related to the central regulatory authorities’ web service contracts, which we integrated to for compliance reporting.
For the uninitiated, a web service is a function that can be accessed by other programs over the internet. A web service contract defines the format of the data involved in the information exchange.
The problem with this approach is that it locks all parties into a specific web service contract and prohibits code reusability across the different reporting implementations. This translated to all the parties starting from scratch whenever there was a need to onboard a new country onto the reporting solution, hence the long delivery times and the never reducing project costs. If we had to make the rollout of the reporting solution viable the concrete dependency on the web service contracts from the central regulatory authorities had to be broken. I applied the architectural principle of Conceptual Integrity to come up with what would be a sustainable rollout of the reporting solution.
Conceptual Integrity
The application should avoid concrete dependencies on other systems and applications where possible, and provide features that allow it and any data that it holds to be upgraded, migrated, and re-factored. [1]
- Application Architecture Guide — Chapter 6: Quality Attributes — J.D. Meier, Alex Homer, David Hill, Jason Taylor, Prashant Bansode, Lonnie Wall, Rob Boucher Jr, Akshay Bogawat.
After a few design sessions, we managed to come up with a standard contract that would be used within our organization for future projects. In addition to this, we managed to design a nifty adaptor component that would transform the message formats appropriately as they transition across the integration boundary. In Domain Driven Design terminology this integration boundary is known as the Anti-corruption Layer [2].
We somehow knew we had done a great job in meeting the initial business mandate, but we couldn’t prove it then as this was the initial implementation.
This is probably the simplest and most elegant solution that I have ever come up with — I doubt I will ever top it.
The Litmus Test
It was one Thursday afternoon when I was summoned to an urgent and impromptu meeting. When I walked into the meeting room, the project manager was already on a conference call with some executives from the country where we were implementing the reporting solution. The mood in the room was tense and I knew straight away something was wrong.
“As you all know, it has been a few days since we went live but the central regulatory authority still has not granted anyone permission to integrate into their web services due to a situation that is out of their control,” the project manager began. “This has put us in a difficult situation as one of the vendors who were reporting to the authority before on a previous version of the application can not have 2 different applications running in their production environment.” This was new information to me as this had never been raised when we logged the project’s risks. “We will have to pay severe penalties if we don’t submit any reports after the grace period which has been afforded to us until next week Wednesday.” Looking toward me she continued, “The reporting entities are already submitting reports to the aggregator component, right?”. I nodded gently to affirm her statement. “Since we have the data in the aggregator component, is it not possible to filter the data from this vendor and submit it to the previous web service endpoint?” she quizzed. I promised to get back to her by the close of business after consulting with the team.
I consulted the team and everyone was extremely confident we could pull off the rescue mission. A chance to test out our design couldn’t have presented itself at a more opportune time. I confirmed with the project manager that we would solve this issue and that there was no need for us to work over the weekend.
As things turned out we were right. We were able to develop, test and deploy the solution to production by Tuesday afternoon. This alone was good enough to prove we had done enough to streamline the delivery timelines and reduce rollout costs for future projects. In light of this, my job here was done.
References
[1] Excerpt from: J.D. Meier; Alex Homer; David Hill; Jason Taylor; Prashant Bansode; Lonnie Wall; Rob Boucher Jr; Akshay Bogawat. “Application Architecture Guide.”
[2] Anti-corruption Layer Patter — https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer
