Team Legacy Improvement (3): SOCAR Zone Management System - A 6-Year Story of Improving Legacy Code and Documentation

SOCAR's Asset Development (Asset) Team operates internal systems including the zone management system, and has been fixing legacy little by little over 6 years without stopping the business. In the process, they improved the structure of around 20 tables and around 400 columns, raising tests from 0 to 350 and coverage from 0% to about 10%.

There were two core problems: outdated table structures and tacit knowledge held by individuals. Different document types were all stored in a single table, so depending on the type, most columns were NULL, and even M:N relationships were used with entirely different meanings depending on the type value. The ERD alone couldn't convey the business flow, and understanding of the system was dependent on specific individuals.

Even when trying to start testing, the structure got in the way. An entity with 70 to 100 columns had to be set up every time, so creating even a single test came at a high cost. In the end, increasing tests required first organizing the ERD and code structure, and the prerequisite was changing to a structure where business, code, and ERD align with each other.

The biggest obstacle in legacy improvement was not technology but permission. While splitting and changing tables, a dual-track period was needed in which the existing structure and the new structure coexisted, and the organization had to accept the risk during this period. To achieve this, the following 3 items were documented every time.

• Current state: existing table structure and dependencies
• Target state: structure after the change
• Rollback method: a procedure that allows reverting even without the person in charge

Column deletion was handled with the same principle. First, references to the column were removed from the code and deployed, then they went through checks for removal of SELECT *, data consistency during the dual-track period, and a full review of code references. After that, DROP COLUMN was performed using MySQL 8.0's Online DDL. The key point was not that DDL itself is safe, but that a safe state must be established first before executing DDL.

After becoming TL, the focus shifted to documentation aimed at improving incident response capability. A Postman Team Workspace was created to organize APIs and incident response procedures by system, and ERDs for 10 systems were uploaded to Confluence so that anyone could view the data structure. As a result, the bottleneck in incident diagnosis and response shifted from people to documentation, and even PMs and business staff began using it in their actual work.

The remaining conclusion is simple. Legacy is not fixed all at once but fixed a little every day, and the criteria can be summarized into four points.

• Structure first: build a structure that allows writing tests
• Organizational trust: be able to accept a long dual-track period and its risks
• Safe order: code first, schema later
• Documentation: separate knowledge from people