Flutter Template

A production-ready, highly scalable Flutter boilerplate built with Clean Architecture and Functional Programming principles.

🛠 Tech Stack

• State Management: flutter_bloc & bloc - Predictable state management using the BLoC pattern.
• Dependency Injection: get_it - Service locator for loose coupling.
• Navigation: go_router - Declarative routing with deep linking support.
• Networking: dio - Powerful HTTP client with interceptors and global configuration.
• Local Database: drift - Reactive persistence library for SQLite.
• Functional Programming: fpdart - Functional programming types like Either and TaskEither for predictable error handling.
• Serialization & Models: freezed & json_serializable - Type-safe models and unions.
• Local Storage: shared_preferences and flutter_secure_storage for sensitive data.

---

🏗 Architecture

The project follows Clean Architecture principles, enforcing a strict separation of concerns and a feature-driven folder structure.

Layers

1. Presentation Layer:
   • UI (Screens & Widgets): Pure Flutter widgets.
   • BLoC: Handles UI events and manages state transitions.
2. Domain Layer (Business Logic):
   • Entities: Plain data objects used across the app.
   • Repositories (Interfaces): Abstract contracts defining data operations.
   • Use Cases: Encapsulate specific business rules.
3. Data Layer (Infrastructure):
   • DataSources: Implementation of remote (API) and local (DB) data fetching.
   • Models (DTOs): JSON-compatible data structures.
   • Mappers: Logic to convert DTOs to Domain Entities.
   • Repositories (Implementations): Orchestrate data flow between DataSources and Domain.

---

📂 Project Structure

lib/
├── app/                  # Application-wide configuration
│   ├── config/           # Environment settings (Dev/QA/Prod)
│   ├── di/               # Global dependency injection modules
│   ├── navigation/       # Centralized GoRouter configuration
│   └── theme/            # Material/Cupertino theme data
├── core/                 # Shared infrastructure and utilities
│   ├── database/         # Drift database definition
│   ├── network/          # Dio client and interceptors
│   ├── storage/          # Storage wrappers (Secure/Prefs)
│   └── utils/            # Functional extensions (Either, Future)
├── features/             # Feature-driven modules
│   └── news/             # Example "News" feature
│       ├── data/         # DTOs, Mappers, DataSources, Repositories
│       ├── domain/       # Entities, Use Cases, Interfaces
│       └── presentation/ # BLoC, Screens, Widgets
├── shared/               # Common components shared between features
│   └── error/            # Unified error handling (Failure types)
└── main_dev.dart         # Entry points for different environments

---

🚦 Error Handling & Functional Approach

This project avoids throwing exceptions in the business logic layer. Instead, it uses a Functional Error Handling approach via fpdart:

• Failure: A standard way to represent errors (Network, Server, Cache, etc.).
• Either<L, R>: Methods return a Left(Failure) or a Right(Result).
• TaskEither: Used in the Data layer to wrap asynchronous operations safely.

---

🚀 Getting Started

1. Prerequisites

• Flutter SDK (check pubspec.yaml for version)
• Dart SDK

2. Setup

Clone the repository and install dependencies:

flutter pub get

3. Code Generation

Run the build runner to generate Freezed, JsonSerializable, and Drift files:

dart run build_runner build --delete-conflicting-outputs

4. Running the App

The project uses flavors. Launch the desired environment:

flutter run -t lib/main_dev.dart

---