Technical Debt

The Vaadin Flow Web Framework - On the Highway to a New Quality Level

Cape of Good Code certifies the Vaadin Flow Web Framework as having good architectural quality after measurable improvement efforts in the previous two years.

“The DETANGLE® analysis reflects the effort put in improving the internal architecture quality of the Vaadin Flow framework. It also gives insights into the possible future quality enhancements.”
Yuriy Yevstihnyeyev and Mikhail Shabarov 
(Technical Lead  and Product Owner Flow Framework)



  • The Vaadin development team has made great measurable efforts over the last two years to improve the internal architecture quality of the Vaadin Flow web framework, the heart of the Vaadin software.

  • The focus on quality improvements, rather than solely new feature development, has paid off. The DETANGLE® software architecture quality metrics have now reached a normal level for 2021/22 and are now in the green zone.

  • The few remaining critical hotspots in the code were identified with DETANGLE® and concrete recommendations for refactoring were derived from them.

  • Vaadin Flow as open source software is well on its way to a high quality standard and can be highly recommended for use in commercial projects.

Measurable Efforts for Quality Improvement

The Vaadin development team has made great measurable efforts over the last two years to improve the internal architecture quality of the Vaadin Flow web framework. The focus on quality improvements rather than solely new feature development has paid off. The increasing maintenance effort to fix new bugs was reduced in 2021 and kept constant in 2022. 


Figure 1: Maintenance vs. Primary/Feature Effort in % (2018-2022)

The diagrams in Figure 1 show the maintenance effort over the last five years until the end of 2022 on the left and the feature development effort on the right. DETANGLE®  measures the effort as a weighting of the changed lines of code across the commit history of the code repository. Details on the approach can be found here.

The aforementioned decrease in feature development in 2021/22 is striking, so that the effort in 2022 is slightly below the critical threshold of 40% compared to a value of 65% in 2020.  I.e. the focus of development work in 2021/22 was not only on new feature development, but on increased code improvement work. 

This is confirmed by the diagrams in Figure 2, where the improvement efforts on the left can now be compared with the said feature development efforts on the right:


Figure 2: Improvement vs. Primary/Feature Effort in % (2018-2022)

Improvement work was captured in the project under the ticket types "Chore", "Refactor", "Internal improvement" and "Performance" and amounted to 28.56% of the development effort in 2022. This accounts for more than the share of maintenance work or at least half of the scope of the respective feature development in the period 2021-2022.

Thus, it is easy to see that the focus of the development team's work in 2021-22 has partially shifted away from feature development to software quality improvement through the addition of testing, refactoring and performance improvement efforts. 

Stable and High Level of Architectural Quality

The result is clear. The DETANGLE software architecture quality metrics now show a strong downward trend towards the green value range in Figure 3 for the years 2021/22 due to the improvement work compared to the years 2018-2020 before.


Figure 3: Primary/Feature Debt Index (PDI)
and Contributor Friction Index (CFI) in 2018-2022

The Primary Debt Index (sometimes also called Feature Debt Index) measures compliance with the single-responsibility principle at architecture level. On the one hand, new features should have been implemented cohesively in the code, or the architecture should make this possible. This means that a feature should not be scattered throughout the entire code base. Secondly, features that are independent of each other should not be coupled to each other in the code base. Feature cohesion and feature coupling together yield the Feature or Primary Debt Index (PDI).

You can find more details on this here. Furthermore, an explanation of the Contribution Friction Index (CFI), the second DETANGLE® architecture metric, can be found on this site

Few Remaining Construction Sites

The few remaining hotspots in the code were identified with DETANGLE® and concrete recommendations for refactoring were derived to improve their design quality. This mainly concerns the design of the "frontend" code areas, as the following tables of the source folders show:


Figure 4: Remaining “frontend” Hotspot Folders

The first two tables on architecture extensibility show exactly two "frontend" folders whose Primary Debt Index (PDI) is marked yellow because their value is above the warning threshold.

These are the flow-server/src/main/java/com/vaadin/flow/server/frontend folder and the corresponding test folder. The two folders each account for around 16kLOC, so together they represent almost 10% of the total code base. Both are affected to approximately the same extent by about 1.5k changed LOC of maintenance effort, whereby this is already 23% of the total development effort in the test folder and slightly under 20% in the src folder.

PDI is a measure of architecture extensibility. It measures the modularity of the code in the sense of whether new features can be implemented cohesively without getting strongly coupled to existing features in the code. It can be concluded from this that both the source files in flow-server/src/main/java/com/vaadin/flow/server/frontend and the test files are strongly coupled with each other and new features can hardly be implemented without unintended side effects (such as new bugs).  

In addition, the DETANGLE® metrics Defect Density (DI) and Defect Impact (DI) in the third table measure architecture maintainability. Defect Density indicates how strongly the code is affected by new bugs (number of bugs per 1000 lines of new code). Defect Impact also indicates the extent to which follow-up bugs occur, i.e. how strongly the bug-fixing is coupled to each other and by affecting the same code passages.  Therefore, the third table shows that the flow-server/src/main/java/com/vaadin/flow/server/frontend folder also stands out under the aspect of architecture maintainability with regard to its DD and DI values, and the feared side effects continue to occur when new features are implemented.

Refactoring Suggestions

With DETANGLE® it is possible to drill down to the source files of these two folders and arrive at a file-level list of hotspots as shown in Figure 5.


Figure 5: Remaining “frontend” Hotspot Files

Furthermore, these source files, their feature coupling and cohesion can also be qualitatively examined by means of a DETANGLE® network graph. From this, refactoring recommendations can be derived, such as splitting a source file or extracting code from several files to form a new file. This will be discussed in a separate blog post.

Commercial Use

In summary, it can be said that the Vaadin Flow open-source web framework is well on its way to a high self-imposed quality standard and can be highly recommended for use in commercial projects.

New requests and requirements on the part of the customers should now be easily implemented by the development team without having to entail a high maintenance effort or the breakage of existing features.


Similar posts