Taming Legacy Code in Flutter: Our Refactoring Framework for Enterprise Flutter Projects

"Legacy code" and "Flutter" are two terms you might not expect to see together. How could a technology that's still relatively young produce legacy code? The answer is simple: success.

Enterprise applications that succeed are the ones that grow, evolve, and adapt to market demands. This often means rapid development cycles, changing requirements, and expanding teams. Over time, this intense pace inevitably creates technical debt. This is not unique to Flutter, but rather a common software development pitfall that’s present in all technologies. Code that was once a quick solution becomes a long-term problem. Features that were clear become entangled. Onboarding new developers slows down as the project's complexity grows.

At LeanCode, we've partnered with numerous enterprise clients to build and scale their Flutter applications. We’ve seen those problems firsthand. In response, we've developed a structured, battle-tested framework for taming legacy code and refactoring existing projects, saving them from a costly rewrite.

Our proven 4-level framework for Flutter refactoring

We like to visualize our framework as a pyramid. To tackle the most complex problems at the top, we must first strengthen the foundations. Without basic code quality principles in place, it’s impossible to effectively execute large-scale refactorings or transform the organization's engineering culture.

Level 1: Code Quality

When our team at LeanCode is brought in on a rescue mission to tackle a project struggling with technical debt, we don't start by debating high-level architectural diagrams - we first need to dive straight into the code at the lower level. By examining individual files, methods, and classes, we assess the general state of the codebase and identify fundamental quality issues and code smells - duplicated code, dependency hell, inconsistent formatting, and other anti-patterns that serve as symptoms of deeper problems.

Let's be clear: fixing these issues alone won’t heal the entire project. However, this is the essential first step. You cannot build a stable house by putting up new walls on a cracked and crumbling foundation. This process is built on several key actions, which can include:

Robust Automated Linting

This is our first and most crucial step. We introduce a strict, comprehensive set of linting rules that serve as an automated code reviewer, catching errors as code is written. Some legacy projects either don’t have linting configured or they use only a small subset of its possibilities. At LeanCode, we often introduce our open-source package, leancode_lint, which is designed to enforce best practices for modern, scalable Flutter apps.

We then supplement this with custom lints tailored to the project's specific domain and architecture. For example, we use rules that forbid the usage of built-in Flutter components like Color or Text in place of project-specific equivalents (AppColor, AppText), which have strict APIs and allow only UI styles that are defined by designers in the design system. Lints can catch many things, from simple style violations to complex architectural mistakes, ensuring a consistent standard of the whole codebase. Lints are also extremely useful for AI-assisted development, as AI will try to auto-fix all linting issues for generated code.

Enforced Formatting

Every codebase should have a single, unified style. The dart format tool provides this out of the box, and its use should be non-negotiable. It is sometimes forgotten when setting up a new project, and this can lead to a codebase that’s inconsistent and hard to read. By integrating it into an IDE config, a pre-commit hook, and a CI/CD pipeline, we ensure that no unformatted code ever reaches the main branch. This simple step eliminates all debates about brace placement or line length, reducing cognitive load and making the code easier to navigate.

Code Metrics Monitoring

To find out which parts of the codebase are most problematic and to verify whether, after introducing new standards, the quality doesn’t decline, it’s good to set some automatic monitoring for metrics such as cyclomatic complexity or file and methods length.

Level 2: Structural Refactorings

Once the overall code quality improves, we can start building the core structure for the application's future. This stage focuses on creating consistent, reusable, and easy-to-maintain components, moving beyond just fixing lines of code. Our goals are to eliminate code duplication, ensure a unified design throughout the app, and make significant changes easier and safer to handle.

UI Audit & Refactoring the Design System

A crucial challenge arises when applications lack a well-designed design system. This often forces developers to create UI components independently, leading to significant miscommunication and duplicated effort because it's unclear whether a desired component already exists in the codebase.

Therefore, a critical first step involves performing a UI audit to identify issues that exist in Figma or other design tools before any code is refactored. There must be a direct, one-to-one correspondence between the components and styles defined in Figma and their implementation in the code to ensure consistency and efficiency. We can then use golden tests (UI snapshot tests) to prevent future visual regressions.

Automated Migrations with Codemods

Enterprise codebases can contain thousands of instances of a single pattern or widget. When that pattern needs to change, doing so manually is incredibly risky, as it might cause regressions. We leverage tools like codemod to perform large-scale, AST-based (Abstract Syntax Tree) refactorings. Imagine you need to change the API of an AppButton widget used thousands of times across the app. A codemod script can perform this change flawlessly in seconds, a task that would take a developer days of manual, error-prone work. Codemods are also completely predictable and can be thoroughly tested, making them safer than just asking the AI to perform the migration.

Managed Deprecations

A healthy codebase evolves, which means old code must be retired gracefully. We establish a formal process for deprecation. When a better pattern emerges, the old one is marked with the @Deprecated annotation, including a message that clearly directs the developer to the new approach (@Deprecated('Use NewAwesomeWidget instead. This will be removed on 12.12.2025.')). This provides a clear migration path, allows teams to plan for removing the technical debt, and prevents new code from being written using outdated patterns.

