The New Default. Your hub for building smart, fast, and sustainable AI software

See now
Striped gear and wrench illustration representing a legacy Rails code refactor

Working With Legacy Code: Cooleaf Refactor Case Study

Hubert Białęcki
|   Updated Nov 15, 2026

Since 2013, twenty Monterail developers have written more than 65,000 lines of code for Cooleaf, an employee engagement platform that had about 15,000 users when the refactor started in 2018.

A small team then refactored that legacy Rails code in stages, starting with dead code removal and a reorganization around business concepts. Working with legacy code means changing software that many developers have shaped over years, usually with uneven style, thin documentation, and leftovers nobody dares delete.

Executive Summary

Duplicate API versions and leftover code made every change riskier, and the client's feature releases could not stop. Monterail's developers chose refactoring over a rewrite, set strict rules such as adding no new gems, and grouped logic into domain concepts.

Cleanup came first and made the app more business-driven and easier to work on. Removing duplicates and adding a repository layer for data access were planned as the next steps.

How Did Cooleaf's Codebase Grow So Large?

Cooleaf changed direction several times before the refactor. A 2019 interview with its founders traces that path. Cooleaf launched in 2011 as a consumer health and wellness platform. Around 2014, it shifted to group micro-events for companies, and later it became white-label recognition and rewards software for employers.

Each pivot asked the same product to do something new. Logic built for an earlier model rarely disappears on its own, so features from past directions can linger long after users stop using them. That history helps explain why dead code and near-duplicate API versions later made it onto the cleanup list.

The product kept earning recognition. Monterail built the first version of its mobile app in six weeks, and the app won Best B2B App at the 2016 Atlanta Mobile Awards. Clients such as Citi, Rubicon, and WestRock praised the platform in the same interview. With paying clients relying on it, the product could not pause for a rewrite, which set the terms for everything that followed.

Cooleaf, an Atlanta-based HR technology company whose platform uses team building and rewards to keep employees engaged, kept growing after the refactor. Its case study page now reports around 110,000 active users across more than 100 organizations.

What Shape Was Cooleaf's Codebase In?

Cooleaf's codebase was large, inconsistent, and full of unused code. Leftover code was the biggest problem. Representers and controllers existed for three nearly identical API versions, and nobody could explain why each version was still in use.

Controllers were already lightweight, with most logic in external services. Those services had too many dependencies, so a change in one class could ripple across the app. High test coverage became a prerequisite at every step, since developers needed fast proof that nothing broke.

A small team owned a codebase of that size. Refactoring had to run alongside regular client features, and both streams had to deliver business value.

Why Did Refactoring Win Over a Rewrite?

Refactoring won because Cooleaf's feature work could not stop. A rewrite can leave an app unfit for release for months or even years, while a gradual refactor can run alongside regular client work and reuse existing code. Anyone facing the choice between rewriting and refactoring weighs the same things: speed, risk, and how long the business can wait for results.

Refactoring isn't cheap either. It is extremely time-consuming, and one system can involve both approaches, since different parts of it can receive different treatment. Larger products face the same trade-off on a larger scale, and paths for modernizing an aging codebase vary mainly in cost and risk.

How Was the Cooleaf Refactor Planned?

Planning rested on a few firm principles and a domain model split into concepts. The first rule: add no new gems where possible, since fewer gems make later updates and maintenance easier.

The developers drew on ideas from Trailblazer, a Ruby architecture that groups business logic by domain concept. Setting the boundaries of those concepts was the major issue, and the split went through two versions.

In Trailblazer, an operation is a class that wraps the business logic for one action, such as creating a user. A contract lists the fields and validation rules that action accepts. Controllers stay lean HTTP endpoints, and models handle associations and queries. The team borrowed the concept structure first and left full operations for later.

Stage

Concept split

First draft

User, HR, and Mutual

Revised model

Admin, HR, and User, with User treated as a separate application

Names agreed at this stage also make refactoring easier to explain to the client. Each later change then had a clear home in one concept.

What Did the First Phase of the Cooleaf Refactor Change?

Phase one cleaned the project to shrink the codebase and tidy each part. Dead modules went out, and code still in use moved into its concept.

