Skip to main content

Clean Architecture

Note: Clean Architecture is one of the supported patterns in easy_init_cli.

easy_init_cli implements Clean Architecture, separating code into three main layers: Data, Domain, and Presentation. This ensures independence, scalability, and testability.

Feature-Wise Separation​

The architecture organizes code by features rather than technical layers. Each feature is a self-contained module with its own data, domain, and presentation layers.

Advantages​

  • Modularity: Features are independent and can be developed, tested, and maintained in isolation
  • Scalability: Easy to add new features without affecting existing ones
  • Team Collaboration: Multiple developers can work on different features simultaneously without conflicts
  • Code Reusability: Shared utilities and widgets are placed in common/ for cross-feature use
  • Maintainability: Changes to one feature don't ripple through the entire codebase
  • Testability: Each feature can be unit tested independently with clear boundaries

Project Structure​

lib/
├── app.dart                   # Main application widget
├── app_runner.dart            # Application runner configuration
├── main.dart                  # Application entry point
├── common/                    # Reusable components, utilities, and shared logic
│   └── widgets/               # Common UI components
├── core/                      # Core functionalities and cross-cutting concerns
│   ├── api_endpoints/         # API endpoint definitions
│   ├── base_usecase/          # Base use case definitions
│   ├── config/                # Application configuration
│   ├── dependency_injection/  # Dependency injection setup
│   ├── extensions/            # Dart extensions
│   ├── failures/              # Custom failure classes
│   ├── network/               # Network client and handling
│   ├── routes/                # Application routing definitions
│   ├── services/              # Core services
│   └── theme/                 # Application theme and colors
└── features/                  # Feature-specific modules
    └── <feature_name>/
        ├── data/              # Data layer
        │   ├── data_sources/  # Remote and local data sources
        │   ├── models/        # Data transfer objects (DTOs)
        │   └── repositories_impl/ # Repository implementations
        ├── domain/            # Domain layer
        │   ├── entities/      # Core business entities
        │   ├── repositories/  # Repository interfaces
        │   └── usecases/      # Business logic (use cases)
        └── presentation/      # Presentation layer
            ├── blocs/         # BLoC for state management
            ├── screens/       # Screens/Pages
            └── widgets/       # Feature-specific UI components

AI Documentation​

The project includes an /ai_docs folder in the root directory containing curated guidelines for AI-assisted development:

  • api_flow_guide.md - Comprehensive guide on API call flow, error handling patterns, and network layer best practices
  • styling_guide.md - Styling conventions, theme usage, widget patterns, and UI consistency guidelines

These guides enable vibe coding - AI-powered development that maintains consistency with your project's architecture and conventions. When using AI assistants, reference these documents to ensure generated code follows your established patterns.

Resources​

For a deep dive into this architecture, we recommend Reso Coder's Flutter Clean Architecture Course.

Note: A "Number Trivia" feature is generated by default to demonstrate the architecture's flow. You can use this as a reference or remove it when you start building your core features.

Core Packages​

The Clean Architecture implementation uses the following packages to maintain separation of concerns and efficient state management:

Dependencies​

  • dartz - Functional programming for error handling with Either type
  • flutter_bloc - BLoC pattern implementation for state management
  • injectable - Code generation for dependency injection setup
  • freezed_annotation - Annotations for generating immutable models and unions
  • get_it - Service locator for dependency injection
  • dio - HTTP client for API requests
  • intl - Internationalization and localization support
  • go_router - Declarative routing solution

Dev Dependencies​

  • build_runner - Code generation tool runner
  • freezed - Code generator for immutable classes and unions
  • injectable_generator - Code generator for injectable dependency injection
  • mocktail - Mocking library for unit tests

These packages work together to provide:

  • Dependency Injection: get_it and injectable handle service registration and retrieval
  • State Management: flutter_bloc manages application state with events and states
  • Error Handling: dartz provides functional Either types for clean error handling
  • Data Models: freezed generates immutable entities and models with copyWith, equality, and toString
  • Networking: dio provides a robust HTTP client with interceptors
  • Routing: go_router enables type-safe, declarative navigation
  • Testing: mocktail allows easy mocking for unit tests