AI-powered Assistance

We are moving beyond simply writing code - with AI IDEs such as Cursor or Claude Code, we are now teaching AI to generate our code. To do this, we deploy LeanAI, our proprietary AI-assisted development framework, built on custom rules and context tailored for these tools.  LeanAI is deeply integrated with our entire development process, linking directly to our Figma MCP server and a set of architectural standards. 

The result is that when a developer requests the AI to "create a screen to display user profiles," it doesn't produce generic Flutter code. Instead, it generates code that utilizes our custom UserProfileCard widget, retrieves data via our established UserRepository, and manages state with our UserCubit. This approach significantly boosts productivity while simultaneously enforcing architectural consistency and code quality.

Level 3: Architectural Refactorings

This level represents the most strategic and high-impact changes we can make to a codebase. Unlike universal best practices at lower levels, the points here are highly project-specific. Not every app needs a monorepo or a new state management solution. These are surgical, high-effort initiatives chosen to solve a project's deepest and most painful problems. When executed correctly, these changes truly rescue a project from the grip of "spaghetti code," bringing a new level of quality and velocity to the entire development team.

Repository Structure (Polyrepo, Monorepo)

The way code is organized in repositories can become a major bottleneck. For example, we worked with a client whose mobile app, web app, and several shared libraries were split across 60+ different repositories (a polyrepo). This setup became their main blocker; a simple change in a shared library required updating dependencies in multiple places, coordinating releases, and navigating a complex web of versioning. Development drastically slowed down. The solution was a major architectural refactoring: migrating the entire ecosystem into a monorepo managed with a tool like Melos. This created a single source of truth, enabled atomic commits across projects, and dramatically simplified dependency management. The change unblocked their teams and restored development momentum.

State Management

State management is often the heart of a Flutter application's complexity. A solution that worked for a prototype will buckle under the weight of dozens of interconnected features. We guide teams through a careful analysis of their current solution's pain points (e.g., poor testability, lack of separation of concerns) and orchestrate a gradual, controlled migration to a more robust and scalable solution like Bloc, refactoring one feature at a time to minimize risk.

Establishing Architectural Decision Records (ADR)

Why did we choose Bloc over Riverpod? Why did we migrate to a monorepo? In a long-running project, the reasoning behind critical decisions often gets lost. An Architectural Decision Record (ADR) is a simple, lightweight document (often a Markdown file in the repo) that captures the context, decision, and consequences for a significant architectural choice. Maintaining ADRs is crucial for onboarding, consistency and future-proofing our decisions.

Level 4: Culture Change

The ultimate goal of any refactoring effort is not just cleaner code, but a self-sustaining culture of quality. Technology and processes are critical, but it is the team's shared values and daily habits that prevent technical debt from accumulating in the first place. This level is about embedding engineering excellence into the team's DNA.

Code Ownership

We foster a culture of collective ownership, where the entire team feels responsible for the project's success.  Every piece of code must have a defined owner - a specific team responsible for its quality and vision. Their primary role is to review and approve any changes, a process we like to automate with a CODEOWNERS file. For shared infrastructure such as the networking layer or core utilities, we establish a dedicated platform team to act as its owner. This structure ensures accountability for every line of code, preventing neglect and fostering team confidence in contributions.

The "Boy Scout Rule"

We ingrain one simple principle: "Always leave the code better than you found it." This means every small task is an opportunity to make a tiny improvement, e.g., renaming a variable, clarifying a comment, or extracting a small method.

Thorough and Productive Code Reviews

Code reviews are essential for fostering collaboration and knowledge sharing within teams. We evolve them from a primary focus on minor syntax remarks to a more constructive dialogue that benefits all participants. Beyond identifying defects, the objective is to ensure code clarity, maintainability, and adherence to established standards. Furthermore, these reviews provide a valuable opportunity for senior developers to mentor less experienced team members, thereby enhancing the team's overall skill set.

Design-Engineering Partnership

Especially in Flutter, a seamless workflow between design and development is critical. We work to break down silos and create a true partnership. This means establishing a living design system where components in Figma are named and structured identically to their corresponding Flutter widgets. When a designer updates a component, it creates a clear, unambiguous task for a developer. This tight feedback loop eliminates guesswork, reduces endless back-and-forth communication, and results in a more polished and consistent final product.

Testing Strategy

We move beyond the vague goal of "writing more tests" to implementing a strategic testing pyramid. With unit tests at the base, followed by widget & golden tests, ending with end-to-end tests in Patrol, we aim to make the codebase well-tested to prevent from regressions.

It’s a Marathon, Not a Sprint

Dealing with legacy code in a large Flutter project can feel daunting, but it is a solvable problem with a structured plan. By approaching it with our 4-Level Refactoring Pyramid, we systematically move from basic code quality fixes to revolutionary architectural changes, all while building a culture of excellence that prevents the debt from returning.

This framework transforms fragile code into a stable, scalable asset, accelerating growth and empowering your team. If your enterprise Flutter project is showing signs of technical debt or slow development velocity, consider starting with our mobile app audit – a detailed assessment designed to identify refactoring priorities.