Mobile Architecture Overview

lib/features/
├── home/
│   ├── presentation/
│   │   ├── pages/
│   │   │   └── home_page.dart
│   │   └── widgets/
│   │       └── home_widget.dart
│   └── bloc/
│       ├── home_bloc.dart
│       ├── home_event.dart
│       └── home_state.dart

class ProductBloc extends Bloc<ProductEvent, ProductState> {
  final ProductService _service;
  
  ProductBloc(this._service) : super(ProductInitial()) {
    on<LoadProducts>(_onLoadProducts);
  }
  
  Future<void> _onLoadProducts(
    LoadProducts event,
    Emitter<ProductState> emit,
  ) async {
    emit(ProductLoading());
    
    final result = await _service.getProducts();
    
    result.fold(
      (failure) => emit(ProductError(failure.message)),
      (products) => emit(ProductLoaded(products)),
    );
  }
}

@LazySingleton()
class ProductService {
  final ProductRepository _repository;
  final IsarDb _isarDb;
  
  Future<Either<Failure, List<Product>>> getProducts() async {
    // 1) Return Isar INSTANTLY
    final local = await _getProductsLocalOnly();
    
    // 2) Trigger background refresh
    _triggerBackgroundRefresh();
    
    // 3) Return local
    return local;
  }
  
  void _triggerBackgroundRefresh() {
    unawaited(() async {
      if (!await _isOnline()) return;
      
      final apiResult = await _repository.fetchProducts();
      await _upsertToIsar(apiResult);
    }());
  }
}

@LazySingleton()
class ProductRepository {
  final ProductApi _api;
  
  Future<Either<Failure, List<ProductDto>>> fetchProducts() async {
    try {
      final response = await _api.getProducts();
      return Right(response.data);
    } catch (e) {
      return Left(ServerFailure(message: e.toString()));
    }
  }
}

@collection
class ProductEntity {
  Id id = Isar.autoIncrement;
  
  @Index()
  late int apiId;
  
  late String name;
  late String sku;
  late int price;
  late int stock;
  
  @Index()
  late String branchCode;
  
  late DateTime createdAt;
  late DateTime updatedAt;
}

// ❌ WRONG: Show loading spinner
BlocBuilder<DataBloc, DataState>(
  builder: (context, state) {
    if (state is DataLoading) {
      return CircularProgressIndicator(); // ❌ Bad UX
    }
    return ListView(children: state.data.map(...));
  },
)

// ✅ CORRECT: Always show data
BlocBuilder<DataBloc, DataState>(
  builder: (context, state) {
    return ListView(children: state.data.map(...));
  },
)

StreamBuilder<List<ProductEntity>>(
  stream: isarDb.isar.productEntitys.watchLazy(),
  builder: (context, snapshot) {
    context.read<ProductBloc>().add(LoadProducts());
    
    return BlocBuilder<ProductBloc, ProductState>(
      builder: (context, state) {
        if (state is ProductLoaded) {
          return ListView(children: state.products.map(...));
        }
        return EmptyState();
      },
    );
  },
)

RefreshIndicator(
  onRefresh: () async {
    context.read<ProductBloc>().add(RefreshProducts(force: true));
    await Future.delayed(Duration(milliseconds: 500));
  },
  child: ListView(...),
)

# Check Flutter version
flutter --version  # Flutter 3.x required

# Check Dart version
dart --version     # Dart 3.x required

# Clone repository
git clone <repo-url>
cd mstore_mobile

# Install dependencies
flutter pub get

# Generate code (Isar, Freezed, Retrofit)
flutter pub run build_runner build --delete-conflicting-outputs

# Run app
flutter run

# Watch mode (auto-generate on file changes)
flutter pub run build_runner watch --delete-conflicting-outputs

# One-time generation
flutter pub run build_runner build --delete-conflicting-outputs

# Run all unit tests
flutter test

# Run specific test file
flutter test test/core/product/product_service_test.dart

# Run with coverage
flutter test --coverage

# Run widget tests
flutter test test/features/home/presentation/pages/home_page_test.dart

# Run integration tests
flutter test integration_test/

# Run on specific device
flutter test integration_test/ -d <device-id>

lib/
├── core/                      # Core functionality
│   ├── auth/                 # Authentication
│   ├── branches/             # Branches service
│   ├── network/              # Dio client, interceptors
│   ├── observers/            # Bloc observer
│   ├── product/              # Product service
│   ├── settings/             # Settings service
│   └── transaction/          # Transaction service
├── database/                  # Isar database
│   └── isar/
│       ├── entities/         # Isar entities
│       └── isar_db.dart      # Database instance
├── di/                        # Dependency injection
│   └── injection.dart        # Get_it setup
├── features/                  # Feature modules
│   ├── auth/                 # Auth feature
│   ├── checkout/             # Checkout feature
│   ├── home/                 # Home feature
│   └── ...
├── pkg/                       # Shared packages
│   ├── constants/            # App constants
│   ├── utils/                # Utilities
│   └── widgets/              # Shared widgets
└── main.dart                  # App entry point