# Legacy Modernization: A Practical Guide for Founders > Legacy modernization for founders and CTOs: when a system is legacy, the first 30 days of a takeover, and how to migrate a live platform incrementally. - Author: Filipe Eduardo, Senior Software Engineer (https://filipeeduardo.dev/) - Published: October 6, 2026 · Updated: October 7, 2026 - Topic: Legacy modernization · Tags: legacy modernization - Canonical URL: https://filipeeduardo.dev/blog/legacy-modernization ![Old server tower having one drive bay swapped for a new orange module while still running, illustrating incremental legacy modernization](https://cms.filipeeduardo.dev/wp-content/uploads/2026/10/legacy-modernization-1.webp) ## Key takeaways - A system is legacy when changing it is risky, slow or dependent on people who are gone, not simply because it is old. - Modernize when patching keeps getting more expensive, not because a new framework looks attractive. - In the first 30 days, work in this order: access, then the build, then the money paths, then the risks. - Prefer incremental migration over a big-bang rewrite. Put a switch in front of everything before writing new code. - A rewrite usually costs more and takes longer, because the old system has to keep running in parallel. - Protect payments, sign-ups and data first. Everything else can move later. - Whoever does the work, you need a plan, a rollback path and someone accountable for the whole thing. In practice, **legacy modernization** is the work of moving an old but valuable system to a newer stack, architecture or infrastructure without losing what makes it valuable: the users, the data and the revenue. Done well, it happens piece by piece while the product keeps running, not as a big-bang rewrite that freezes the business for a year. I’m Filipe, a senior full-stack engineer based in Brazil. This guide comes from seven years of building web and mobile products, including leading the migration of a live platform while people kept using it every day. It is written for founders and CTOs who inherited a codebase, are leaving an agency, or are stuck on a stack that slows the team down. ## What is legacy modernization, and when does a system count as legacy? A system is legacy when it still does important work but is hard to change safely. Age is a weak signal. I have seen fairly young apps that were effectively legacy because nobody understood them, and much older systems that were healthy because they had tests, documentation and clear boundaries. These are the signs I look for: - **Fear of deploying.** Releases are rare, manual or done late at night because something might break. - **Knowledge sits in one head.** The original developer or agency left, and nobody can explain why certain code exists. - **Unsupported dependencies.** The language version, framework or libraries no longer get security fixes. - **No safety net.** There are few or no automated tests, so every change is a gamble. - **Hiring friction.** Engineers don’t want to work on the stack, or the few who know it are expensive and hard to find. - **Slow feature delivery.** A small change takes weeks because everything is tangled together. Modernization is the umbrella term for the options you have: refactor the code, [move it to new infrastructure](https://filipeeduardo.dev/blog/replatforming), replace parts of it, or rebuild it. Those are different strategies with different risks, and I compare them below. ### Legacy is not the same as technical debt [Technical debt is the accumulated shortcuts in a codebase](https://filipeeduardo.dev/blog/technical-debt). Legacy is the situation where that debt, plus outdated technology and lost knowledge, makes the system hard to evolve. You can have debt without being legacy, and you can pay down debt without modernizing the whole platform. ## How do you know it’s time to modernize instead of patching? Patching is right when problems are local and the foundation is sound. Modernizing is right when the foundation itself is the problem. The test I use is simple: is the cost of each change going up over time, and is the cause structural? ### Signals that point to modernizing - Security fixes can’t be applied because the runtime or framework is end-of-life. - Every new feature breaks something unrelated. - You can’t hire or onboard engineers at a reasonable pace. - The product needs capabilities the architecture can’t support, such as real-time features, a mobile app on the same API, or multiple tenants. - Infrastructure costs or outages are growing faster than usage. - [A buyer, investor or enterprise customer is asking hard questions about security or maintainability.](https://filipeeduardo.dev/blog/technical-due-diligence) ### Signals that point to patching - One module is the problem, and the rest is stable. - The pain is a missing feature, not a broken structure. - The team is productive and the stack is still supported. - You have no clear business outcome that modernization would unlock. A caution: engineers love new stacks, including me. Don’t modernize because a technology is fashionable. Write down the business reason first, such as faster releases, lower incident rate, ability to hire, or a customer requirement. If you can’t, [you are probably looking at a refactoring problem](https://filipeeduardo.dev/blog/legacy-code-refactoring), not a modernization project. When you do modernize, it helps to have a baseline. Note how long a typical change takes from idea to production, how often deployments fail, and how many incidents you have per month. Without those numbers you can’t tell later whether the work paid off. ## What should you do first when you inherit a legacy codebase? Don’t start by changing code. Start by getting control. [The order I follow for the first 30 days](https://filipeeduardo.dev/blog/take-over-codebase-first-30-days) is: access first, then the build, then the money paths, then the risks. The order matters because each step depends on the one before it. ### 1\. Access When I take over a codebase, the very first thing I do is inventory everything the system touches and make sure the company owns it. That means source repositories, hosting and cloud accounts, the domain and DNS, the database, third-party services (payments, email, analytics, authentication), app store accounts, and secrets. If the previous agency or developer is the only owner of any of these, transfer ownership now, while the relationship is still cooperative. Then rotate credentials that former contractors could still know. It is routine, not accusatory. ### 2\. The build Can you build and deploy the system from scratch on a clean machine? Many inherited codebases only work on the original developer’s laptop. Get a reproducible build, document the steps, and make one deployment yourself before you change anything. If you can’t deploy, you can’t fix anything safely. ### 3\. The money paths Identify the flows where the business earns or loses money: checkout, subscriptions, billing, sign-up, the core action users pay for. Trace each one end to end, add monitoring and alerts to it, and write at least a basic automated test or checklist for it. These are the parts you must never break. I learned to treat these flows with extra care on the cart and checkout team at Total Wine & More, a US retailer with 190 million site visits a year, where checkout is exactly the place a small mistake gets expensive fast. ### 4\. The risks Only now do a broader risk review: outdated dependencies, exposed secrets, missing backups, untested restores, unclear data handling, single points of failure. Rank them by likelihood and impact, and fix the cheap, severe ones first. [A code audit is a deeper version of this step](https://filipeeduardo.dev/blog/code-audit), and it is worth doing on its own. At the end of 30 days you should have a map of the system, a repeatable deployment, monitored money paths and a short, ranked risk list. That is the real starting point for any modernization decision. ## Rewrite, refactor, replatform or strangle: which approach fits? These four words get mixed up, so here they are side by side. Approach What it means Best when Main risk Refactor Improve the code’s structure without changing behavior The stack is fine, but the code is messy Slow payoff if the real problem is the platform Replatform Move to new infrastructure or runtime with minimal code changes Hosting, database or runtime is the bottleneck Moving problems to a new place Strangle Replace the system gradually, route by route, behind a switch The product is live and can’t stop Needs discipline and a long-running two-system period Rewrite Build a new system and cut over The system is small, or truly unsalvageable Cost, delay and lost behavior nobody documented ### Why I default to incremental My default is incremental migration, [usually the strangler approach](https://filipeeduardo.dev/blog/strangler-fig-pattern): put a switch in front of everything before writing new code. Requests go through a routing layer, and that layer decides whether the old or the new system handles each one. You then move one slice at a time, check it in production, and keep the ability to switch back. That is the pattern that let us move a live platform at avanzzada without asking users to stop using it. Big-bang rewrites fail for predictable reasons. The old system keeps changing while you rebuild it, so the target moves. Undocumented behavior, such as edge cases customers rely on, disappears in the new version. And you deliver no value until the very end, which is exactly when the pressure is highest. A rewrite can still be the right call. If the system is small, if the business logic is well understood, or if the old code is so broken that wrapping it is harder than replacing it, rebuilding the whole thing can be faster. Just make that decision on evidence, not frustration. ## How do you migrate a live platform without stopping the product? At avanzzada I led the full migration of a platform that applies to job openings automatically for its users. We [moved its whole architecture from a legacy stack to a new one while people kept using it every day](https://filipeeduardo.dev/blog/migrating-a-live-platform-to-a-new-stack). The lessons below come from that work and from similar situations. ### Step 1: Put the switch in first Before any new code, [add a routing layer or feature flags](https://filipeeduardo.dev/blog/feature-flags) so you can send traffic to old or new implementations, per route, per user group or by percentage. This is the most important decision in the project because it makes every later step reversible. ### Step 2: Choose the first slice carefully Start with something real but low-risk: a read-only page, an internal tool, a small feature with clear inputs and outputs. The goal is to prove the pipeline, deployment, monitoring and rollback, not to move the hardest part first. ### Step 3: Write down current behavior Before replacing a feature, capture what it does today, including the odd cases. Tests that run against the old system and then against the new one are the cheapest way to find missing behavior. When the two disagree, decide which one is right. ### Step 4: Release to a few users first Send a small share of traffic to the new path, watch errors and business metrics, then widen it. If something breaks, flip the switch back. That is the idea behind [canary releases](https://filipeeduardo.dev/blog/canary-deployment), and it works because mistakes stay small. ### Step 5: Handle the data deliberately Data is usually the hardest part. Options include sharing the old database during the transition, [syncing two databases](https://filipeeduardo.dev/blog/change-data-capture), or migrating in phases. Whichever you pick, decide which system is the source of truth at each stage, and [rehearse the migration on a copy of production data](https://filipeeduardo.dev/blog/database-migration) before running it for real. ### Step 6: Retire the old code Finish each slice by deleting the old implementation. A migration that never removes anything leaves you maintaining two systems indefinitely, which is the worst outcome. Expect the middle of the project to feel slow. You are running two systems, and that is the price of not stopping the business. ## What does legacy modernization cost, and why do rewrites cost more? I won’t give you a number, because any figure without knowing your system would be invented. What I can give you is what drives cost and how to compare options. ### What drives the cost - **Size and complexity of the system.** Number of features, integrations and user roles. - **Quality of what’s there.** Tests, documentation and clean boundaries make everything cheaper. - **Data volume and shape.** Messy or inconsistent data adds migration work. - **Uptime requirements.** The less downtime you can tolerate, the more careful and slower the cutover. - **Team seniority.** Senior engineers cost more per hour but tend to avoid expensive wrong turns. - **Scope discipline.** Adding features during a migration is the classic budget killer. ### Why a rewrite usually costs more A rewrite usually costs more and takes longer than an incremental migration, because the old system must keep running in parallel. You pay to maintain the old product, you pay to build the new one, and you pay again to reach feature parity before you can switch. With an incremental approach, each slice delivers value as soon as it ships, and you can stop at any point with a working product. That doesn’t make incremental migration cheap. The routing layer, the dual-running period and the data sync all take effort. But the spending is spread out, the risk is smaller, and you can adjust course. ### How to keep estimates honest - Run a time-boxed discovery (the 30-day takeover is a good one) before committing to a full budget. - Estimate slice by slice, not for the whole program. - Include testing, data migration, monitoring and the cost of running both systems. - Add a contingency for surprises. In inherited codebases there are always some. Be skeptical of fixed-price quotes made without seeing the code. The unknowns are too large to price honestly. ## How do you keep users safe and revenue flowing during the move? Users should barely notice the migration. These practices make that realistic. ### Protect the money paths first Checkout, billing and sign-up get the strongest safeguards: monitoring, alerts, tests and a documented rollback. If you migrate one of them, do it late, with a small share of traffic, during a period when your team is fully available to watch it. ### Always keep a way back Every release should be reversible quickly. With a routing layer, rollback is a configuration change, not an emergency redeploy. [Blue-green setups](https://filipeeduardo.dev/blog/blue-green-deployment), where the old environment stays up until the new one proves itself, serve the same purpose for infrastructure changes. ### Monitor business metrics, not just errors A migrated flow can return no errors and still lose money, for example by silently dropping a field or changing a redirect. Track conversion, completed orders or successful job applications, whatever your product’s key action is, and compare old and new paths while both run. ### Protect the data - Take verified backups before each data step, and test that you can restore them. - Limit who can touch production data during the migration. - Keep a clear record of what moved, when and how. - If you handle personal or regulated data, involve a lawyer or compliance advisor. This article is not legal advice. ### Communicate Tell support and customer-facing staff what is changing and when. Most customer pain during migrations isn’t technical, it’s surprise. A short internal note before each release saves a lot of confusion. ### Freeze what you can Limit new feature work in the areas being migrated. Changes landing in the old code while you replace it create double work and subtle mismatches. A short feature freeze per slice is usually easier than a long one for the whole system. ## Should you modernize in-house, with a contractor or with an agency? There isn’t a universal answer. It depends on your team’s capacity, your timeline and how much institutional knowledge you need to keep. ### In-house team Best for long-term ownership and domain knowledge. The downside is that your engineers are probably also running the product, so modernization competes with daily work, and they may not have done a migration like this before. ### Senior contractor or small team Good when you need experienced leadership for a defined stretch, to set the plan, build the first slices and leave the team with a working pattern. It works best when your own people stay involved, so knowledge doesn’t leave when the contract ends. Full disclosure: I’m a Brazilian engineer myself, so I’m biased toward the nearshore model. It has real advantages, such as time zone overlap with the US, but weigh it against your own context. ### Agency [Useful when you need volume, a mix of skills and project management in one package.](https://filipeeduardo.dev/blog/legacy-modernization-services) The risk is the one you may already know: if the agency owns the knowledge and the accounts, you can end up inheriting a codebase again. If you go this way, require documentation, repository and cloud ownership in your name, and regular handoffs. ### What to check, whichever you choose - Do they start with discovery, or jump straight to a rewrite estimate? - Do they propose a reversible, incremental plan? - Will you own all code, accounts and documentation from day one? - Who is accountable for the money paths during the migration? - Can they show a past migration of a live system, and explain what went wrong in it? Handing a legacy system to a new vendor without a plan is the usual way takeovers go badly. The first 30 days of access, build and money paths decide a lot, so make sure someone does them properly, whoever it is. ## Want a second opinion on your own case? If you’ve inherited a codebase or are planning a migration, email me@filipeeduardo.dev with a short description of your stack and the problem. I’m glad to compare notes and tell you what I’d check first. ## Frequently asked questions ### How long does legacy modernization take? It depends on the size of the system, the quality of the code and how much downtime you can accept. Anyone who gives a firm date before seeing the code is guessing. A time-boxed discovery gives you a much better basis for a timeline, and an incremental plan lets you deliver value along the way. ### Is a full rewrite ever the right choice? Yes, when the system is small, its behavior is well understood, or the old code is so poor that wrapping it costs more than replacing it. For larger live products, incremental migration is usually safer, because the old system keeps earning while you replace it. ### Can we keep shipping features during modernization? Yes, but with limits. Ship in areas you are not migrating, and use short freezes for the slice currently being moved. Mixing big new features into code that is about to be replaced creates double work. ### What should we do before hiring anyone for the migration? Secure access to every repository, account and credential, get a reproducible build, list your money paths, and write down the business reason for modernizing. With that, any partner can give you a more realistic plan, and you can judge it better. ### How do we know the migration is working? Compare against your baseline: time to ship a change, deployment failure rate, incident count, and the business metrics of the migrated flows. If old and new paths show the same results and the team ships faster, it’s working.