Flutter Location Selection App

A Flutter application that demonstrates clean architecture with BLoC state management for selecting countries and their corresponding states.

Features

• Country selection from a dynamic list fetched from API
• State selection based on the selected country
• Clean architecture implementation with separation of concerns
• BLoC pattern for state management
• Comprehensive unit and widget testing
• Error handling and loading states

Project Structure

This project follows Clean Architecture principles with the following structure:

lib/
├── core/                       # Core functionality shared across features
│   ├── constants/             # API constants and configuration
│   ├── errors/               # Error handling (Failures and Exceptions)
│   └── utils/                # Utility functions
├── features/
│   └── location/             # Location selection feature
│       ├── data/            # Data layer
│       │   ├── datasources/ # Remote data sources for API calls
│       │   ├── models/     # Data models with JSON serialization
│       │   └── repositories/ # Repository implementations
│       ├── domain/          # Domain layer (business logic)
│       │   ├── entities/   # Business entities
│       │   ├── repositories/ # Repository contracts
│       │   └── usecases/   # Business use cases
│       └── presentation/    # Presentation layer
│           ├── bloc/       # BLoC state management
│           ├── screens/    # UI screens
│           └── widgets/    # Reusable widgets
└── injection/               # Dependency injection setup

Architecture

Clean Architecture Layers

1. Presentation Layer (presentation/)

• Responsibility: UI and user interaction
• Components:
  • BLoC (Business Logic Component) for state management
  • Screens and widgets for UI
• Dependencies: Only depends on Domain layer

2. Domain Layer (domain/)

• Responsibility: Business logic and rules
• Components:
  • Entities: Core business objects
  • Use Cases: Application-specific business rules
  • Repository Interfaces: Contracts for data operations
• Dependencies: No dependencies on other layers (pure Dart)

3. Data Layer (data/)

• Responsibility: Data retrieval and caching
• Components:
  • Models: Data transfer objects with JSON serialization
  • Data Sources: Remote API implementations
  • Repository Implementations: Concrete implementations of domain contracts
• Dependencies: Depends on Domain layer

State Management

The app uses BLoC (Business Logic Component) pattern for state management:

• Events: User actions (LoadCountriesEvent, SelectCountryEvent, SelectStateEvent)
• States: UI states (LocationInitial, LocationLoading, LocationLoaded, LocationError)
• BLoC: Transforms events into states through business logic

Dependency Injection

Uses GetIt for dependency injection to:

• Maintain loose coupling between layers
• Enable easy testing with mock implementations
• Centralize dependency configuration

API Integration

The app integrates with a REST API:

• Base URL: https://68a2b00ac5a31eb7bb1d7ad2.mockapi.io/api/v1
• Endpoints:
  • GET /countries - Fetches list of countries
  • GET /countries/{countryId}/states - Fetches states for a specific country

Testing

Unit Tests

• Models: JSON serialization/deserialization
• Data Sources: API call behavior and error handling
• Repositories: Data flow and error transformation
• Use Cases: Business logic execution
• BLoC: Event to state transformations

Widget Tests

• UI component rendering
• User interaction handling
• State-based UI updates

Running Tests

flutter test

Getting Started

Prerequisites

• Flutter SDK ^3.7.0
• Dart SDK ^3.7.0

Installation

1. Clone the repository:

git clone https://github.com/[username]/flutter_coding_challenge.git
cd flutter_coding_challenge

2. Install dependencies:

flutter pub get

3. Run the app:

flutter run

Development

Code Analysis

flutter analyze

Format Code

dart format lib/

Key Dependencies

• flutter_bloc: State management
• bloc: Core BLoC library
• equatable: Value equality for entities and states
• http: HTTP client for API calls
• get_it: Service locator for dependency injection
• dartz: Functional programming utilities (Either type for error handling)
• mocktail: Mocking library for tests
• bloc_test: Testing utilities for BLoC

Design Decisions

1. Clean Architecture

Rationale: Provides separation of concerns, making the code more maintainable, testable, and scalable. Each layer has a single responsibility and clear boundaries.

2. BLoC Pattern

Rationale: Offers predictable state management with clear separation between business logic and UI. Makes testing easier and provides a reactive programming model.

3. Repository Pattern

Rationale: Abstracts data sources from business logic, allowing easy switching between different data sources (API, local database, cache) without affecting domain layer.

4. Either Type for Error Handling

Rationale: Using dartz's Either type provides functional error handling without exceptions in the domain layer, making error cases explicit and type-safe.

5. Dependency Injection

Rationale: Promotes loose coupling, enables easy testing with mocks, and centralizes object creation and lifecycle management.