DEV Community

Cover image for 🚀 Flutter Riverpod Clean Architecture: The Ultimate Production-Ready Template for Scalable Apps
Sohanuzzaman Soad
Sohanuzzaman Soad

Posted on

🚀 Flutter Riverpod Clean Architecture: The Ultimate Production-Ready Template for Scalable Apps

#flutter #dart #appdev #programming

Hi Flutter devs! 👋

Are you tired of wrestling with messy codebases, unclear folder structures, and state management headaches? I’ve been there too. That’s why I built the Flutter Riverpod Clean Architecture template—a modern, production-ready starter kit that helps you build robust, scalable, and maintainable Flutter apps, faster than ever.

🏆 What Makes This Template Stand Out?

1. Clean Architecture, Done Right

  • Separation of Concerns: Features, core logic, and infrastructure are clearly separated.
  • Feature-First Structure: Each feature is isolated, making it easy to add, remove, or refactor without breaking the rest of your app.
  • Testability: Business logic is decoupled from UI, so you can write meaningful unit and integration tests.

2. Riverpod 2.0+ for State Management

  • Modern & Robust: Riverpod is the go-to for scalable, testable, and reactive state management.
  • Provider Organization: All providers are organized by feature, not by type, for maximum clarity.
  • Async & Sync Support: Easily handle both synchronous and asynchronous state.

3. Localization & Theming

  • Built-in Localization: Add new languages in minutes. All strings are externalized and ready for translation.
  • Dark/Light Mode: The template comes with beautiful, accessible themes for both light and dark users.

4. Production-Ready Out of the Box

  • CI/CD Scripts: Automated scripts for building, testing, and generating documentation.
  • Modern Documentation: The docs site uses glassmorphism, gradients, and dark mode for a stunning developer experience.
  • Example Features: Real-world examples (auth, onboarding, etc.) to help you get started.

5. Comprehensive Testing

  • Unit, Widget, and Integration Tests: Examples included for every layer.
  • Mocking & Dependency Injection: Easily swap out implementations for testing.

🗂️ Folder Structure Overview 

lib/
├── core/         # Shared services, utilities, and cross-cutting concerns (e.g., networking, error handling, theming)
├── features/     # Each app feature in its own folder, fully isolated
│   └── feature_name/
│       ├── data/         # Data sources, models, and repositories (API, DB, etc.)
│       ├── domain/       # Business logic: entities, repositories, use cases
│       └── presentation/ # UI widgets, screens, and Riverpod providers
├── examples/     # Example implementations and UI showcases
├── l10n/         # Localization files and delegates
├── gen/          # Generated code (if any)
└── main.dart     # App entry point
Enter fullscreen mode Exit fullscreen mode

✨ Key Features at a Glance

  • ✅ Riverpod 2.0+: Modern, robust state management
  • ✅ Clean Architecture: Feature-first, scalable structure
  • ✅ Localization: Easy multi-language support
  • ✅ Dark/Light Themes: Beautiful, accessible UI
  • ✅ Comprehensive Testing: Unit, widget, and integration
  • ✅ CI/CD Ready: Automated scripts and workflows
  • ✅ Modern Docs: Beautiful, accessible, and interactive

🚦 Quick Start 

git clone https://github.com/ssoad/flutter_riverpod_clean_architecture.git
cd flutter_riverpod_clean_architecture
flutter pub get
Enter fullscreen mode Exit fullscreen mode

📸 Documentation Preview

The documentation landing page is designed for clarity and beauty, with bold gradients, glassmorphism, and full dark mode support.

Image description

Code Generation Tools

The template includes several powerful CLI tools to automate repetitive tasks. Let's explore each one with practical examples.

1. Feature Generator (generate_feature.sh)

The feature generator is the most versatile tool, allowing you to scaffold new features with different architectural patterns.

Basic Usage 

./generate_feature.sh --name user_profile
Enter fullscreen mode Exit fullscreen mode

This creates a complete feature with Clean Architecture layers:

  • Data layer (repositories, data sources, models)
  • Domain layer (entities, repository interfaces, use cases)
  • Presentation layer (screens, widgets, UI providers)
  • Tests for each layer
  • Documentation

Different Feature Types

The generator supports various feature types to match your needs:

Clean Architecture Feature (Default) 

