Upgrading a Legacy Ruby on Rails Portal After the Original Dev Team Left the Stack
The Wholesale Floor Covering Credit Association of Canada runs a portal its members use to exchange credit information. Another company built it on Ruby on Rails and Heroku. By 2022, that company had moved its focus off Ruby on Rails, and the portal was sitting on Ruby 2.5.8, Rails 5.2.4.2, and the Heroku 18 stack with nobody maintaining it.
WFCCA had no technical team. MobiDev took over the codebase, audited it, and completed the upgrade and bug fixing in under three months against a fixed deadline. A business analyst documented how the portal actually behaved. We created clear quality assurance documentation with step-by-step test cases to easily verify that features work correctly and ensure the client can seamlessly run their business for years to come without worrying about portal stability.
The Story Behind the WFCCA Portal Upgrade
WFCCA is a Canadian non-profit association. Its members, floor-covering manufacturers, wholesalers, and distributors, use its web portal to exchange credit information remotely. The portal worked. Built on Ruby on Rails and hosted on Heroku, it had met members’ needs for years.
Then the company that built it stopped doing Ruby on Rails. By 2022, the stack was outdated, and nobody was left who knew the codebase.
WFCCA has no technical team, making it impossible to assess how far behind the stack was, how risky the upgrade would be, or whether a three-month estimate was honest. They needed an outside team to take the project over outright: the legacy code upgrade and the complex bug fixing that came with it.
Business Value of the Ruby on Rails Legacy Upgrade
The upgrade landed inside a fixed three-month window. Code audit, version upgrade, bug fixing and QA were completed in less than three months from the December 2022 start.
The portal became stable enough to stop being a topic. Since March 2023, WFCCA members have used the upgraded portal for day-to-day credit information exchange.
The team covered the project with Unit tests, so any further development and upgrades have a solid foundation to check against.
WFCCA now owns documentation it never had. Functional requirements describing intended portal behaviour, a Project Review Report, and a set of user acceptance testing cases. For an association with no technical staff, that documentation is what makes the next update scopeable by anyone.
Bugs outside the original scope were found and fixed. Regression testing surfaced unrelated defects, from minor issues to problems affecting application logic. Upon getting the client’s approval, we fixed them.
Several suggestions to improve the portal’s functionality within the planned budget were made. We implemented those approved by the client.
What the Client Says
We are a non-profit society that was in need of a website update. When we reached out to MobiDev, they were very patient with us, as we do not have a technical team, and they took the time to walk us through the process and explain what was going to happen. That was very reassuring. Their communication throughout the entire process was excellent. We were provided regular updates, so at no time did we feel that we did not know what was going on. They were extremely professional and an absolute pleasure to deal with. Thank you again for an excellent job.
Lindsay Clarkson
WFCCA Representative
Project Scope of the Ruby on Rails Legacy Upgrade
Four experts: a tech expert, a business analyst, and a QA engineer, with a project manager on the client-facing side.
Stage 1. Software code audit. An overall review of the product with an emphasis on technical aspects, before any upgrade work started. It produced the Project Review Report: current status of the system, issues ranked by severity, practical suggestions on what to do first, and the timeline and scope of work.
Stage 2. Functional requirements. We suggested creating the documentation for the project that would provide a single south of truth for testing and for the client to use it in the future and onboard new team members. Upon client’s approval, the business analyst documented the intended behaviour and functionality of the portal.
Stage 3. The upgrade. With the timeline and scope confirmed by the review, the team upgraded the system from Ruby 2.5.8, Ruby on Rails 5.2.4.2 and Heroku 18 Stack, and resolved the known bugs, in less than three months.
Stage 4. Regression testing and bug fixing. Legacy code is interdependent, so small changes cause unintended consequences. We notified the client about them before the work started. Regression testing was the approach chosen to confirm existing functionality still worked after the upgrade. It also surfaced unrelated bugs, from minor issues to problems affecting application logic, which were fixed.
Stage 5. UAT documentation. The QA engineer produced a list of user acceptance testing cases: which areas to test and the expected result for each. It sped up bug fixing during the project, and it is what a non-technical team can use to verify any future release.
Deliverables of the WFCCA Portal Upgrade
Deliverables text:
- Project Review Report: system status, issues by severity, prioritized recommendations, timeline and scope.
- Functional requirements documenting intended portal behaviour and functionality.
- Upgrade from Ruby 2.5.8, Ruby on Rails 5.2.4.2 and Heroku 18 Stack.
- Complex bug fixing on the inherited codebase, including defects outside the original scope and covering with unit tests.
- Regression and functional testing coverage.
- User acceptance testing case list.
Tech Stack
Ruby on Rails (upgraded from 2.5.8 / 5.2.4.2)
Functional testing
UAT
Ruby on Rails (upgraded from 2.5.8 / 5.2.4.2)
Functional testing
UAT
Inherited a codebase nobody wants to touch?
Send us the repository and we’ll tell you what state it’s in.
FAQ
Technical risks usually come from incompatible libraries, deprecated code, existing code that behaves differently after the upgrade, new infrastructure requirements (Ruby, Postgres, servers), and third-party integrations that stop working. Business risks are data loss during database structure changes, broken features, and downtime on the live site. We reduce them by backing up all data before the update, covering the code with unit tests and running regression testing, and preparing a rollback plan.
We deploy the upgraded app to a separate testing environment first and run regression testing until every function works as expected. Before the production update, we back up all live data, warn users in advance, and schedule the release for the window when downtime would affect them least. A disaster recovery and rollback strategy is ready before we switch production over.
Yes, and it is a common enough reason to change teams that it barely counts as a complication. WFCCA’s portal was built on Ruby on Rails and Heroku by a company that later shifted its focus away from Ruby on Rails. MobiDev took full responsibility for the legacy code upgrade and the bug fixing that came with it.
What matters is the order of work. You audit before you commit to a timeline, because nobody inheriting a codebase knows what is in it yet.
You get it in writing before the work. On this project the audit produced a Project Review Report: the system’s current status, the issues found with their severity, practical suggestions on what to prioritize, and the timeline and scope that followed. The business analyst then documented what the portal is supposed to do, which is the reference point for judging whether it does.
WFCCA is a non-profit society with no technical team. In their words: MobiDev “took the time to walk us through the process and explain what was going to happen,” with regular updates throughout.
Overall, the timeline heavily depends on the project scope and the code.
WFCCA modernization was done in 3 months. Cooperation ran from December 2022 to March 2023, and the system upgrade plus bug fixing was completed in less than three months, with three experts, on an inherited codebase.
The deadline held because the audit came first and set the scope. A three-month commitment made before anyone has read the code is a guess.
An overall review of the product with an emphasis on technical aspects. It answers four things: what state the system is in, which issues exist and how severe they are, what should be done first, and how long the work will take. Only then is the timeline and scope confirmed.
That is the actual risk, and it is why regression testing was the chosen approach here rather than an afterthought. Legacy code is complex and interdependent, so even small changes can cause unintended consequences or introduce new bugs.
On the WFCCA portal, that testing also turned up unrelated bugs nobody had reported, some minor, some affecting the application’s logic. Those were fixed as well.
Three documents WFCCA did not have before: the Project Review Report, functional requirements describing the portal’s intended behaviour, and a list of user acceptance testing cases specifying what to test and the expected result.
For an organization without engineers, the documentation is the part that keeps working after we leave. It is what the next update gets scoped and verified against, by us or by anyone else.
It is possible to migrate from any version to any version. The timeline and cost of the project will depend on many factors, including:
- Incompatible libraries
- Deprecation of existing code
- Changes in existing code behavior
- Required infrastructure is (Ruby, Postgres, Server, etc.).
- 3rd-party integrations
- The size of the existing app?
There is nothing impossible, but only the Technical audit will answer how many resources are required for the upgrade.
Yes, AI coding tools shorten the most repetitive parts of an upgrade: finding deprecated code, rewriting it for the new version, flagging incompatible libraries, and generating the unit tests that make a safe upgrade possible. The speed only holds if the AI output is reviewed and tested inside a controlled process, otherwise, it ships new bugs faster. For a legacy retail operations platform we’ve supported for 7 years, we turned the client team’s ad hoc vibe coding into a governed AI-driven SDLC (AISDLC) with clear rules for how AI-generated code is written, reviewed, and released.