Clean Architecture; How To Keep Your Codebase Scalable Without Overengineering

Clean Architecture has turned into the “eat more protein” advice of software engineering. Everyone repeats it. Everyone shares the same circle diagram. Almost no one talks about what it’s actually like to build something with it.

When I first tried applying it, I kept asking myself: am I writing better code or just more files?

Most articles treat Clean Architecture like a theory exam, abstract entities, endless layers, and rules that fall apart the moment a real feature ships. But I don’t write code for diagrams. I write code that has to change, stay testable, and not drive me insane as the product grows.

So instead of another diagram, I want to talk about what Clean Architecture looks like in practice the parts worth keeping, the parts that just slow you down, and how to evolve a version that actually works in real projects.

What The Layers Actually Look Like

In my current project, a fairly large one, I’ve settled on a structure that’s simple enough to reason about but strong enough to grow. It follows the usual three layers: presentation, domain, and data. What matters most isn’t the names or number of layers, but how they depend on each other and how responsibilities are divided.

==This setup is tuned for mobile development. If you’re working on a web app, the same ideas apply, but the outer layers will look a little different. Where I have background services, local database managers, and offline sync, a web app might rely on browser storage, API caching, or server-driven state. The principles stay identical clean but the implementation details shift with the platform.==

1. The presentation layer handles the user-facing side: screens, widgets, and a View Model (VM) for each feature. The VM only talks to the domain layer. That rule alone prevents a lot of accidental coupling and keeps UI code clean.
2. The domain layer defines how the app behaves. It contains all use cases, small, focused pieces of logic that represent what the app does. It also declares the repositories, which act as boundaries between the domain and data layers. The data layer can’t just do whatever it wants; it has to conform to these promises. If there’s code in the data layer that no one calls, it simply dies off on its own.
3. The data layer provides the actual implementations for those repositories. These call into managers that handle background events, local storage, and communication with external systems through the background service. The background service, in turn, keeps things running smoothly, syncing data, writing to the database, and managing API calls, without the rest of the system needing to know the details.

All entities live in the domain, shared across layers. That keeps data models consistent and avoids the constant mapping that usually clutters large codebases.

This setup may look heavy at first, but in practice it saves time and stress. Clear boundaries make it easier to change things without worrying about breaking something unrelated. When a new feature comes in, I know exactly where it belongs. If a bug shows up, I can usually trace it to the right layer within minutes.

Over time, this separation of concerns has proven to be the main reason the codebase stays manageable. It’s not about following a pattern perfectly, it’s about keeping the system loosely coupled enough that it can keep growing without turning fragile.

What I Learned the Hard Way

Early on, I thought Clean Architecture was about layers and abstractions. It’s not. It’s about staying in control when your codebase starts growing faster than you can refactor. Here are some of the things I learned, some of these may sound like “this is implied, duh”, let me tell you this: IT WAS’NT, at least to me.

1. A layer is only useful if it protects you from something, framework churn, backend changes, or accidental coupling. If it doesn’t, it’s just ceremony.

2. Abstractions should earn their place, Don’t create a repository interface unless you can imagine a second implementation. Theoretical flexibility is just another word for clutter.

3. Domain should never depend on UI frameworks or database details. Every time I ignored that rule, debugging felt like trying to untie headphones.

   This structure doesn’t make development faster, it makes it sane. You actually see this pay off when you’re shifting your backend to another platform or maybe redoing your entire UI, THE APP SURVIVES AND SO DO YOU!

\