./generate_feature.sh --name user_auth
Enter fullscreen mode Exit fullscreen mode

This creates:

lib/features/user_auth/
├── data/
│   ├── datasources/
│   │   ├── user_auth_remote_datasource.dart
│   │   └── user_auth_local_datasource.dart
│   ├── models/
│   │   └── user_auth_model.dart
│   └── repositories/
│       └── user_auth_repository_impl.dart
├── domain/
│   ├── entities/
│   │   └── user_auth_entity.dart
│   ├── repositories/
│   │   └── user_auth_repository.dart
│   └── usecases/
│       ├── get_all_user_auths.dart
│       └── get_user_auth_by_id.dart
├── presentation/
│   ├── providers/
│   │   └── user_auth_ui_providers.dart
│   ├── screens/
│   │   ├── user_auth_list_screen.dart
│   │   └── user_auth_detail_screen.dart
│   └── widgets/
│       └── user_auth_list_item.dart
└── providers/
    └── user_auth_providers.dart
Enter fullscreen mode Exit fullscreen mode

Simplified Feature (No Repository Pattern) 

./generate_feature.sh --name theme_switcher --no-repository
Enter fullscreen mode Exit fullscreen mode

This creates a simpler structure without the repository pattern:

lib/features/theme_switcher/
├── models/
│   └── theme_switcher_model.dart
├── presentation/
│   ├── providers/
│   │   └── theme_switcher_ui_providers.dart
│   ├── screens/
│   │   └── theme_switcher_screen.dart
│   └── widgets/
│       └── theme_switcher_widget.dart
└── providers/
    └── theme_switcher_providers.dart
Enter fullscreen mode Exit fullscreen mode

UI Component Only 

./generate_feature.sh --name custom_button --ui-only
Enter fullscreen mode Exit fullscreen mode

Perfect for reusable UI components:

lib/features/custom_button/
├── models/
│   └── custom_button_model.dart
├── presentation/
│   ├── providers/
│   │   └── custom_button_ui_providers.dart
│   └── widgets/
│       └── custom_button_widget.dart
└── providers/
    └── custom_button_providers.dart
Enter fullscreen mode Exit fullscreen mode

Service Only 

./generate_feature.sh --name analytics_service --service-only
Enter fullscreen mode Exit fullscreen mode

Ideal for utility services:

lib/features/analytics_service/
├── models/
│   └── analytics_service_model.dart
├── services/
│   └── analytics_service_service.dart
└── providers/
    └── analytics_service_providers.dart
Enter fullscreen mode Exit fullscreen mode

Additional Options

You can combine options to customize the generated feature:

# Generate without UI (for background services)
./generate_feature.sh --name notification_handler --no-ui

# Skip test files generation
./generate_feature.sh --name quick_prototype --no-tests

# Skip documentation generation
./generate_feature.sh --name internal_utility --no-docs

# Minimal feature (no UI, tests, or docs)
./generate_feature.sh --name formatter --no-ui --no-tests --no-docs
Enter fullscreen mode Exit fullscreen mode

2. Test Generator (test_generator.sh)

The test generator automates testing workflows and generates coverage reports.

Running All Tests with Coverage 

./test_generator.sh
Enter fullscreen mode Exit fullscreen mode

This command:

  1. Runs all Flutter tests in the project
  2. Generates a coverage report
  3. Opens the HTML coverage report in your browser

Testing Specific Features 

# Test only the auth feature
./test_generator.sh --target test/features/auth/

# Test a specific file
./test_generator.sh --target test/features/auth/domain/usecases/login_test.dart
Enter fullscreen mode Exit fullscreen mode

Test Options 

# Run tests without coverage (faster)
./test_generator.sh --no-coverage

# Generate coverage but don't open the report
./test_generator.sh --no-report
Enter fullscreen mode Exit fullscreen mode

3. Language Generator (generate_language.sh)

The language generator helps manage translations and internationalization.

Adding a New Language 

# Add Spanish localization
./generate_language.sh --lang es

# Add multiple languages
./generate_language.sh --lang fr,de,ja
Enter fullscreen mode Exit fullscreen mode

This will:

  1. Set up translation files in lib/l10n/ for each language
  2. Create necessary configuration for Flutter's localization system
  3. Generate boilerplate translation keys based on existing languages

