Bloc Architecture

A scalable, maintainable Flutter project template using BLoC, Clean Architecture, GoRouter, Theming, Localization, and best practices.

---

✨ Features

• Splash Screen: Animated splash with timed navigation.
• Home Page: Central hub with navigation, dialog, and snackbar demos.
• Avatar Explorer:
  • Fetch and display avatars from an API.
  • Infinite scroll and pagination.
  • Search and filter by name, gender, and age.
  • Mark and view favorite avatars.
  • Avatar details view.
• Profile Page: Placeholder for user profile features.
• Settings Page:
  • Change app language at runtime.
  • Multi-language support (English, Hindi, Gujarati, German).
• Theming: Light/dark mode toggle and theme demo.
• Localization: JSON-based, runtime language switching.
• Navigation: GoRouter-based, with tab navigation (Home, Profile, Settings).
• State Management: BLoC pattern, Hydrated BLoC for persistence.
• Dependency Injection: get_it for all repositories, blocs, and services.
• Utilities & Architecture:
  • Feature-first folder structure.
  • Code generation scripts for new features.
  • Centralized constants, themes, and utility functions.
  • Error handling and loading indicators.

---

🆕 Recent Additions & Improvements

• Advanced Notification Service:
  • Local notification handling with payload parsing, extensible notification types, and robust error handling.
• Common Shimmer Widgets:
  • Shimmer, ShimmerLoading, CircleShimmer, and RoundedRectangleShimmer for consistent loading placeholders across the app.
• Popup Dialog Utilities:
  • CommonDialog, PopupButton, and PopupType for platform-adaptive dialogs and reusable popup actions.
• Responsive Utilities:
  • ResponsiveUtils and responsive extensions for adaptive UI scaling on mobile, tablet, and ultra-tablet devices.
• Common Scaffold & Image Widgets:
  • CommonScaffold for unified app layout with shimmer and keyboard handling.
  • CommonAppImage for standardized image display (network, asset, file, SVG).
• Barrel File Structure:
  • All core modules and features use barrel files for clean, maintainable imports and exports.
  • Feature-level barrels for widgets, bloc, data, entities, and repositories.
• Improved Documentation:
  • All utilities, widgets, and constants are now fully documented with Dart doc comments and inline explanations.
• Consistent Constants:
  • Dimens class for all UI spacing and sizing constants, ensuring design consistency.
• Code Quality:
  • Unused/duplicate files removed, imports refactored, and code style enforced throughout the project.

---

🚀 Getting Started

1. Requirements

• Flutter (latest stable)
• Dart
• flutter_dotenv for environment variables

2. Setup

flutter pub get
cp .env.example .env # Edit .env as needed

3. Running the App

flutter run

---

🌱 Project Structure

lib/
  core/           # Shared utilities, constants, theme, localization
  features/       # Feature-first structure (see below)
  di/             # Dependency injection setup (get_it)
  router/         # App routing (GoRouter)
  main.dart       # Entry point

Feature Example

lib/features/sample_feature/
  data/
    datasources/
    repositories/
  domain/
    entities/
    repositories/
    usecases/
  presentation/
    bloc/
    view/
      widgets/

---

🛠️ Environment Variables

• Managed with flutter_dotenv.
• Place your keys in .env (see .env.example).

---

🧑‍💻 Linting & Code Style

• Uses Flutter and BLoC recommended lints.
• Custom rules in analysis_options.yaml enforce structure and code quality.
• Run:

  flutter analyze
  flutter format .

---

⚡ Feature Generator

• Windows: Use generate_feature.ps1 (PowerShell)

  .\generate_feature.ps1

• Mac/Linux/Any: Use generate_feature.sh:

  chmod +x generate_feature.sh
  ./generate_feature.sh

• Prompts for feature name, creates all folders/files, and gives DI registration snippet.

---

🧩 Dependency Injection (DI)

• Uses get_it.
• Register your BLoC and repository in di/service_locator.dart:

  getIt.registerFactory<SampleFeatureBloc>(() => SampleFeatureBloc());
  getIt.registerLazySingleton<SampleFeatureRepository>(() => SampleFeatureRepositoryImpl());

• Inject into UI with getIt<SampleFeatureBloc>().

---

🎨 Theming

• Centralized in core/theme/.
• Use Theme.of(context) and custom color schemes.
• Add new colors/fonts in app_colors.dart, app_fonts.dart.

---

🌍 Localization

• Uses core/config/app_strings.dart and assets/translations/.
• Add new languages by adding JSON files and updating supported locales.

---

🧭 Routing

• Uses GoRouter in router/app_router.dart.
• Define routes and navigation logic centrally.
• Example:

  context.goNamed(AppRouter.sampleFeatureScreen);

---

🌐 API & Interceptors

• API logic in core/network/ and feature data sources.
• Interceptors (e.g., auth, logging) in core/network/dio_interceptor.dart.
• Example usage:

  final response = await apiProvider.get(apiUrl: NetworkConstants.api);

---

🧑‍🎨 Sample Feature

• See features/sample_feature/ for a reference implementation:
  • BLoC, repository, DI, screen, theming, localization, and routing.

---

📝 Contributing

• Follow the structure and code style.
• Use the feature generator for new features.
• Register new BLoCs and repositories in DI.
• Add tests and documentation as you go.

---

📚 Resources

• BLoC Pattern
• Clean Architecture
• GoRouter
• get_it
• flutter_dotenv

---

Happy coding! 🎉