How We Refactored a 30k‑Line Ad Engine in One Month: Key Lessons

1. System History and Pain Points

The advertising engine started as a simple search‑ad system but, after a year and a half of rapid business expansion, it had to support feed recommendations and similar‑item recommendations, leading to two major challenges: increasingly complex business scenarios and a surge in traffic that demanded both new functionality and high performance.

To cope, the team abstracted common logic into a core framework while parallelizing some code for performance, but the framework became rigid as new strategies piled up, forcing patch‑style development and resulting in scattered if checks and a loss of clear architectural boundaries.

2. Preparation Work

The team spent a month before the refactor reviewing existing code, reading old requirement documents, and consolidating core processes and ad strategies into a clear spreadsheet, which helped both technical and product stakeholders see the full scope and pain points.

Show the pain points – the spreadsheet revealed tangled logic and dozens of scattered strategies.

Define goals and value – the refactor aimed to (a) modularize the core framework with well‑defined interfaces and (b) make ad strategies dynamically configurable and pluggable.

Quantify expected benefits – clearer code structure, improved extensibility, faster development cycles, finer‑grained strategy configuration, and accelerated business iteration.

3. Execution Experience

The refactor was organized around four practical practices:

High‑quality technical design – for any task longer than three days, a detailed design document was produced; the final design covered architecture, module contracts, strategy extensibility, and generated a 5,000‑word, 36‑page specification.

Pre‑refactor framework scaffolding – a separate PR defined package structure, module boundaries, and API contracts before any implementation, allowing the team to review the intended architecture without being distracted by low‑level details.

Frequent communication and pair‑review – with only three engineers on the refactor, every ambiguous logic was clarified through repeated discussions; code reviews were assigned to domain‑knowledgeable peers in a paired fashion.

Robust testing strategy – the team adopted (a) end‑to‑end tests (no functional changes, so API behavior remained stable), (b) smoke tests provided by QA, (c) sandbox double‑process verification by comparing pre‑ and post‑refactor API responses, and (d) staged gray‑release using an AB‑test platform, gradually increasing traffic from 5% to 100% while monitoring logs and business metrics.

4. Final Takeaways

Seven key points emerged from the project:

Choose the right timing for refactoring.

Conduct thorough pre‑analysis to surface pain points.

Clearly articulate goals and value to motivate the team.

Avoid long‑running parallel work with business features.

Invest in a high‑quality technical design.

Let testing lead the change – never modify existing code without a new, fully tested package.

Validate every line of code through careful verification.

The most critical factor was the team’s collaboration; when every member is reliable, a large‑scale refactor is already half‑won.