I joined a large, multi-year Flutter project six months ago. The team was five Flutter devs when I started; it's grown to ten since. I didn't drive most of the engineering decisions in this post; more senior teammates did that work, some of it years before I arrived. But watching it happen, and working inside the systems that came out of it, taught me more about real-world software engineering than any tutorial or side project ever did. This is that story.
The codebase I walked into
The app is a consumer health & wellness product: habit tracking, nutrition logging, workouts, a proprietary health score, the works. It had been in active development for years by the time I joined, with 20+ feature modules and a lot of accumulated history. Some of that history was clean. Some of it wasn't.
What I noticed in my first few weeks:
- One or two enormous "umbrella" feature folders that had absorbed years of unrelated functionality, because it was easier to add one more file than to figure out where things should live
- Legacy data models built on heavy code-generation tooling that people were visibly reluctant to touch
- Modules with fuzzy boundaries, where the same piece of state could get read and mutated from several unrelated screens, so a small change in one place could break something in another
- Places where the app quietly assumed a network connection was always available, so an action taken on bad signal could go missing instead of failing loudly
- Hardcoded colors and font sizes on some screens instead of theme references
- Raw platform widgets mixed in with the app's actual design components, so buttons didn't always look like buttons
What I noticed pretty quickly was that some parts of the app were much easier to work in than others, and it turned out that wasn't random.
The thing that made the biggest impression on me: a lint rule
The part of this codebase I keep thinking about is the design system, not because I built it, but because I got to see what it made possible.
The team has a canonical set of shared widgets (card, button, and semantic text components) backed by custom static-analysis lint rules. If you use a raw platform widget, a hardcoded color, or a literal string instead of the shared components, your code doesn't pass analysis. Not a style guide. Not a review comment. An actual failure.
I didn't build this system, but I've lived inside its consequences. During my time on the team, the app went through a full brand refresh: new theme tokens, new typography, new component styling, applied across an app with years of history, and it happened while the app kept shipping releases, without a dedicated freeze. Because most screens were already required to consume shared widgets and theme tokens, a huge amount of the visual change happened centrally, in the design-system layer, instead of screen by screen.
Seeing that land was the first time I really understood the difference between code that works and code that's built to change. The lint rule that probably felt like an annoying gate to whoever wrote it years earlier is the reason a brand refresh didn't turn into a six-week fire drill.
Other things I watched happen (and learned from, more than contributed to)
I want to be honest about scope here: I was one developer on a team that's grown to ten, working on pieces of a much bigger effort. A few things I got to observe up close:
- Feature-folder architecture. Each domain (nutrition, exercise, scoring, consent, and so on) is its own self-contained module with its own screens, controllers, and services. This made the codebase legible in a way I didn't fully appreciate until I later worked in a messier corner of it.
- Legacy folder decomposition. Two old "catch-all" folders were being broken apart while I was on the team: usage was mapped first, low-risk files migrated first, and temporary re-export shims were used on the files with lots of dependents so nothing broke in one big move. I mostly watched this from the sidelines, but it changed how I think about "safe" refactors.
- Offline-first tracking. Habit and workout logging needs to keep working at the gym or with bad signal, so there's a local queue and reconciliation layer under the hood. I didn't build this, but debugging around it taught me a lot about why "just retry the request" isn't a real offline strategy.
- Externalized content. No hardcoded copy or asset paths in UI code. Small, but it meant I could fix a string without touching a build.
What six months on this team taught me
If I had to compress it into a few things:
- The most valuable engineering decisions are often boring. A lint rule isn't a highlight reel. It's the reason a brand refresh didn't need a freeze, months or years later.
- You can learn architecture by living inside it, before you're the one designing it. I didn't write the feature-folder structure or the shim strategy for the legacy migration, but working inside both taught me what "good" actually looks like in practice, not just in theory.
- Watching a team scale alongside a codebase is its own education. Seeing the team roughly double in size while the codebase stayed navigable told me a lot about scaling people and code together, not just in isolation.
- Credit belongs where the work happened. A lot of what made this app easier to work in was decided before I ever touched the repo. Worth saying plainly instead of writing myself into a bigger role than I had.
I'm still early in this project and still learning most days. But six months inside a codebase that was built to absorb change, rather than resist it, taught me what to look for, and build toward, wherever I end up next.
This post describes patterns from a real production Flutter app; specific product, company, and partner names have been generalized for confidentiality.