Book entity

Domain Layer

08:35

Summary

This lesson introduces the Entity as the foundational building block of the Domain layer in Clean Architecture. It clarifies the common confusion between a Model and an Entity, emphasizing that a Model is responsible for parsing external data (like JSON from an API), whereas an Entity is shaped strictly by the data requirements of the user interface. By looking solely at the UI mockup, a BookEntity is constructed to hold exactly the fields needed for display, remaining completely agnostic of the data source. The lesson concludes with a reminder to apply the KISS (Keep It Simple, Stupid) principle, advising against over-engineering when architectural complexity isn't warranted.

Key Ideas

Entity acts as the core data structure of the Domain layer and the starting point for implementation.
Model handles data serialization (e.g., fromJson) and is strongly coupled to external data sources like APIs.
Entity is driven purely by the Presentation layer's visual needs, representing the exact data required to render the UI.
Separation of Model and Entity decouples the UI from backend API changes, though it introduces intentional boilerplate.
Dart's num type acts as a safeguard for numeric API values that might arrive unpredictably as either int or double.
KISS (Keep It Simple, Stupid) principle dictates that architectural layers (like separating Models and Entities) should be omitted if the application's complexity does not strictly require them.

Code Snippets

The BookEntity class representing the UI data requirements for a book.dart

class BookEntity {
  final String image;
  final String title;
  final String authorName;
  final num price;
  final num rating;

  BookEntity(this.image, this.title, this.authorName, this.price, this.rating);
}

Architecture Insight

Architecture insight

An Entity is what the rest of the app agrees a "Book" is. A Model is one specific encoding (JSON from Google Books, a Hive record, a Firestore document). Keeping them separate means the API can rename volumeInfo.title to bookTitle without the UI noticing.

The instructor's pragmatic shortcut — shaping the entity from UI mockups — is fine for a UI-driven app, but pure CA has the entity reflect business rules first. A Book entity in a bookstore conceptually has a price even if no current screen shows it.

Looking ahead — When BookModel lands in the data layer, it should extends BookEntity so the repo can return entities without a manual map step.

My Notes

Model vs Entity distinction: The instructor's pragmatic approach (building Entities by looking at UI mocks) is a highly effective way for beginners to grasp the concept, even if it slightly deviates from strict DDD where Entities are pure business concepts.
Use of num: Using num for price and rating is a smart Dart-specific safeguard. JSON parsers often throw errors if an integer (e.g., 4) is parsed directly into a double without .toDouble(). num cleanly handles both 4 and 4.5.
[Editor's note] Layer dropping (KISS): The advice to drop unnecessary layers is crucial. Over-engineering a simple CRUD app with full Clean Architecture is a common anti-pattern. If the API model perfectly maps 1:1 to the UI, merging Model and Entity is a valid architectural decision for smaller scopes.