Blazin Safety: five framework versions moved, zero database changes

Write the parity contract before writing any code

The first real phase was not upgrade work, it was an inventory. Every screen of the legacy application was walked and documented: every field, validation rule, workflow, role gate, and side effect across eleven feature areas, from user access and the dashboard through clients and locations, the 15,168-item equipment register, service records and work orders, reports, and the cross-cutting audit, barcode, PDF, and Excel tooling.

The output was roughly 150 catalogued findings. Not a wish list, a definition of “unchanged.”

Two details from that phase matter more than the headline number. Predictions were tested rather than assumed: at least two anticipated defects turned out not to exist, because the legacy app had gotten them right, and both were documented as overturned. An inventory you can only confirm is an inventory nobody should trust.

And the database’s typos were promoted to requirements. Column names like clinet_location_type_id and supression_agents are misspelled. They stayed misspelled. Downstream code depends on them, and cleaning that up is exactly the kind of well-intentioned change that breaks a production system on a Tuesday.

Build the safety net before touching the stack

Phase 2 delivered the harness the entire upgrade would lean on: PHPUnit against real MySQL on the back end, front-end unit tests, per-module happy-path coverage, and CI running everything on every change.

It also introduced three guard tests, automated checks that fail loudly if anyone ever renames a preserved production column, breaks the audit trail, or changes URL resolution. These are not feature tests. They are tripwires on the three non-negotiable constraints.

With the net in place, the same phase cleared the backlog of code-only production bugs the inventory had found, each fix shipping with a test. Self-service password reset had been broken for every user, a malformed link plus a token expiry set to four minutes instead of four hours. More than 1,200 equipment-model records were invisible to administrators because of a URL-casing bug. A role-check gap let non-admins reach equipment they should not see, through both the on-screen filter and the Excel export. A 60-second dashboard hang turned out to be a 60 MB payload loaded on every visit and never used.

Move one thing at a time, and gate every step

The core discipline: each phase changes exactly one concern, and no phase closes without passing the same formal bar. Laravel 6 to 8 is not one step, it is two, each separately gated. PHP 7.4 to 8.1 is two. The Vue 3 migration is three checkpoints. There is always a working, verified application between any two steps, never a six-week window where the app does not run.

Phase 4.5 does not appear in the original thirteen. It exists because scoping the PHP 8 upgrade surfaced a hard blocker: the abandoned login library had no released version that runs on both PHP 8 and Laravel 8 at the same time. There was no version of the plan where it survived. The choice was to patch a dead dependency or pull forward a replacement already on the roadmap, and the replacement won, executed immediately on the then-stable build where exactly one variable was changing against otherwise-proven ground. Browser-stored tokens became protected server-side sessions, a genuine security improvement, and login, logout, “remember me,” and password reset behaved identically for every user.

Doing it early was the whole point. An authentication cutover handled as a deliberate, isolated, gated phase on a stable build is a controlled change. Discovering it midway through a PHP upgrade is an incident.

The gate catching things is the system working

Across the gated phases, the live walkthroughs, not the automated suite, caught real defects that would otherwise have reached production: a build configuration pointing part of the app at the production web address, anonymous visitors hitting a server error instead of a login redirect, every date picker rendering blank after the bundler change.

The clearest case came at the Vue 3 checkpoint. A full walkthrough of every module found six front-end bugs the previous checkpoint had missed, including two validation rules on the Service Record screen that had silently stopped running. When modern components replaced old ones, some legacy instructions were left pointing at page elements that no longer existed, and they failed silently. Nothing errored. The instruction just quietly stopped working, and automated tests written against the new components pass cleanly. Only a human driving the real app on real data finds that. Every fix now carries a test that was deliberately proven capable of failing, and the codebase was swept for the same class of problem.

None of it reached a user. All of it existed only in the upgrade branch. That is what the gates are for.

Decisions written before the code, not after

More than thirty architecture decision records were written across the project, each following the same rule: the record is written and approved before the code, never after. Accepted records are never edited, they are superseded.

That matters more than it sounds on a preservation-constrained project. When the correct answer is “do not change that,” you need a written reason that survives the next developer’s good intentions, including future you.

The same discipline applies to open questions. Where a question affects what a saved record means, the answer is not assumed. The clearest example: a technician who types a serial number to look it up is currently recorded as having scanned it. That behavior is identical in the live legacy app, and it has deliberately not been “fixed,” because changing it changes what saved records mean. That is the client’s call, not the developer’s.