Handling a VAT Increase in a Legacy Real-Time System

Twin v1 served as the core operational system for the distributor business. In 2022, the Indonesian government increased VAT from 10% to 11%, requiring a system-wide update to our financial logic. While the system had been functionally stable for years, this regulatory shift exposed deep-seated architectural debt The long-term cost of choosing an easy or "quick-fix" solution now instead of using a better approach that would take longer to implement. in how we handled tax calculations.

The legacy architecture lacked temporal awareness A system's ability to track and process data based on when it occurred in time, rather than only knowing the 'current' state of the data. and data persistence for financial totals. Grand totals and tax amounts were never saved to the database; instead, they were recalculated dynamically "on the fly" every time an invoice was viewed or a report was generated.

This logic was decentralized, with the VAT percentage hardcoded as 0.10 magic numbers Unique values—like the 0.10 tax rate—hardcoded directly into source code without explanation, making them difficult to locate and update safely. directly within dozens of API controllers. Because calculations were performed in real-time rather than persisted at the point of sale, a simple update to 11% would have triggered a retroactive mutation An unintended change to historical records caused by updating logic or configurations that the system applies to both new and old data indiscriminately. of every historical invoice. We couldn't comply with the new regulation without simultaneously corrupting years of past financial records.

Accepting that a rewrite was impossible, I opted for a pragmatic, versioned tax strategy. I introduced a new vat_percentage column directly into the transaction tables to capture and freeze the rate at the exact moment of sale (Point-in-Time Snapshotting The practice of recording the exact state of dependent data (like tax rates or prices) at the moment a transaction occurs, ensuring the record remains accurate even if master data changes later.).

To mitigate the operational risk, I built out end-to-end test suites specifically for the critical APIs. I also introduced a runtime feature flag A technical toggle that allows functionality to be turned on or off at runtime, providing a safety net to disable new logic instantly if it causes production issues.—a defensive block that would hard-fail any transaction if the calculated VAT didn’t strictly match the legally valid rate during the rollout window.