Extracting Translation Keys 

# Extract all translatable strings from the codebase
./generate_language.sh --extract
Enter fullscreen mode Exit fullscreen mode

This scans your codebase for strings wrapped in context.tr() calls and updates your translation files with new keys.

Generating Translations 

# Generate the localization files
./generate_language.sh --generate
Enter fullscreen mode Exit fullscreen mode

This creates the necessary Dart classes for accessing translations in your code.

4. App Renamer (rename_app.sh)

The app renamer makes it easy to customize the app name, package name, and bundle ID across all platforms.

App Renaming 

# Update app name and bundle ID
./rename_app.sh --name "My Awesome App" --bundle com.mycompany.awesomeapp
Enter fullscreen mode Exit fullscreen mode

This updates:

  • App name in all platform-specific files
  • Package/bundle identifiers in Android and iOS
  • Various configuration files

Platform-Specific Options 

# Update only certain platforms
./rename_app.sh --name "My Awesome App" --bundle com.mycompany.awesomeapp --platforms android,ios

# Change the iOS bundle ID only
./rename_app.sh --ios-bundle com.mycompany.iosapp

# Change the Android package name only
./rename_app.sh --android-package com.mycompany.androidapp
Enter fullscreen mode Exit fullscreen mode

Real-World Examples

Let's see how these tools work together in a real-world development flow:

Creating a New Feature with Full Testing 

# 1. Generate the feature
./generate_feature.sh --name shopping_cart

# 2. Run specific tests for the new feature
./test_generator.sh --target test/features/shopping_cart/

# 3. Add new translations for the feature
./generate_language.sh --extract
Enter fullscreen mode Exit fullscreen mode

Quickly Prototyping a UI Component 

# 1. Generate a UI-only component
./generate_feature.sh --name gradient_card --ui-only

# 2. Skip tests during initial development
./test_generator.sh --no-coverage
Enter fullscreen mode Exit fullscreen mode

Adding a New Service with Multiple Language Support 

# 1. Generate a service-only feature
./generate_feature.sh --name analytics_tracker --service-only

# 2. Add support for multiple languages
./generate_language.sh --lang fr,de,es,ja

# 3. Run tests for the service
./test_generator.sh --target test/features/analytics_tracker/
Enter fullscreen mode Exit fullscreen mode

Tips and Best Practices

  1. Use the right feature type: Choose the appropriate feature structure based on complexity:
  • Full Clean Architecture for complex business features
  • No-repository for simpler features
  • UI-only for reusable UI components
  • Service-only for utility services
  1. Run tests frequently: The test generator makes it easy to run tests as you develop: 
   ./test_generator.sh --target test/features/your_feature/
Enter fullscreen mode Exit fullscreen mode
  1. Generate documentation: Always generate documentation for features to keep the codebase easily maintainable: 
   # Generate a feature with documentation
   ./generate_feature.sh --name feature_name
Enter fullscreen mode Exit fullscreen mode
  1. Extract translations early: Extract translatable strings frequently to avoid missing any: 
   ./generate_language.sh --extract
Enter fullscreen mode Exit fullscreen mode
  1. Combine commands in scripts: Create custom scripts that combine these tools for your workflow: 
   # Example: create_and_test_feature.sh
   #!/bin/bash
   ./generate_feature.sh --name $1
   ./test_generator.sh --target test/features/$1/
   ./generate_language.sh --extract
Enter fullscreen mode Exit fullscreen mode

💡 Why Use Clean Architecture + Riverpod?

  • Maintainability: Add features and refactor with confidence.
  • Testability: Write meaningful tests for every layer.
  • Scalability: Grow your app and your team without chaos.
  • Community-Driven: Built with real-world feedback and best practices.

🤝 Contribute & Connect

I’d love your feedback, issues, and PRs!

If you find this template useful, please ⭐ the repo and share your thoughts.

Ready to build your next Flutter app?

Start with a foundation that scales. Try the Flutter Riverpod Clean Architecture template today!

Drop your questions, suggestions, or clean architecture tips in the comments!

Let me know if you want to highlight any specific feature, add more code samples, or further customize this post!

This is part of a series on Flutter Riverpod Clean Architecture. Check out the full repository on GitHub.

Top comments (0)