Refactoring a Core Business System: Lessons Learned and Best Practices

In 2014 the author transferred from the infrastructure team to the business department and was tasked with improving the stability of a core business system.

A bug caused a private message intended for a single user to be broadcast to many merchants, leading to customer complaints, public relations involvement, and pressure from management.

The team concluded that the only sustainable solution was to refactor the existing code, which had become difficult to maintain due to extensive if‑else branches, long functions, sparse comments, and insufficient documentation.

Because the system comprised dozens of micro‑services and external dependencies, they divided it into three logical parts and prioritized the middle segment—where changes and failures were most frequent—for the first phase of refactoring.

Traditional unit tests were inadequate, so they designed a dual‑flow verification approach: the refactored code was wrapped behind a new interface while the old logic continued to run; the outputs of both flows were compared field by field, and the new flow was validated without producing real side effects, combined with a careful gray‑release strategy.

Lacking documentation, the team extracted the full version‑control log, contacted original code owners, and gradually reconstructed about 90‑plus percent of the business logic.

The gray‑release was performed at a very fine granularity—initially one merchant at a time—monitoring logs and metrics after each step; after a week the rollout expanded gradually and covered all users within a month, with only minor issues detected.

To align expectations, the author communicated openly with superiors, peers, and sub‑team members, adopting a "tight inside, loose outside" strategy that lowered external expectations while the team worked intensively.

Ultimately, the refactor was completed successfully, enhancing system reliability, reducing technical debt, and strengthening the team’s influence within the organization.