Adopting a Clean Architecture design pattern + suggestions

[dariowskii]

Intro

Hello everyone! I just recently joined the project since I learned that it was made with Flutter 😁

I have been using Flutter professionally for 3 years now, while using it for personal projects since 2018 (I feel old saying that 🥲).

For the past year and a half, I have been in a decision-making role within a team of about 10 Flutter developers.
When the project started, I carefully studied the existing design patterns in order to best collaborate concurrently on the same project.
The choice eventually fell on a Clean Architecture (feature-based), which with proper task management brought tremendous benefits in terms of time and development.

1. Why Clean Architecture in Flutter?

Many Flutter projects start with a simple structure, but as they grow, they become difficult to maintain. Some common problems:

• Highly coupled code → Hard to test and modify
• Reusability issues → Duplicate functionalities or circular dependencies
• Scalability problems → As features increase, the code becomes messy

Advantages of Clean Architecture:

• Separation of concerns → Each layer has a clear responsibility
• Easier testing → Business logic is isolated from UI and data sources
• Scalability → Features are independent, making it easier to add new functionality

Comparison with other architectures:

Architecture	Pros	Cons
MVC	Simple, easy to understand	Can become messy as the project grows
MVVM	Better separation than MVC	ViewModel can become too large
Clean Architecture	Highly modular and scalable	More initial setup, requires discipline

2. Project Structure

In feature-based Clean Architecture, the project is structured by functionality rather than just by layers. Here’s an example folder structure:

lib/
│── core/                 # Shared functionality (e.g., networking, themes, etc.)
│── features/             # Feature-based structure
│   ├── authentication/
│   │   ├── domain/       # Business logic (UseCases, Entities)
│   │   ├── data/         # Repository and data sources
│   │   ├── presentation/ # UI and state management
│   │   ├── auth_module.dart # Dependency injection setup for this feature
│   ├── home/
│   ├── profile/
│── main.dart

✅ Each feature is isolated and independent
✅ Easier to scale by adding/modifying features
✅ Improved testability

3. Domain Layer

The domain layer is the core of business logic and is independent of frameworks or technical details.

Entities

Entities represent the fundamental objects of business logic.

I really suggest to use freezed package to handle entities/models, having the benefits of immutability suggested also by Riverpod itself (see the docs).

@freezed
abstract class Person with _$Person {
  const factory Person({
    required String firstName,
    required String lastName,
    required int age,
  }) = _Person;

  factory Person.fromJson(Map<String, Object?> json) => _$PersonFromJson(json);
}

4. Data Layer

The data layer implements data sources (API, database, etc.) and repositories.

Instead of manually handling API calls, I suggest using retrofit to define the API client

@RestApi(baseUrl: "https://api.example.com")
abstract class AuthApi {
  factory AuthApi(Dio dio, {String baseUrl}) = _AuthApi;

  @POST("/login")
  Future<UserModel> login(@Body() Map<String, String> credentials);
}

// You can serve the repo with a provider like that:
@riverpod
AuthApi authRepository(Ref ref) => AuthApi(Dio());

✅ Less Boilerplate – No need to manually write HTTP requests
✅ Type-Safe API Calls – Enforces structured responses
✅ Automatic Code Generation – Keeps API calls clean and modular

5. Presentation Layer

The presentation layer contains UI and state management.

State Management

For status management, I recommend moving to the code generation version of Riverpod, as it reduces development time and simplifies maintenance.

Conclusion

Adopting this type of architecture would allow moving toward more structured project management, helping in terms of scalability and maintainability.

In addition, I have been able to confirm that this type of architecture is crucial in a project where several people are collaborating at the same time, as it allows working on separate modules while avoiding merge conflicts as much as possible.

I remain available for any questions or to discuss the proposal!

SOCOMUNQUESOOOOOOLDI

[fres-sudo]

Thanks for the deep dive!
Some comments:

Instead of manually handling API calls, I suggest using retrofit to define the API client

I am a big fan of Retrofit but in this phase we don't need to do any API call, so useless now.

I really suggest to use freezed package to handle entities/models

+1 for that

I recommend moving to the code generation version of Riverpod,

+1 also for that

About the Clean Architecture.

I am not a big fan of the Clean Architecture TBH, I would suggest this kind of approach, that basically takes the good part of Clean Architecture, but it remains more flexible. I guess it's called Technical architecture, I don't know, I am not very interested in this kind of naming.

lib/
│── di/                       # Dependency injection
│── errors/                   # All error handling classes and variants
│── i18n/                     # Internazionalization strings
│── misc/                     # Miscellaneous utilities
│   ├── extensions.dart/          # Eventually can became also a folder
│   ├── constants.dart/          # If any
│── mixins/                   # Mixins (if any)
│── models/                   # All error handling classes and variants
│   ├── user/                 # a folder contains all the files for a model (`user.dart`, `user.g.dart`, `user.freezed.dart`)
│   ├── transaction/
│── pages/                    # Divided by "domain" as the following example
│   ├── transaction/          # a folder that contains all the pages related to the transactions
│   │   ├── _widgets          # A folder that is on top of everything and holds all the widgets for that particular domain (that are not being used outside of it)
│   │   ├──add_update_transaction_page.dart 
│   │   ├──transactions_page.dart 
│── repositories/             # Core piece of the app that handle all the business logic, they are being called from the state manager and communicates directly with the service layer, they drive the business logic of the app
│   ├── mappers/              # Contains all the mappers that converts DTOs in Entities (UserDTO -> User and viceversa)
│── routes/                   # Contains the auto_route configuration and all the routes
│── ui/                 
│   ├── widgets/              # Global used widgets
│   ├── typography.dart        
│   ├── colors.dart          
│   ├── assets.dart           # Conversion 1:1 to the assets folder to avoid hardcoding the assets string into the app
│   ├── theme.dart            # Theme configuration
│── providers/                # (or state) contains all the logic for the state managing
│── services/               
│   ├── dtos/                 # Contains all the DTOs in this case they are DAOs
│   ├── local/                # For example: package_info_plus utilities
│   ├── storage/              # Shared pref storage or others
│   ├── networks/             # Retrofit classes if any
│   ├── database/             # Database connections and service realted to DAOs (ex: transaction_service.dart that contains all the queries for the transactions
│── main.dart

Please read all the comments for better context.

This is usually my setup, it scales pretty well also for very large apps.

Ofc it's a proposal, we can iterate on top of it, and we can merge it with the Clean Architecture one.

[dariowskii]

Hi @fres-sudo!

It looks like a really interesting architecture, even at a glance it looks to me like it can scale really well.

In fact everything here is separated by “categories” (more or less).

Here the only thing that scares me is that it may become difficult to contribute to the project while avoiding merge problems, since there are “larger categories” instead of “smaller categories” (i.e., features).

This is just the first hot impression, I am also open to comparison and ready to be taken apart 😁

[fres-sudo]

Here the only thing that scares me is that it may become difficult to contribute to the project while avoiding merge problems, since there are “larger categories” instead of “smaller categories” (i.e., features).

wdym by merge problems? Can you provide an example scenario in which this architecture can cause some issue for a new contributor?

[dariowskii]

I tried to imagine a scenario, but I'll be honest, I didn't find it 😅

It was most likely an impression from a first glance.

Using clean architecture (feature-based) for so long, it just seems to me that everything is a bit scattered, but surely it's a personal bias at this point due to habit 🥲