Flutter Clean Architecture Template

A scalable, modular, and production-ready Flutter architecture template that follows best practices using Clean Architecture, BLoC, and dependency injection. Perfect for bootstrapping any new project with a solid foundation.

---

✨ Features

• Feature-based modular structure
• Clean Architecture separation (Data, Domain, Presentation)
• Dependency injection via get_it
• State management with flutter_bloc
• Auto-mapping with auto_mappr
• Localization with easy_localization
• Centralized networking using dio
• Error handling & typed responses with dartz
• Scalable widget structure & utilities in core

---

🗂 Folder Structure

lib/
└── src/
    ├── config/                # App-wide setup (routing, theming, localization)
    │   ├── locale/
    │   ├── routes/
    │   └── themes/
    ├── core/                  # Core logic, base widgets, and utilities
    │   ├── api/               # Dio setup, interceptors
    │   ├── constant/          # Constant values and keys
    │   ├── error/             # Error handling classes
    │   ├── network/           # Internet checker & network utilities
    │   ├── utils/             # Helpers, extensions, formatters
    │   └── widgets/           # Common reusable UI widgets
    ├── features/              # Feature modules (e.g. auth, home, profile, etc.)
    │   └── auth/
    │       ├── data/
    │       │   ├── auto_mapper/      # Entity-model mappers
    │       │   ├── datasources/      # Remote/local data sources
    │       │   ├── models/           # DTOs and model classes
    │       │   └── repositories/     # Data layer implementations
    │       ├── domain/
    │       │   ├── entities/         # Pure business objects
    │       │   ├── repositories/     # Abstract contracts
    │       │   └── usecases/         # Business logic
    │       └── presentation/
    │           ├── cubit/            # State management
    │           ├── screens/          # UI screens
    │           └── widgets/          # Feature-specific widgets
    ├── translations/          # Localization generated keys
    ├── injector_container.dart # DI setup using GetIt
    ├── bloc_observer.dart     # Global BLoC observer
    ├── app.dart               # App widget with MaterialApp setup
    └── main.dart              # Entry point

---

🧩 What's Included

This architecture template showcases a production-ready Flutter setup including:

• ✅ Socket.IO Manager
  Easily establish and manage real-time connections using socket_io_client. Integrated for scalable use inside your feature modules.

• 🔗 App Links Manager + Share Integration
  Handles deep linking with app_links and makes content sharing seamless using share_plus.

• 🧵 Custom Isolate Manager
  Offload heavy tasks using a well-structured isolate manager for background processing without blocking the UI.

• 🔔 Firebase Messaging
  Fully configured push notification handling with firebase_messaging, including background and foreground scenarios.

• 📍 Geolocation Services
  Get device location and convert coordinates to readable addresses with:

  • geolocator for current location
  • geocoding for reverse geolocation

• 🔐 Token Expiry Checker with Dio Interceptor
  Centralized solution to check token validity, auto-refresh, and re-attempt failed requests using Dio interceptors.
  📦 Check core/api/dio_interceptors.dart for the complete setup.

• 🗺️ AutoMapper with Type Conversion
  Simplifies DTO <=> Domain object conversion using auto_mappr.
  Includes a working example with custom type converters:
  📦 See /features/auth/data/auto_mapper/ for implementation.

---

🔧 Dependencies

This template includes many commonly used packages, such as:

dependencies:
  flutter_bloc: ^9.0.0
  get_it: ^7.6.4
  dartz: ^0.10.1
  dio: ^5.4.1
  easy_localization: ^3.0.1
  auto_mappr_annotation: ^2.1.0
  cached_network_image: ^3.4.1
  flutter_secure_storage: ^9.2.4
  shared_preferences: ^2.3.2
  ...

dev_dependencies:
  build_runner: ^2.4.7
  auto_mappr: ^2.5.0
  json_serializable: ^6.7.1

See pubspec.yaml for full list.

---

🛠 Setup Instructions

1. Install dependencies:

   flutter pub get

2. Generate code: (mappers, JSON, etc.)

   dart run build_runner build --delete-conflicting-outputs

3. Run the app:

   flutter run

---

🧩 How to Add a New Feature

1. Create a new folder under features/ (e.g. profile/)
2. Add data, domain, presentation folders
3. Follow the same structure as other features
4. Register dependencies in injector_container.dart

---

🧠 Why This Structure?

This template is:

• Easy to scale and maintain as the app grows
• Clearly separates responsibilities and logic layers
• Encourages testability and modular development

---

💡 Motivation

This template is meant to:

• Kickstart production-ready apps with best practices
• Showcase how to structure medium-to-large scale Flutter projects
• Make onboarding and maintenance easier in team environments

---

👤 Author

Template maintained by Me. Feel free to fork and contribute!

---

Happy Coding 🚀