Flutter Clean Architecture Example

The project is divided into three distinct layers. To maintain separation of concerns, data is mapped between layers using specialized objects (DTOs, Entities, and States).

1. Presentation Layer (UI)

Contains the Flutter framework code, Widgets, and state management logic. It is responsible for:

• Managing application state.
• Handling UI aspects (navigation, internationalization, updates).
• Using States classes to represent the UI data.

2. Domain Layer

The core business logic layer. It is a pure Dart module with no external dependencies. It includes:

• Entities: Core business objects (e.g., Character) with properties and methods.
• Use Cases: Classes that encapsulate specific business logic (e.g., GetAllCharacters) and coordinate data flow.
• Repository Interfaces: Abstractions that define how data should be accessed without knowing the implementation details.

3. Data Layer

Acts as the boundary to the external world. It includes:

• Repository Implementations: Concrete logic for the interfaces defined in the Domain layer.
• Data Sources: Network or database calls.
• DTOs (Data Transfer Objects): Simple containers used for JSON serialization/deserialization.
• Caching & Coordination: Managing data flow between local and remote sources.

The _Content widget (a private StatefulWidget) manages the character list and implements infinite scrolling logic using a ScrollController.

Key Behaviors:

1. Data Selection: It selects both the characters list and the hasReachedEnd boolean from the CharacterPageBloc state.
2. Pagination: It listens to scroll events via _onScroll. When the user scrolls to within 90% of the bottom of the list (_isBottom), it dispatches a FetchNextPageEvent to the CharacterPageBloc to load more data.
3. List Rendering:
   • It uses a ListView.builder.
   • If hasReachedEnd is false, it adds an extra item to the list to show a CharacterListItemLoading indicator at the bottom.
   • The first item (index 0) is rendered with a CharacterListItemHeader.
4. Navigation: Tapping a CharacterListItem triggers _goToDetails, which uses CharacterDetailsPage.route(character: character) to navigate to the details screen.

// Inside __ContentState
void _onScroll() {
    if (_isBottom) {
      pageBloc.add(const FetchNextPageEvent());
    }
}

bool get _isBottom {
    if (!_scrollController.hasClients) return false;
    final maxScroll = _scrollController.position.maxScrollExtent;
    final currentScroll = _scrollController.offset;
    return currentScroll >= (maxScroll * 0.9);
}

To display a list of characters, use the CharacterPage widget. It follows a standard Bloc pattern where the CharacterPageCubit is provided via BlocProvider and initialized by calling fetchNextPage().

Key components of this implementation:

• Initialization: The CharacterPage injects GetAllCharacters (a domain use case) into the CharacterPageCubit.
• State Management: The UI uses context.select to react to changes in CharacterPageCubit.state.status, state.characters, and state.hasReachedEnd.
• Pagination: Infinite scrolling is implemented by attaching a ScrollController to a ListView.builder. When the user scrolls past 90% of the maxScrollExtent, pageCubit.fetchNextPage() is triggered.
• Navigation: Tapping a character item uses CharacterDetailsPage.route(character: character) to navigate to the details view.

// To use the character list page in your widget tree:
const CharacterPage()

To implement a character list page following the MobX pattern in this project, you should separate the page into three distinct parts: a StatelessWidget for dependency injection, a StatefulWidget (View) for lifecycle management, and a private StatefulWidget (Content) for UI rendering and scroll handling.

1. Dependency Injection: Use a StatelessWidget to instantiate the CharacterPageStore, passing in required domain use cases (e.g., GetAllCharacters) retrieved via context.read().
2. Lifecycle Management: Use a StatefulWidget to trigger initial data fetching in initState using WidgetsBinding.instance.addPostFrameCallback to ensure the store's fetchNextPage() is called after the first frame.
3. Reactive UI: Wrap the UI in an Observer widget from flutter_mobx. Use the store's contentStatus to toggle between a loading indicator and the main content.
4. Pagination: Implement infinite scrolling by attaching a ScrollController to a ListView.builder. When the user scrolls near the bottom (e.g., 90% of the way), call store.fetchNextPage().

Note: The store's charactersList and hasReachedEnd properties should drive the list length and the visibility of loading indicators at the end of the list.

// 1. The Entry Point (Dependency Injection)
class CharacterPage extends StatelessWidget {
  const CharacterPage({super.key});

  @override
  Widget build(BuildContext context) {
    return CharacterView(
      store: CharacterPageStore(
        getAllCharacters: context.read<GetAllCharacters>(),
      ),
    );
  }
}

// 2. The View (Lifecycle)
class CharacterView extends StatefulWidget {
  const CharacterView({super.key, required this.store});
  final CharacterPageStore store;

  @override
  State<CharacterView> createState() => _CharacterViewState();
}

class _CharacterViewState extends State<CharacterView> {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      widget.store.fetchNextPage();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Observer(
      builder: (_) => widget.store.contentStatus == CharacterPageStatus.loading
          ? const Center(child: CircularProgressIndicator())
          : _Content(store: widget.store),
    );
  }
}