Refactoring legacy software: from challenges to opportunities

This article tells how we handle the internationalization of an logistics management system (OMS) and the challenges of integrating with new e-commerce platforms. The system was developed in 2018 to optimize the order preparation process of a booming e-commerce company and efficiently integrate with different logistics operators. Built using PHP (Symfony), MySQL, Socket.io, and jQuery, it covers the entire process from packaging to shipping, including features such as order tracking, courier connections, label generation, and order preparation performance metrics.

The accumulation of technical debt

This system worked well for many years, but as the business grew, its limitations became increasingly apparent. Technical debt is particularly worrisome, affecting multiple levels of a project. In terms of technical infrastructure, the application runs on outdated frameworks and base language versions:

• Symfony version (4.0) is not a long-term support (LTS) version and will stop receiving security updates starting from January 2019.
• PHP 7.1 has also ended its life cycle and the system lacks critical security updates.

In addition to outdated versions, the project also has serious flaws in the fundamentals of software development:

• Lack or Insufficient Testing: A lack of automated testing (unit, integration, and end-to-end testing) not only hinders the early detection of bugs, but also makes any modifications potentially jeopardizing the stability of the system.
• Lack of coding standards: The codebase does not follow any documented patterns or standards, and even if there are, they are not consistent with industry best practices. This makes both maintenance and onboarding new developers to the project difficult.
• Inadequate documentation: Existing documentation is sparse and often incomplete. This affects not only technical development but also the understanding of the business processes implemented in the code.
• Incomplete version control: Git history lacks explanation, commit granularity is rough, messages do not follow any conventions, and lack background information on the changes made. This makes it difficult to understand the evolution of code and decisions made over time.

The accumulation of technical debt not only poses a threat to the stability and security of the system, but also:

• Reduced the development speed of new features
• Increased risk of introducing bugs
• Increased the difficulty for new members to join the team
• Increased maintenance costs
• Complicates problem diagnosis and resolution

Structural limitations

The original architecture had coupling issues that seriously affected its flexibility and scalability:

• Completely dependent on the main e-commerce platform: The application cannot run independently, and all logistics operations are directly dependent on the data and processes of the e-commerce platform. This means that any changes to the main platform may break the functionality of the system.
• Shared database causing performance issues: Logistics applications and e-commerce platforms use the same database, which leads to performance issues, especially during peak load periods for either application. Additionally, this configuration complicates permission management because any access to the database may compromise important data from other systems.
• Cannot run standalone: This app is designed to run only with e-commerce platforms. Not only does this limit its portability, it also prevents testing in an isolated environment or migrating to other platforms. Its dependencies are not properly encapsulated, any attempt at isolation would require large and costly changes to the entire system, and the Single Responsibility Principle (SRP) is not adhered to in the main class.
• Difficulty in implementing new features: Lack of compliance with the Open/Closed Principle (OCP) and Liskov Substitution Principle (LSP) greatly hinders the evolution of the system. New features require modifications to existing code, increasing the risk of introducing regressions. Additionally, direct dependencies between modules make following the Dependency Inversion Principle (DIP) nearly impossible.

These structural limitations not only reduce the maintainability and scalability of the system, but also increase the risks associated with any modification or evolution, leaving the application in a technically fragile and strategically vulnerable state.

Development management and strategic alignment

One of the most significant challenges is not only technical, but also strategic. While external development is functionally correct, there are significant organizational limitations:

• Disconnected from global strategy: Development is done in silos without a complete understanding of the company’s internal goals and processes. This results in features that, although technically correct, don't always meet the actual needs of the business.
• Lack of strategic prioritization: Implementation of new features lacks a clear evaluation and prioritization process. There is no questioning whether a feature is truly necessary, whether it is the best way to implement it, or whether a more efficient alternative exists.
• Reactive Development vs. Proactive Development: Development primarily follows a reactive model, addressing immediate needs without considering long-term impacts or potential synergies with other processes in the company.
• Lack of Validation Process: The lack of a structured review and validation process results in features that, while working, don’t always provide the best solution for the end user or the company’s overall goals.

This situation is unsustainable in the long term because it:

• Resulting in products increasingly deviating from actual needs
• Hinders integration with other company systems and processes
• Complicates strategic decisions about products
• Limits the team’s ability to innovate and continuously improve

Impact of basic costs

An often overlooked but particularly important aspect in this project is base cost, which I believe is a key concept in software development and refers to the cost of keeping a system running even without adding new features or making improvements. minimum cost required.

In our case, base costs include all costs associated with maintaining obsolete framework and language versions, resolving emergencies due to accumulation of technical debt, managing dependencies with other systems, adapting to coupled architectures, and domain knowledge costs incurred due to insufficient understanding. All of this consumes a significant amount of available resources and directly impacts the ability to invest in innovation and continuous improvement.

Although this factor was not the decisive factor in our decision to internalize development, it was quite influential in the initial diagnosis of the project. Base costs are often ignored when assessing the sustainability of a system, but in this case it clearly demonstrates that current strategies are unsustainable in the long term. Furthermore, as we will see in subsequent articles, any attempt to maintain the existing structure will exponentially increase the base cost over time.

For a more detailed explanation of basic cost concepts and their importance, it is recommended to refer to Eduardo Ferro’s original article.

Turning Point: New Challenges and Strategic Decisions

In any refactoring project, there are multiple strategies that can be employed, and the dilemma is often encountered: strangler fig or big bang rewrite.

The initial technical decision was to work within the same legacy project using the Strangler Pattern, an approach that involves developing a new module or system that gradually replaces parts of the old system. This strategy allows us to make parallel changes, reduce risk, and maintain current functionality while building a stronger foundation to support future functionality.

However, from a business perspective, this option poses an undue risk to the existing system (which is already operational and performing its functions). We decided to avoid touching the existing project and instead develop a standalone application to meet the new needs.

This shift resulted in us forking the existing codebase, a decision that was technically feasible but had certain drawbacks:

• Duplication of code bases: Two separate code bases now need to be maintained.
• Database Separation: Data structures must be copied and adapted for each system.
• Infrastructure replication: Requires deploying independent servers and ensuring appropriate observability for each system.
• Increased cognitive load on the team: All this duplication requires extra effort to maintain consistency between the two systems, thereby increasing the team’s complexity and risk of errors.

This approach allows us to move towards independent solutions, ensuring the stability of existing systems while developing a project aligned with new strategic goals. However, a detailed analysis of the pros and cons is necessary to plan and address this challenge with confidence. In addition, we reached a consensus with the business level not to expand functionality and to tightly control the project's backlog until the migration to the new e-commerce platform was completed.

Conclusion and next steps

The decision to internalize and rewrite legacy software is never easy, especially when the software is capable of doing its job. The saying "If it works, don't touch it" will always be there. However, sometimes it takes one step back to take two steps forward.

In subsequent articles in this series, we will explore how we responded to these challenges, the technical and strategic decisions we made, and how we turned these challenges into opportunities for improvement and team development.

The above is the detailed content of From software legacy to strategic opportunity: The starting point (I). For more information, please follow other related articles on the PHP Chinese website!