Skip to content

README.md

Latest commit

 

History

History
205 lines (154 loc) · 5.29 KB

README.md

File metadata and controls

205 lines (154 loc) · 5.29 KB

🧠 Flutter Clean Architecture Learning App

A complete Flutter learning project built to demonstrate best practices for:

  • Fetching data from APIs
  • Using BLoC/Cubit for state management
  • Implementing the Repository pattern
  • Organizing code with clean architecture
  • Applying router navigation for screens
  • Adding search functionality
  • Using Hero animations for smooth navigation transitions
  • Customizing SliverAppBar for better UX
  • Following clean linting rules and project conventions

🚀 Features

✅- Fetch data from REST API using Dio / WebServices layer ✅- Manage state using BLoC / Cubit ✅- Organize project with Repository Pattern ✅- Navigation via AppRouters class ✅- Implement Search filter inside GridView ✅- Add Hero widget for transition between Character list and details ✅- Beautiful SliverAppBar in details screen ✅- Handle loading, success, and error states gracefully ✅- Clean, modular, and readable project structure ✅- Proper lint rules configuration in analysis_options.yaml

📂 Project Structure

lib/
├── business_logic/
│   └── cubit/
│       └── character_cubit.dart
├── constants/
│   ├── colors.dart
│   └── strings.dart
├── core/
│   └── bloc_observer.dart
├── data/
│   ├── models/
│   │   └── character.dart
│   ├── repository/
│   │   └── characters_repository.dart
│   └── web_services/
│       └── characters_web_services.dart
├── presentation/
│   ├── screens/
│   │   ├── characters_screen.dart
│   │   └── characters_details.dart
│   └── widgets/
│       └── character_item.dart
└── app_router.dart

This structure follows Clean Architecture principles:

  • WebServices → responsible for API calls
  • Repository → connects data layer and business logic
  • Cubit/BLoC → handles states and logic
  • Presentation → displays data in UI

⚙️ Technologies & Packages

Package Purpose
flutter_bloc State management
dio API networking
equatable Easier Cubit state comparisons
cached_network_image Efficient image loading
flutter_lints Enforcing code style
google_fonts Custom typography
animations For Hero and transitions

🔍 Search Feature

Users can search for characters by name (case-insensitive). It filters results dynamically inside the GridView using Cubit state updates.

🎨 UI Highlights

  • CharactersScreen: Displays all characters in a responsive grid
  • CharacterItem: Card with image and name
  • CharacterDetailsScreen: Opens with smooth Hero transition + SliverAppBar
  • Error & Loading states handled elegantly using widgets
  • Consistent spacing, rounded corners, and shadows for a clean look

🧩 Routing

App navigation is managed by AppRouters:

switch (settings.name) {
  case ConstantStrings.characterScreen:
    return MaterialPageRoute(
      builder: (_) => BlocProvider(
        create: (context) => CharacterCubit(repository),
        child: const CharactersScreen(),
      ),
    );
  case ConstantStrings.characterScreenDetails:
    final character = settings.arguments as Character;
    return MaterialPageRoute(
      builder: (_) => CharactersDetails(character: character),
    );
}

🧱 State Management

Each feature has its own Cubit class (e.g. CharacterCubit) that:

  • Fetches data via Repository
  • Emits Loading → Success → Error states
  • Allows filtering (search)

Example:

class CharacterCubit extends Cubit<CharacterState> {
  final CharactersRepository charactersRepository;

  CharacterCubit(this.charactersRepository) : super(CharacterInitial());

  void getAllCharacters() async {
    emit(CharacterLoading());
    try {
      final characters = await charactersRepository.getAllCharacters();
      emit(CharacterLoaded(characters));
    } catch (e) {
      emit(CharacterError(e.toString()));
    }
  }
}

🧭 How to Run

  1. Clone the repository:

    git clone https://github.com/your-username/Characters.git

  2. Navigate to project folder:

    cd Characters

  3. Get dependencies:

    flutter pub get

  4. Run the app:

    flutter run

🎓 Learning Goals

This project is perfect for anyone who wants to:

  • Learn Flutter + BLoC/Cubit from a real example
  • Understand Clean Architecture pattern
  • Practice API fetching + Repository separation
  • Master navigation, search, and Hero animation
  • Write clean and lint-approved Flutter code

🤝 Contributing

Feel free to fork, open issues, and submit pull requests. This project is meant for learning and collaboration!

💬 Author

Mohammad Hmedat 👨‍💻 - Software Engineer | Flutter & .NET Developer 📚 - Passionate about clean code, architecture, and building learning projects 📧 - [humedat23@gmail.com]