Implementing Clean Architecture in Flutter

Clean Architecture is a software design philosophy aimed at creating maintainable, testable, and scalable applications. It decouples the business logic from the UI and other implementation details. Implementing Clean Architecture in Flutter allows you to build robust applications that are easier to understand and modify. This article delves into the core principles of Clean Architecture and provides a practical guide on how to implement it in a Flutter project.

What is Clean Architecture?

Clean Architecture, proposed by Robert C. Martin (Uncle Bob), is a software design paradigm that separates code into layers of abstraction. The central idea is to organize code so that changes to external elements (like UI or database) have minimal impact on the core business logic.

Core Principles of Clean Architecture

• Independence of Frameworks: The architecture doesn’t depend on the existence of some library or framework.
• Testability: The business rules can be tested without the UI, Database, Web Server, or any other external element.
• Independence of UI: You can easily change the UI without changing the system logic.
• Independence of Database: You can switch databases (e.g., from SQLite to PostgreSQL) without affecting the business rules.
• Independence of any external agency: Business rules don’t know anything about the outside world.

Layers in Clean Architecture

Clean Architecture typically includes the following layers:

1. Entities: Contains the business objects of the application. These are core to the domain and are independent of all other layers.
2. Use Cases (Interactors): Encapsulates the specific business rules. It orchestrates the flow of data between the Entities and the presentation layer.
3. Interface Adapters: Converts data from the format most convenient for the Use Cases and Entities, to the format most convenient for some external agency such as the Database or the Web. This layer includes Presenters, Views, and Controllers.
4. Frameworks and Drivers: This layer is composed of frameworks and tools such as the UI, database, and any external interfaces.

Implementing Clean Architecture in Flutter: A Step-by-Step Guide

Step 1: Project Setup

Create a new Flutter project using the Flutter CLI:

flutter create clean_architecture_flutter
cd clean_architecture_flutter

Step 2: Directory Structure

Organize your project with the following directory structure:

lib/
├── core/              # Reusable components
│   ├── errors/
│   ├── usecases/
│   └── utils/
├── data/              # Data layer implementation
│   ├── datasources/
│   ├── models/
│   └── repositories/
├── domain/            # Business logic and entities
│   ├── entities/
│   ├── repositories/  # Abstraction for data operations
│   └── usecases/      # Orchestration of entities
└── presentation/      # UI/Screens (Flutter-specific)
    ├── blocs/          # State management using BLoC pattern
    ├── pages/          # Flutter widgets (screens)
    └── widgets/        # Reusable UI components

Step 3: Define Entities (Domain Layer)

Entities represent the core business objects of your application. These are simple Dart classes.

Example: lib/domain/entities/user.dart

class User {
  final int id;
  final String name;
  final String email;

  User({required this.id, required this.name, required this.email});
}

Step 4: Create Repositories (Domain Layer)

Create abstract classes for your repositories in the domain layer. This defines the contract for data operations.

Example: lib/domain/repositories/user_repository.dart

import '../entities/user.dart';

abstract class UserRepository {
  Future<List<User>> getUsers();
  Future<User> getUser(int id);
}

Step 5: Implement Use Cases (Domain Layer)

Use cases encapsulate the specific business rules and coordinate the interaction between entities and repositories.

Example: lib/domain/usecases/get_users.dart

import '../entities/user.dart';
import '../repositories/user_repository.dart';

class GetUsers {
  final UserRepository userRepository;

  GetUsers(this.userRepository);

  Future<List<User>> execute() {
    return userRepository.getUsers();
  }
}

Step 6: Data Layer Implementation

Implement the data layer, which includes data sources (local and remote), models, and repository implementations.

Data Models

Define data models for mapping JSON data to Dart objects. These are usually used to transfer data between data sources and the repository.

Example: lib/data/models/user_model.dart

import '../../domain/entities/user.dart';

class UserModel extends User {
  UserModel({
    required int id,
    required String name,
    required String email,
  }) : super(id: id, name: name, email: email);

