Flutter Riverpod Architecture

Goal

Implements scalable Flutter applications using the Feature-First directory structure, Riverpod (with code generation) for state management, and flutter_hooks / HookConsumerWidget for UI composition. Organizes code into four layers — UI, Use Case, Repository, and Data Source — enforcing unidirectional data flow. Applies @Riverpod(keepAlive: true) for global/repository providers and @riverpod for screen-scoped state.

Decision Logic

Before implementing, evaluate the following to determine the correct approach:

Provider scope

• Does the state need to persist across screen navigations, or is it a repository / auth state shared across features?
  • Yes → Use @Riverpod(keepAlive: true)
  • No → Use @riverpod (auto-disposed when no longer watched)

Repository vs. Use Case

• Does the operation simply read/write a single data source with no business rules?