Incremental refactoring using three foundational pillars: Architectural Guidelines, Tests, and API Standardization

Improving Three Critical Pillars of the Source Code

Our team focused on improving three fundamental pillars to overhaul the existing source code: Testability, Code Organization, and Architecture/API Standardization.

Testability

Our team's initial goal was to create a large group of tests, guaranteeing high confidence in the code. Prioritizing this allowed the team to perform subsequent refactoring and initialize improvements without the fear of breaking the applications.

Our test suite mainly consisted of integration/functional tests powered by Cypress and Gherkin. By following this test structure, we maximized the effort:coverage ratio. Also, these tests provided excellent documentation, allowing future developers and stakeholders to understand the project features and functionalities.

Two phases divided the test creation effort.

In the first, we covered all of the principal scenarios, allowing us to continue the application's development, and refactor with certainty.

The second phase is a perpetual increment stage, where we both wrote tests for the new feature, and covered the test surface of parts we missed in phase one.

Code Organization and Architecture

Once the newly implemented tests endowed our team with an excellent confidence threshold, we worked to improve the code quality by focusing on Code Organization and architecture.

First, we identified the problems and virtues of the source code. The applications were already living in a Monorepo, but there were no clear boundaries. Admin, Platform, and Server applications shared logic, creating tight coupling and circular dependencies.

The monorepo used only Angular and some Nx. After analyzing the situation, Nx seemed like a perfect match. We started by migrating the repository to a pure Nx workspace, and we created the first libraries that would break the circular dependencies between the applications folders. This is an ongoing process, given that the applications have a considerable size. But the guidelines were set, and any changes to an old part of the code would involve a refactoring effort.

API Standardization

The third major pillar was API standardization. Initially, the admin and platform applications were created to consume the data from the server using different API protocols. The platform application used REST, and the admin application used GraphQL.

The goal was clear. We wanted to transform the entire application to GraphQL and benefit from its advantages. The process was iterative as with previous steps, but we managed to convert 99% of the application to use GraphQL in a relatively short time. This transformation also represented a significant performance improvement in load times and interactivity, not only because we solved the N+1 problem, but also because we obtained built-in cache capabilities.

Collaboration Following Changes to Client Organization

It is not entirely uncommon for critical members of client teams to leave their organization in the midst of a project. During this project, a Technical Lead at the client, who had been critical to the success of the project until their departure, left to explore different paths.

This presented two primary challenges:

• Our team needed to assume the project’s technical leadership role in the smoothest way possible
• We needed to compensate for the lost developer labor due to the absence of one of the client’s Technical Leads

The process was orchestrated through collaboration between leadership, This Dot Labs, and the outgoing technical lead, the latter creating textual and visual documentation to support the transition.

With the provided documentation and knowledge transfer sessions, our team could take ownership over the project's leadership, and continue delivering complex features at a similar rate as it would normally.

Doing this required our team to maintain a presence in all the operational and strategic meetings with stakeholders to gather feedback for future work requirements and improvements.

Additionally, we now maintain the backlog of tasks for both the Planning and Development Boards while taking a central role in the decision-making for the technical aspects of the project.

Finally, we manage the AWS infrastructure of the project, including CI/CD workflows, the cost analysis of the services, and instance maintenance.

Improving Open Source Technologies for Client and Community

While developing a feature, we found a bug in an npm package. Our team quickly opened an issue in their Github repository and through their customer service channels, helped them improve their code by fixing the bug blocking our development.

PowerBI integration

The product is a central place where medical professionals can find the information they need, but of course, it is not the only place. Other platforms provide additional features that are similar to those offered. In the spirit of making a unified platform, we embedded some of the informational dashboards from a business partner.

The integration was made using Microsoft PowerBI technology, which required an effective collaboration with the team owning the associated platform.

This process involved a couple of steps:

• Sign in with Azure AD to obtain an access token needed to authenticate on PowerBI to get an embed token.
• With the embed token, we could then embed the dashboards and customize them to look and feel like the platform, making it difficult for anyone to even notice that it was an external tool.

The integration was a greatly received feature from the client, who immediately found value in having the application as a more integrated tool.