I want to share what we’ve achieved working with architectural drift. Linters and tests help check code correctness and style, but they can’t effectively identify structural deviations that may accumulate over time and affect the long-term stability of a project. So, we asked ourselves how we can proactively manage such risks.

In the search for an answer, we came across an approach that takes into account not only the syntax and functionality but also the code structure. It’s based on analyzing changes in a project’s architecture by modeling its structural integrity. This method allows us to track deviations from the historical code structure, which is critical for long-term maintainability and scalability.

The foundation for this approach is the theoretical model PhaseBrain, which uses a toroidal representation to analyze the dynamics of structural changes. This allows us to capture deviations that are not visible to standard tools but can significantly impact the project’s architecture.

The translation of this theory into practice led to the creation of a tool that integrates into the code review process and analyzes changes in pull requests. This tool works with the code in the context of its historical structure, highlighting areas that may affect the architectural integrity of the project.

As a result, each PR is analyzed, and hidden dependencies and changes are identified that could be missed in traditional analysis. The system flags these changes as potentially dangerous to the structure and provides a report for further analysis. All of this happens within the familiar code review process.

The technology was implemented as a GitHub App, which is available on the GitHub marketplace.

We invite developers interested in this topic to test the proposed tool and share their experiences. Feedback would be very helpful for us.

Thank you for reading, and have a great day!