March 23, 2026
Architectural smells in TypeScript backends: a comparative analysis
Alef Felix de Farias; Jamile Raquel Regazzo
Summary prepared by the ResumeAI tool, an artificial intelligence solution developed by Instituto Pecege focused on synthesis and writing.
Contemporary software development is undergoing a period of rapid evolution, driven by the need to meet increasingly complex and dynamic demands in the digital environment. In this scenario, software architecture plays a decisive role in defining the quality and sustainability of technological solutions, especially in web-oriented ecosystems using the TypeScript language. The structural integrity of a system is not merely a matter of aesthetic code organization, but a critical factor that directly influences the maintainability, scalability, and longevity of applications. The identification of architectural deficiencies, technically termed architecture smells (Martin, 2017), has become a vital field of study for modern software engineering. These flaws, often invisible in immediate functional tests, compromise the internal structure of the system, creating obstacles that hinder the healthy evolution of software over time.
Projects developed in TypeScript face particular challenges due to the language’s flexibility and the diversity of architectural styles it supports, from the traditional monolithic model to modern microservices and serverless computing approaches. Issues such as high coupling between modules and low internal cohesion are recurrent and negatively impact the performance and reliability of deliverables. Although technical literature has extensively explored these concepts in languages like Java or C++, there is still a significant gap in studies that specifically focus on the impacts of these deficiencies in the context of TypeScript. The relevance of this topic is reinforced by empirical investigations demonstrating how inadequate architectural patterns affect maintainability (Jolak, 2025). Managing architectural debt, through the detection and prioritization of smells, is an essential practice in large organizations seeking to maintain agility without sacrificing technical quality (Martini, 2018).
The persistence of these structural flaws throughout the software lifecycle is a documented phenomenon, indicating that once introduced, architecture smells tend to become more recurrent and difficult to eradicate if there is no early intervention (Gnoyke, 2024). To address this reality, automated detection methodologies have been proposed as a way to enable continuous monitoring of code health (Fontana, 2016). The theoretical basis for this analysis largely lies in the set of object-oriented design metrics established by Chidamber and Kemerer (1994). Although originally conceived for analyzing source code at the class level, these metrics offer a solid foundation for evaluating broader architectural problems when properly adapted. Recent studies confirm that applying these indicators allows for the early identification of problematic patterns, facilitating the adoption of effective corrective measures (Jolak, 2025; Gnoyke, 2024).
A deep understanding of architecture smells requires an analysis that goes beyond the surface of the code, investigating how design decisions impact the interdependence between components. The central objective of this investigation is to explore the presence and evolution of these deficiencies in TypeScript projects, using adapted metrics to measure the real impact across different architectural styles. By identifying the most frequent patterns and understanding their implications, it becomes possible to propose mitigation strategies that contribute to the development of more robust and sustainable web applications. The justification for such an effort lies in the pressing need for tools and knowledge that assist software engineers in navigating the complexity of modern architectures, ensuring that technological innovation is not hindered by internal structural degradation.
For the execution of this analysis, a methodology structured in sequential steps was adopted, focusing on the investigation of open-source repositories with a predominance of the TypeScript language. The process began with an assertive survey on the GitHub platform, using the public API to filter projects that met rigorous criteria for relevance and activity. Repositories were selected with a number of forks greater than 50, the presence of multiple contributors, and recent activity, characterized by commits made after the beginning of 2025. This filtering ensured that the sample consisted of projects with sufficient maturity to present architectural structures amenable to in-depth analysis. In total, 47 repositories were selected for detailed study.
The classification of projects into different architectural styles was performed through a technical inspection of the source code and configuration files. For the identification of monolithic architectures, the presence of centralized modules and standardized entry files, such as the prefix module and the main.ts file, was sought. In the case of serverless applications, the determining criterion was the existence of specific configuration files, such as serverless.yml or template.yml, which define isolated routes and functions. For microservices, identification was based on the presence of multiple package.json files and independent src folder structures for each service, indicating functional decentralization. After this screening, the final sample consisted of 27 monoliths, 14 microservice systems, and six serverless applications.
The collection of metric data required the development of a sophisticated analysis pipeline, based on the TypeScript compilation API. This pipeline allowed for semantic and structural reading of the code, going beyond a simple text analysis. The process involved reading the tsconfig.json file of each project, creating an analysis program via typescript.createProgram, and generating an Abstract Syntax Tree (AST). With the support of the TypeChecker, it was possible to extract precise information about the relationships between classes, methods, and properties. The extracted data were persisted in an SQLite database, using the better-sqlite3 library in a Node.js environment, which facilitated the execution of complex queries and subsequent statistical analysis.
The metrics selected for evaluation were Coupling Between Objects (CBO), Weighted Methods per Class (WMC), Response for Class (RFC), and Lack of Cohesion in Methods (LCOM). CBO was calculated by identifying dependencies between classes, including the use of parameters, properties, and inheritance, allowing for the detection of points of low functional isolation. WMC focused on internal complexity, calculating the individual cyclomatic complexity of each method, considering conditional blocks and loops. RFC counted the total number of methods and functions accessible in response to a call on a class, highlighting the accumulation of responsibilities. Finally, LCOM assessed internal cohesion by analyzing how many methods share common attributes, identifying classes with fragmented responsibilities.
To interpret the results, severity thresholds were established, adapted from classic literature and contemporary studies (Chidamber; Kemerer, 1994; Pigazzini, 2020; Martini, 2018). CBO and WMC values between zero and 10 were considered adequate, while results between 11 and 20 indicated a state of attention, and values above 20 were classified as critical. For RFC, the normal range was defined up to 25, with attention between 26 and 50, and criticality above 50. In the case of LCOM, values up to four were seen as positive, between five and 10 as a warning, and above 10 as critical. In addition to design metrics, the Madge tool was used to perform static module inspection and identify cyclic dependency chains, which are clear indicators of modularity degradation.
The data analysis revealed an unequal distribution of architecture smells among the analyzed models. It was observed that large-scale projects, such as NX, Island.is, and Firebase-tools, concentrate the largest sums of metrics, with extremely high RFC and LCOM values. This pattern suggests excessive coupling and the presence of classes with multiple responsibilities, characteristics that frequently point to the existence of latent architectural debts. The recurrence of circular dependencies in expressive repositories, such as generator-jhipster and opencollective-api, highlights flaws in functionality isolation, which hinders refactoring processes and limits system scalability. These findings corroborate the thesis that structural complexity tends to increase proportionally to project size when rigorous technical governance is absent (Jolak, 2025).
In the monolithic architecture, the average CBO recorded was 26.84, a considerably lower value than observed in microservices. This difference can be attributed to the integrated nature of the monolith, which requires fewer explicit dependencies between external modules. However, the monolithic model presented the highest average WMC, with 89 points, and RFC, reaching 172.11. These figures suggest a strong concentration of functionalities within a few central classes, a phenomenon typical of mature or legacy systems where continuous evolution generates overloaded components. The high presence of WMC reinforces the indication of excessively complex methods, which compromises both code readability and testability, creating what the literature defines as God Classes (Martin, 2017).
Conversely, microservice-based systems exhibited the highest degree of external coupling, with an average CBO of 92.22. This result reflects the very nature of the architectural style, which is based on communication between multiple autonomous services. However, the high average LCOM, which reached 94, indicates that, even within theoretically isolated services, there is low internal cohesion. This suggests that the transition to microservices, if not accompanied by precise domain design, may merely displace complexity, creating services that attempt to handle multiple responsibilities simultaneously. The fragility in communication between these services, often carried out without versioned contracts, generates risks of cascading failures and significantly increases integration complexity (Pigazzini, 2020).
Serverless applications, despite presenting the lowest absolute averages for CBO (3.40) and RFC (6.40), revealed unexpected behavior in the WMC metric, with an average of 69.40. This value indicates that, although functions are small and independent, they tend to concentrate dense and complex internal logic. The formation of mini-monoliths was observed, where a single serverless function assumes responsibilities for persistence, data manipulation, and business rules. A critical example was identified in the typescript-aws-lambda-typescript repository, where the DBManager class presented a WMC of 31 in a single method. This pattern, termed Spaghetti Functions (Fowler, 2018), violates the principles of granularity and simplicity expected for the serverless model, hindering error tracking and maintenance.
The discussion of the results indicates that the choice of an architectural style is not, in itself, a guarantee of quality. The absence of systematic monitoring practices inevitably leads to the degradation of internal structure, regardless of whether the system is a monolith or a set of microservices. The statistical tests performed reinforced this view; the Kruskal-Wallis test indicated a significant difference only for the CBO metric (p=0.0306), while the aggregated profile analyzed via PERMANOVA showed no global statistical distinction between architectures (p=0.856). This suggests that, at a macro level, all architectures share common structural fragilities when subjected to continuous evolution processes without adequate refactoring. The distinction between them lies more in the location and type of smell than in the presence or absence of the problem.
The identification of classes with critical RFC and LCOM values, as observed in the island.is project, where RFC exceeded 6000 and LCOM surpassed 4000, serves as an early warning sign of imminent maintainability failure. Such components become bottlenecks for development, as any minimal change can trigger unpredictable side effects in various parts of the system. To mitigate these risks, the adoption of Bounded Contexts principles (Evans, 2003) is recommended, which aid in the clear separation of responsibilities and the reduction of implicit coupling. Furthermore, the implementation of function composition patterns and the standardization of responses via middlewares are effective strategies for reducing cyclomatic complexity in TypeScript environments.
The practical contribution of this study materialized in the development of the artie-lens tool, designed to automate the collection and analysis of these metrics in continuous integration pipelines. The systematic use of tools of this type allows engineering teams to anticipate architectural degradation before it becomes an impediment to business evolution. Static analysis should not be seen merely as passive diagnosis, but as input for predictive models of technical debt. For example, the trend of exponential growth in coupling metrics can serve as a trigger for prioritized refactoring sessions, ensuring that software sustainability is preserved over time (Wang; Zhang; Kazman, 2024).
It is necessary to acknowledge the limitations of this research, which focused on open-source code repositories. The coding bias present in community projects may differ from practices adopted in closed corporate environments, where architectural rigor can be influenced by aggressive commercial deadlines or restrictive internal standards. Furthermore, the reduced number of serverless applications in the sample limited the depth of statistical conclusions for this specific group. Future research should expand this database and explore the correlation between architecture smells and operational performance indicators, such as mean time to recovery from failures and infrastructure cost, providing an even more integrated view of the impact of code quality on organizational success.
It is concluded that the objective was achieved, as the investigation empirically demonstrated that the presence of architecture smells in TypeScript systems significantly compromises the quality and sustainability of applications. The analysis showed that each architectural style has specific vulnerabilities: monoliths tend towards the creation of overloaded and complex classes, microservices suffer from high coupling and fragile dependencies between components, and serverless systems often feature poorly cohesive functions that concentrate excessive logic. The results reinforce that structural degradation is a continuous process that is independent of the chosen model, with technical governance and automated monitoring through metrics such as CBO, WMC, RFC, and LCOM being the only effective defenses for prolonging software lifespan. The artie-lens tool emerges as a viable solution for integrating this vigilance into the development cycle, allowing for the early identification and mitigation of architectural flaws to ensure the scalability and maintainability necessary to face the growing complexity of modern systems.
Bibliographic References:
CHIDAMBER, S. R.; KEMERER, C. F. A metrics suite for object oriented design. IEEE Transactions on Software Engineering, v. 20, n. 6, p. 476-493, 1994. DOI: 10.1109/32.295895.
EVANS, E. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003.
FONTANA, F. A.; PIGAZZINI, I.; ROVEDA, R.; ZANONI, M. Automatic Detection of Instability Architectural Smells. In: IEEE INTERNATIONAL CONFERENCE ON SOFTWARE MAINTENANCE AND EVOLUTION (ICSME), 2016, Raleigh, NC, USA. Proceedings […]. IEEE, 2016. p. 433–437. DOI: 10.1109/ICSME.2016.33.
FONTANA, F. A.; PIGAZZINI, I.; ROVEDA, R.; ZANONI, M. Automatic Detection of Instability Architectural Smells. In: IEEE INTERNATIONAL CONFERENCE ON SOFTWARE MAINTENANCE AND EVOLUTION (ICSME), 2016, Raleigh, NC, USA. Proceedings […]. IEEE, 2016. p. 433–437. DOI: 10.1109/ICSME.2016.33.
FOWLER, M. Refactoring: Improving the Design of Existing Code. Addison-Wesley, 2018.
GNOYKE, P.; SCHULZE, S.; KRÜGER, J. Evolution patterns of software-architecture smells: An empirical study of inter-version smells. Information and Software Technology, 14 ago. 2024.
JOLAK, R.; KARLSSON, S.; DOBSLAW, F. An empirical investigation of the impact of architectural smells on software maintainability. Information and Software Technology, v. 156, Mid Sweden University, Sweden, 27 fev. 2025.
MARTIN, R. C. Clean Code: A Handbook of Agile Software Craftsmanship. Upper Saddle River, NJ: Prentice Hall, 2008.
MARTINI, A.; FONTANA, F. A.; BIAGGI, A.; ROVEDA, R. Identifying and prioritizing architectural debt through architectural smells: a case study in a large software company. In: EUROPEAN CONFERENCE ON SOFTWARE ARCHITECTURE (ECSA), 2018. Proceedings […]. Springer, 2018. p. 320–335.
WANG, Z.; ZHANG, Y.; KAZMAN, R. The study on software architecture smell refactoring based on priority. Journal of Systems and Software, v. 206, p. 111334, 2024.
Executive summary from the Final Project of the Specialization in Software Engineering of the MBA USP/Esalq
Learn more about the course; click here:
