DEV Community: Yusuf Umar Hanafi

Understanding Clean Architecture: Models vs Entities in Flutter Applications

Yusuf Umar Hanafi — Thu, 24 Jul 2025 14:32:48 +0000

Introduction

Clean Architecture has become increasingly popular in modern software development, especially for those building scalable and maintainable Flutter applications. One of the most common points of confusion for developers implementing Clean Architecture is understanding the distinction between Models and Entities. While they may seem similar, they serve fundamentally different purposes in a well-structured application.

In this article, we'll explore the key differences between Models and Entities, when to use each, and how they fit into the broader Clean Architecture pattern in Flutter applications. Whether you're new to software architecture or looking to refine your understanding, this guide will help you make better design decisions.

Programming Paradigms in Clean Architecture

Before diving into Models and Entities, it's important to understand the programming paradigms that underpin Clean Architecture:

Object-Oriented Programming (OOP): Clean Architecture leverages encapsulation, inheritance, and polymorphism to create modular, reusable components.
Functional Programming: With libraries like dartz, we incorporate functional concepts such as immutability, pure functions, and algebraic data types (like Either) for more predictable code behavior.
Dependency Inversion Principle: Higher-level modules do not depend on lower-level modules; both depend on abstractions.
Separation of Concerns: Each layer has a specific responsibility, making the system easier to maintain and test.

Setting Up Your Flutter Project

To implement Clean Architecture in Flutter, you'll need several packages. Let's start by setting up our pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  # For functional programming constructs
  dartz: ^0.10.1
  # For value equality
  equatable: ^2.0.5
  # For state management
  flutter_bloc: ^8.1.3
  # For immutable classes
  freezed_annotation: ^2.4.1
  # For dependency injection
  get_it: ^7.6.4
  injectable: ^2.3.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  # For code generation
  build_runner: ^2.4.6
  freezed: ^2.4.5
  injectable_generator: ^2.4.1
  json_serializable: ^6.6.2

After adding these dependencies, run:

flutter pub get

Clean Architecture Layers

Clean Architecture typically consists of three main layers:

Domain Layer: Contains business logic and rules, completely independent of other layers.
Data Layer: Responsible for data retrieval from external sources like APIs or databases.
Presentation Layer: Handles UI and user interaction.

Now let's focus on where Models and Entities fit within these layers.

Entities: The Heart of Domain Layer

What are Entities?

Entities are core business objects within your application domain. They represent the most fundamental business rules and are independent of how the data is stored or presented.

Key characteristics of Entities:

They encapsulate the most critical business rules
They're independent of frameworks or external systems
They don't contain any presentation or data access logic
They should be stable and change rarely

Example Entity in Flutter

Let's create a simple User entity:

import 'package:equatable/equatable.dart';

class User extends Equatable {
  final String id;
  final String name;
  final String email;
  final int age;

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

  @override
  List<Object> get props => [id, name, email, age];
}

Notice that our entity:

Uses Equatable for value equality
Contains only business-relevant data
Has no annotations for JSON serialization or database mapping
Is completely framework-independent

Models: The Bridge in Data Layer

What are Models?

Models are data structures that typically mirror your entities but are designed to work with external data sources. They handle serialization, deserialization, and data conversion between your domain entities and external systems.

Key characteristics of Models:

They're specific to data sources (API, database, etc.)
They handle conversion between external data formats and domain entities
They may contain framework-specific annotations
They can change whenever external interfaces change

Example Model in Flutter

Let's create a UserModel that corresponds to our User entity:

import 'package:freezed_annotation/freezed_annotation.dart';
import '../../domain/entities/user.dart';

part 'user_model.g.dart';
part 'user_model.freezed.dart';

@freezed
class UserModel with _$UserModel {
  const UserModel._();

  const factory UserModel({
    required String id,
    required String name,
    required String email,
    @JsonKey(name: 'user_age') required int age,
  }) = _UserModel;

  factory UserModel.fromJson(Map<String, dynamic> json) => 
      _$UserModelFromJson(json);

  // Convert model to domain entity
  User toEntity() => User(
    id: id,
    name: name,
    email: email,
    age: age,
  );

  // Create model from domain entity
  factory UserModel.fromEntity(User user) => UserModel(
    id: user.id,
    name: user.name,
    email: user.email,
    age: user.age,
  );
}

After creating this file, generate the necessary code:

flutter pub run build_runner build --delete-conflicting-outputs

Note that our model:

Uses freezed for immutability and code generation
Has JSON annotations for serialization
Provides methods to convert between domain entities and models
Is aware of external data formats (like snake_case field names)

Models vs Entities: Key Differences

Now let's compare the two concepts:

Aspect	Entity	Model
Purpose	Represents core business objects	Translates between domain and external data
Layer	Domain	Data
Dependencies	None (pure business logic)	May depend on frameworks or libraries
Serialization	No serialization logic	Handles JSON/XML parsing
Stability	Changes rarely	Changes when external interfaces change
Framework	Framework-independent	May contain framework-specific annotations

Practical Implementation in Clean Architecture

Repository Pattern

The Repository pattern serves as a bridge between your domain and data layers. Repositories deal with entities in their interfaces but use models internally:

import 'package:dartz/dartz.dart';
import '../entities/user.dart';
import '../../core/errors/failures.dart';

abstract class UserRepository {
  Future<Either<Failure, User>> getUserById(String id);
  Future<Either<Failure, List<User>>> getAllUsers();
  Future<Either<Failure, void>> saveUser(User user);
}

And the implementation:

import 'package:dartz/dartz.dart';
import 'package:injectable/injectable.dart';
import '../../domain/entities/user.dart';
import '../../domain/repositories/user_repository.dart';
import '../../core/errors/failures.dart';
import '../datasources/user_remote_data_source.dart';
import '../models/user_model.dart';

@Injectable(as: UserRepository)
class UserRepositoryImpl implements UserRepository {
  final UserRemoteDataSource dataSource;

  UserRepositoryImpl(this.dataSource);

  @override
  Future<Either<Failure, User>> getUserById(String id) async {
    try {
      final userModel = await dataSource.getUserById(id);
      return Right(userModel.toEntity());
    } catch (e) {
      return Left(ServerFailure());
    }
  }

  @override
  Future<Either<Failure, List<User>>> getAllUsers() async {
    try {
      final userModels = await dataSource.getAllUsers();
      return Right(userModels.map((model) => model.toEntity()).toList());
    } catch (e) {
      return Left(ServerFailure());
    }
  }

  @override
  Future<Either<Failure, void>> saveUser(User user) async {
    try {
      final userModel = UserModel.fromEntity(user);
      await dataSource.saveUser(userModel);
      return const Right(null);
    } catch (e) {
      return Left(ServerFailure());
    }
  }
}

Notice how:

The repository interface in the domain layer only deals with entities
The implementation in the data layer converts between models and entities
External systems (data sources) only interact with models, never entities

Best Practices

Keep Entities Simple: Entities should contain only business logic and validation rules, nothing related to external systems.
Models Should Be Disposable: Models can change whenever external APIs change without affecting your core business logic.
Convert Early: Convert models to entities as early as possible, typically in your repository implementation.
One-Way Dependency: Domain entities should never depend on data models; only models should know about entities.
Test Separately: Write separate tests for entities and models to ensure they both work correctly.

Common Pitfalls to Avoid

Using Models Throughout the App: Models should be confined to the data layer; using them in presentation layers breaks clean architecture principles.
Making Entities Aware of Persistence: Entities shouldn't know how they're stored or retrieved.
Missing Conversion Logic: Always ensure you have proper methods to convert between models and entities.
Tight Coupling: Avoid having your domain layer depend on specific data formats or structures.

Conclusion

The distinction between Models and Entities is fundamental to implementing Clean Architecture properly. Entities represent your core business objects and rules, while Models handle the translation between your domain and external systems.

By maintaining this separation, you achieve several benefits:

Your business logic remains isolated from external concerns
Changes to APIs or databases don't affect your core domain
Your code becomes more testable and maintainable
Your application becomes more adaptable to changing requirements

Remember, Clean Architecture is about creating systems that are independent of frameworks, UI, databases, and external agencies. The proper use of Models and Entities is crucial to achieving this independence.

Connect With Me

Source Code - Get example code for this approach
LinkedIn - Connect with me professionally
GitHub - Check out my other open source projects
Instagram - Follow me for behind-the-scenes and daily updates
Telegram - Join my channel for Flutter tips and tricks
Website - Visit my portfolio and blog for more tutorials

Happy coding!

Building Scalable Flutter Apps with Cubit Abstraction: A Practical Guide

Yusuf Umar Hanafi — Thu, 17 Jul 2025 06:45:29 +0000

Introduction

Flutter has become one of the most popular frameworks for cross-platform development, and state management is a crucial aspect of any Flutter application. Among various state management solutions, BLoC (Business Logic Component) pattern has gained significant traction. The Cubit pattern, a simplified version of BLoC, provides an elegant way to manage state without the complexity of events.

In this article, I'll guide you through creating a reusable, abstract Cubit that can significantly reduce boilerplate code while maintaining clean architecture principles. This approach is especially useful for handling listed data that follows the common pattern of loading, success, error, and empty states.

Programming Paradigms at Play

Before diving into implementation details, let's understand the programming paradigms used in our Cubit abstraction:

Object-Oriented Programming (OOP): We use abstract classes and inheritance to create reusable components.
Reactive Programming: The Cubit pattern follows reactive principles, emitting states that UI components can react to.
Functional Programming: We leverage functional concepts like immutable states and the Either type for error handling.
Generic Programming: Our base Cubit is generic (LoadListedDataCubit<T>), making it reusable for different data types.

Package Installation

Let's start by adding the necessary packages to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_bloc: ^8.1.3  # For Cubit implementation
  dartz: ^0.10.1        # For functional programming constructs like Either
  freezed: ^2.4.2       # For immutable state classes
  freezed_annotation: ^2.4.1
  injectable: ^2.1.2    # For dependency injection

dev_dependencies:
  build_runner: ^2.4.6
  freezed_generator: ^2.4.2
  injectable_generator: ^2.1.6

Run the following command to install these dependencies:

flutter pub get

Creating the Abstract Load Listed Data Cubit

The core of our abstraction is the LoadListedDataCubit, which handles the common patterns for loading listed data:

import 'package:dartz/dartz.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:freezed_annotation/freezed_annotation.dart';

import '../../core.dart';

part 'load_listed_data_state.dart';
part 'load_listed_data_cubit.freezed.dart';

abstract class LoadListedDataCubit<T> extends Cubit<LoadListedDataState<T>> {
  LoadListedDataCubit() : super(const LoadListedDataState.initial()) {
    _initial();
  }

  void _initial() async {
    await getData();
  }

  Future getData() async {
    emit(const LoadListedDataState.loading());
    final Either<AppException, List<T>> result = await fetchData();
    result.fold(
      (error) => emit(LoadListedDataState.error(error: error)),
      (itemList) {
        if (itemList.isEmpty) {
          emit(const LoadListedDataState.empty());
        } else {
          emit(LoadListedDataState.success(data: itemList));
        }
      }
    );
  }

  Future<Either<AppException, List<T>>> fetchData();
}

Now let's define the state class:

// filepath: lib/core/cubit/load_listed_data/load_listed_data_state.dart
part of 'load_listed_data_cubit.dart';

@freezed
class LoadListedDataState<T> with _$LoadListedDataState<T> {
  const factory LoadListedDataState.initial() = _Initial;
  const factory LoadListedDataState.loading() = _Loading;
  const factory LoadListedDataState.success({required List<T> data}) = _Success;
  const factory LoadListedDataState.error({required AppException error}) = _Error;
  const factory LoadListedDataState.empty() = _Empty;
}

After defining these files, run code generation:

flutter pub run build_runner build --delete-conflicting-outputs

Understanding the Abstraction