  factory UserModel.fromJson(Map<String, dynamic> json) {
    return UserModel(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
    };
  }
}

Data Sources

Create data sources for retrieving data (e.g., from a REST API or a local database). Define abstract classes and their implementations.

Example: lib/data/datasources/remote_data_source.dart

import '../models/user_model.dart';

abstract class RemoteDataSource {
  Future<List<UserModel>> getUsers();
  Future<UserModel> getUser(int id);
}

class RemoteDataSourceImpl implements RemoteDataSource {
  final http.Client client;

  RemoteDataSourceImpl({required this.client});

  @override
  Future<List<UserModel>> getUsers() async {
    final response = await client.get(Uri.parse('https://jsonplaceholder.typicode.com/users'));
    if (response.statusCode == 200) {
      final List<dynamic> jsonList = json.decode(response.body);
      return jsonList.map((json) => UserModel.fromJson(json)).toList();
    } else {
      throw Exception('Failed to load users');
    }
  }

  @override
  Future<UserModel> getUser(int id) async {
    final response = await client.get(Uri.parse('https://jsonplaceholder.typicode.com/users/$id'));
    if (response.statusCode == 200) {
      final json = json.decode(response.body);
      return UserModel.fromJson(json);
    } else {
      throw Exception('Failed to load user');
    }
  }
}

Repository Implementation

Implement the repository with data sources.

Example: lib/data/repositories/user_repository_impl.dart

import 'package:clean_architecture_flutter/core/errors/exceptions.dart';
import 'package:clean_architecture_flutter/core/network/network_info.dart';
import 'package:clean_architecture_flutter/data/datasources/local_data_source.dart';
import 'package:clean_architecture_flutter/data/models/user_model.dart';
import 'package:clean_architecture_flutter/domain/entities/user.dart';
import 'package:clean_architecture_flutter/domain/repositories/user_repository.dart';
import 'package:dartz/dartz.dart';

class UserRepositoryImpl implements UserRepository {
  final RemoteDataSource remoteDataSource;
  final LocalDataSource localDataSource;
  final NetworkInfo networkInfo;

  UserRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
    required this.networkInfo,
  });

  @override
  Future<List<User>> getUsers() async {
    if (await networkInfo.isConnected) {
      try {
        final remoteUsers = await remoteDataSource.getUsers();
        localDataSource.cacheUsers(remoteUsers);
        return remoteUsers;
      } on ServerException {
        return Left(ServerFailure());
      }
    } else {
      try {
        final localUsers = await localDataSource.getCachedUsers();
        return Right(localUsers);
      } on CacheException {
        return Left(CacheFailure());
      }
    }
  }

  @override
  Future<User> getUser(int id) async {
    // Logic to get a single user (similar to getUsers)
    // Implement network and caching logic here
    throw UnimplementedError();
  }
}

Step 7: Presentation Layer (UI/Screens)

The presentation layer consists of Flutter widgets that display the UI and interact with the BLoCs for state management.

BLoC Implementation

Implement the BLoC (Business Logic Component) for handling UI logic and state management.

Example: lib/presentation/blocs/user_bloc.dart

import 'package:flutter_bloc/flutter_bloc.dart';
import '../../domain/usecases/get_users.dart';
import 'user_event.dart';
import 'user_state.dart';

class UserBloc extends Bloc<UserEvent, UserState> {
  final GetUsers getUsers;

  UserBloc({required this.getUsers}) : super(UserEmpty()) {
    on<LoadUsers>((event, emit) async {
      emit(UserLoading());
      final users = await getUsers.execute();
      if (users != null) {
        emit(UserLoaded(users: users));
      } else {
        emit(UserError(message: 'Failed to load users'));
      }
    });
  }
}

Example: lib/presentation/blocs/user_event.dart

abstract class UserEvent {}

class LoadUsers extends UserEvent {}

Example: lib/presentation/blocs/user_state.dart

import '../../domain/entities/user.dart';

abstract class UserState {}

class UserEmpty extends UserState {}