Fixes and features set the order. If something broke in the user profile, for example, developers split the profile into concepts while fixing it. Each ticket took a bit longer, but the client never had to wait for a feature freeze, and the codebase improved with every fix.

Developers split existing logic into smaller classes and rarely wrote code from scratch. New patterns came in too, which could confuse other developers, yet the team stuck with them.

By the end of the phase, the app felt more business-driven and simpler to work on from one week to the next. Moving needed code and deleting the rest, though, was only the opening move.

How Do You Find Dead Code Safely in a Rails App?

Deleting code is cheap, while deleting code someone still uses is expensive. A 2023 thoughtbot article describes four strategies for removing dead Ruby code, and they work best in combination.

Technique

What it shows

Caveat

Coverband

How often each line runs in production

Needs weeks or months of traffic for rare paths

debride

Methods that static analysis never sees called

Misses dynamic calls, so verify before deleting

Feature flags

Whether anyone notices when a feature is off

Suits rarely used features such as yearly reports

Small pull requests

One removal per change

Makes each deletion easy to revert

The article's author left Coverband running for a couple of months and found that no line tied to one feature ever executed. The TODO Or Die gem can then mark other removable code for later pull requests.

High test coverage, which the Cooleaf team set as a precondition, adds the last safety layer. Tests confirm that the remaining code still behaves the same after each deletion.

How Do You Retire Duplicate API Versions?

With three nearly identical API versions, a single fix could need applying in up to three places. Retiring the extras starts with identifying who still calls them. Production usage data, such as Coverband counts for each version's controllers, shows which endpoints still receive traffic.

HTTP now has standard signals for the next step. The Deprecation header, defined in RFC 9745 from March 2025, warns API consumers about a past or upcoming deprecation, and the resource continues to work as before. The older Sunset header from RFC 8594 specifies the date when the resource is likely to stop responding. That date must not be earlier than the deprecation date.

A practical sequence follows from those tools. Measure usage, announce deprecation in headers and release notes, give clients a sunset date, then remove the version once traffic reaches zero. Each removed version shrinks both the codebase and the test suite.

What Comes After a Legacy Rails Cleanup?

With dead code gone, the plan moves from cleanup to structure. Four steps follow, in this order.

  • Remove duplicated code. Each fix then lands once, which makes the code easier to read and safer to change.

  • Introduce Rails model repositories to stabilize the app by separating database access from domain rules. The work is slow, so it goes step by step, with one developer owning it.

  • Revisit Trailblazer later. Full adoption would bring more structure, but its complexity keeps it out of scope until the cleanup settles.

  • Keep external gems to a minimum. It remains a standing goal, since fewer dependencies make future maintenance easier.

Every step builds on a smaller, better-understood codebase, so risk falls as the work continues.

Key Takeaways

  • Working with legacy code at Cooleaf's scale favors staged cleanup that runs alongside feature releases, not a rewrite.

  • Unused code and duplicate API versions were the first targets for removal.

  • Production usage data, static analysis, and feature flags make dead code removal safe, and Deprecation and Sunset headers do the same for old API versions.

  • Adding no new gems where possible keeps dependencies from growing during a refactor.

  • Grouping logic into business concepts gave every change a clear home.

Strategic Takeaway: Shrink Before You Restructure

Cooleaf's refactor began with deletion before any restructuring. Removing dead code and duplicates cuts the surface area that later changes must cover. Restructuring around business concepts then becomes realistic, and patterns such as repositories have a clean place to land.

Long-running Rails products need someone who can assess where a cleanup should start. Refactors of this kind are a core service of Monterail's Rails specialists. Discuss your legacy Rails app with Monterail.

Cooleaf Refactor FAQ

Hubert Białęcki avatar
Hubert Białęcki
Head of Technology at Monterail
Linkedin
As Monterail’s Head of Technology, Hubert brings a unique blend of technical expertise and strategic leadership to drive innovation and organizational growth. A graduate of Wrocław University of Science and Technology, Hubert has carved an impressive career path from JavaScript developer to technology executive, demonstrating both technical mastery and exceptional leadership capabilities. He excels at understanding complex organizational dynamics and implementing strategic changes that enhance team performance and company development.