Let's break down what's happening in our LoadListedDataCubit:

Generic Type: <T> allows us to reuse this Cubit for any data type.
Initial State: The constructor sets up an initial state and triggers data loading.
State Management: The Cubit handles five states (initial, loading, success, error, and empty).
Template Method Pattern: The fetchData() method is abstract, while getData() provides the common implementation.
Error Handling: We use the Either type from dartz to handle success and error cases elegantly.

Implementing a Concrete Cubit

Now, let's implement a concrete Cubit for a specific feature, like loading tweets:

import 'package:dartz/dartz.dart';
import 'package:injectable/injectable.dart';

import '../../../../core/core.dart';
import '../../data/models/tweet_response_model.dart';
import '../../domain/usecases/get_tweet_usecase.dart';

@lazySingleton
class TweetCubit extends LoadListedDataCubit<TweetResponseModel> {
  TweetCubit({required GetTweetUsecase getTweetUsecase})
      : _getTweetUsecase = getTweetUsecase;

  final GetTweetUsecase _getTweetUsecase;

  @override
  Future<Either<AppException, List<TweetResponseModel>>> fetchData() async {
    return await _getTweetUsecase();
  }
}

That's it! Notice how little code we needed to write for our TweetCubit. All the common loading, error handling, and state management logic is inherited from the base class.

Using the Cubit in UI

To use our Cubit in the UI, we can do something like this:

// filepath: lib/modules/tweet/presentation/pages/tweet_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

import '../cubit/tweet_cubit.dart';
import '../../../../core/core.dart';
import '../../data/models/tweet_response_model.dart';

class TweetPage extends StatelessWidget {
  const TweetPage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => getIt<TweetCubit>(),
      child: Scaffold(
        appBar: AppBar(title: const Text('Tweets')),
        body: BlocBuilder<TweetCubit, LoadListedDataState<TweetResponseModel>>(
          builder: (context, state) {
            return state.maybeWhen(
              initial: () => const SizedBox(),
              loading: () => const Center(child: CircularProgressIndicator()),
              empty: () => const Center(child: Text('No tweets available')),
              error: (error) => Center(child: Text('Error: ${error.message}')),
              success: (tweets) => ListView.builder(
                itemCount: tweets.length,
                itemBuilder: (context, index) => ListTile(
                  title: Text(tweets[index].text),
                  subtitle: Text(tweets[index].author),
                ),
              ),
              orElse: () => const SizedBox(),
            );
          },
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () => context.read<TweetCubit>().getData(),
          child: const Icon(Icons.refresh),
        ),
      ),
    );
  }
}

Benefits of This Approach

DRY (Don't Repeat Yourself): Eliminates boilerplate code across multiple features.
Consistency: Ensures consistent handling of loading, success, error, and empty states.
Separation of Concerns: Keeps business logic separate from UI.
Testability: Makes testing easier with clearly defined states and behaviors.
Scalability: New features can be added with minimal code.
Maintainability: Changes to the core loading logic only need to be made in one place.

Advanced Usage

You can extend this pattern for more complex scenarios:

Pagination: Add pagination methods to the base Cubit.
Filtering and Sorting: Implement methods for data manipulation.
Caching: Add caching mechanisms to the base implementation.

Conclusion

The abstract Cubit pattern is a powerful way to reduce boilerplate code in Flutter applications while maintaining clean architecture principles. By leveraging OOP concepts like abstraction and inheritance along with reactive and functional programming approaches, we can build more maintainable and scalable apps.

This pattern is especially useful for teams working on medium to large-scale applications where consistent state management across features is essential. It helps enforce best practices and ensures that all developers follow the same patterns.

Happy coding!

If you found this article helpful, please consider following me for more Flutter and Dart content. Share your thoughts and questions in the comments below!

Connect With Me

Source Code - Get the complete source code for this project
LinkedIn - Connect with me professionally
GitHub - Check out my other open source projects
Instagram - Follow me for behind-the-scenes and daily updates
Telegram - Join my channel for Flutter tips and tricks
Website - Visit my portfolio and blog for more tutorials