class UserLoading extends UserState {}

class UserLoaded extends UserState {
  final List<User> users;

  UserLoaded({required this.users});
}

class UserError extends UserState {
  final String message;

  UserError({required this.message});
}

UI Implementation

Create Flutter widgets to display the UI and connect them to the BLoC for state management.

Example: lib/presentation/pages/user_page.dart

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import '../../domain/entities/user.dart';
import '../blocs/user_bloc.dart';
import '../blocs/user_event.dart';
import '../blocs/user_state.dart';

class UserPage extends StatefulWidget {
  @override
  _UserPageState createState() => _UserPageState();
}

class _UserPageState extends State<UserPage> {
  @override
  void initState() {
    super.initState();
    BlocProvider.of<UserBloc>(context).add(LoadUsers());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Users'),
      ),
      body: BlocBuilder<UserBloc, UserState>(
        builder: (context, state) {
          if (state is UserLoading) {
            return Center(child: CircularProgressIndicator());
          } else if (state is UserLoaded) {
            return ListView.builder(
              itemCount: state.users.length,
              itemBuilder: (context, index) {
                User user = state.users[index];
                return ListTile(
                  title: Text(user.name),
                  subtitle: Text(user.email),
                );
              },
            );
          } else if (state is UserError) {
            return Center(child: Text(state.message));
          } else {
            return Center(child: Text('No data'));
          }
        },
      ),
    );
  }
}

Step 8: Dependency Injection

Use a dependency injection framework (such as get_it or provider) to manage dependencies and inject them into the appropriate layers. This helps maintain loose coupling and improves testability.

Example using get_it:

Add get_it dependency in pubspec.yaml:

dependencies:
  get_it: ^7.2.0

Configure dependency injection in lib/injection_container.dart:

import 'package:get_it/get_it.dart';
import 'package:http/http.dart' as http;

import 'data/datasources/remote_data_source.dart';
import 'data/repositories/user_repository_impl.dart';
import 'domain/repositories/user_repository.dart';
import 'domain/usecases/get_users.dart';
import 'presentation/blocs/user_bloc.dart';

final sl = GetIt.instance;

Future<void> init() async {
  // BLoC
  sl.registerFactory(
    () => UserBloc(getUsers: sl()),
  );

  // Use cases
  sl.registerLazySingleton(() => GetUsers(sl()));

  // Repository
  sl.registerLazySingleton<UserRepository>(
    () => UserRepositoryImpl(
      remoteDataSource: sl(),
      localDataSource: sl(), // Assuming you have a LocalDataSource
      networkInfo: sl(),    // Assuming you have a NetworkInfo
    ),
  );

  // Data sources
  sl.registerLazySingleton<RemoteDataSource>(
    () => RemoteDataSourceImpl(client: sl()),
  );

  // Core
  // sl.registerLazySingleton<NetworkInfo>(() => NetworkInfoImpl(sl()));

  // External
  sl.registerLazySingleton(() => http.Client());
  // sl.registerLazySingleton<SharedPreferences>(() async => await SharedPreferences.getInstance());
}

In main.dart, initialize dependency injection:

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'injection_container.dart' as di;
import 'presentation/pages/user_page.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await di.init();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Clean Architecture Flutter',
      home: BlocProvider(
        create: (_) => di.sl<UserBloc>(),
        child: UserPage(),
      ),
    );
  }
}

Advantages of Clean Architecture in Flutter

• Testability: Easier to write unit and integration tests.
• Maintainability: Clear separation of concerns makes code easier to understand and maintain.
• Scalability: Easier to scale the application with changing requirements.
• Framework Independence: Reduced dependency on specific frameworks, providing flexibility to switch frameworks if needed.

Conclusion

Implementing Clean Architecture in Flutter can significantly improve the quality and maintainability of your applications. By following the principles and structuring your project accordingly, you can create robust and scalable applications that are easy to test, understand, and modify. While it might require more initial setup, the long-term benefits in terms of code quality and maintainability make it a worthwhile investment.