Flutter 3.x Clean Architecture: Designing Offline-First Enterprise Systems

+--------------------------------------------------------------+
|                       PRESENTATION LAYER                     |
|  - UI Widgets (Stateless/Stateful)                           |
|  - State Holders (Riverpod AsyncNotifiers & Providers)       |
+--------------------------------------------------------------+
                               |  (Observes State / Dispatches Actions)
                               v
+--------------------------------------------------------------+
|                          DOMAIN LAYER                        |
|  - Business Entities (Immutable Data Classes)                |
|  - Use Cases (Application-specific business rules)           |
|  - Repository Interfaces (Abstraction Boundary)              |
+--------------------------------------------------------------+
                               ^
                               |  (Implements Interfaces)
+--------------------------------------------------------------+
|                           DATA LAYER                         |
|  - Repository Implementations (Orchestrates Sync)            |
|  - Local Data Sources (Isar Database, Secure Storage)        |
|  - Remote Data Sources (HTTP/gRPC/WebSocket Clients)         |
|  - Data Transfer Objects / Models (JSON Mappers)             |
+--------------------------------------------------------------+

// Target: Flutter 3.22+ / Dart 3.4+
// File: lib/domain/entities/order_entity.dart

import 'package:meta/meta.dart';

@immutable
class OrderEntity {
  final String id;
  final String customerName;
  final double totalAmount;
  final String status; // 'pending', 'synced', 'failed'
  final DateTime createdAt;
  final DateTime updatedAt;

  const OrderEntity({
    required this.id,
    required this.customerName,
    required this.totalAmount,
    required this.status,
    required this.createdAt,
    required this.updatedAt,
  });

  OrderEntity copyWith({
    String? id,
    String? customerName,
    double? totalAmount,
    String? status,
    DateTime? createdAt,
    DateTime? updatedAt,
  }) {
    return OrderEntity(
      id: id ?? this.id,
      customerName: customerName ?? this.customerName,
      totalAmount: totalAmount ?? this.totalAmount,
      status: status ?? this.status,
      createdAt: createdAt ?? this.createdAt,
      updatedAt: updatedAt ?? this.updatedAt,
    );
  }
}

// File: lib/domain/repositories/order_repository.dart

import '../entities/order_entity.dart';

abstract class OrderRepository {
  Stream<List<OrderEntity>> watchOrders();
  Future<void> createOrder(OrderEntity order);
  Future<void> synchronizePendingOrders();
}

// File: lib/data/models/order_model.dart

import 'package:isar/isar.dart';
import '../../domain/entities/order_entity.dart';

part 'order_model.g.dart';

@collection
class OrderModel {
  // Isar requires an auto-incrementing id or a fast-hash mapped to integer
  Id get isarId => id.hashCode;

  @Index(unique: true, replace: true)
  late String id;
  
  late String customerName;
  late double totalAmount;
  late String status;
  late DateTime createdAt;
  late DateTime updatedAt;

  // Convert Entity -> Model
  static OrderModel fromEntity(OrderEntity entity) {
    return OrderModel()
      ..id = entity.id
      ..customerName = entity.customerName
      ..totalAmount = entity.totalAmount
      ..status = entity.status
      ..createdAt = entity.createdAt
      ..updatedAt = entity.updatedAt;
  } 

  // Convert Model -> Entity
  OrderEntity toEntity() {
    return OrderEntity(
      id: id,
      customerName: customerName,
      totalAmount: totalAmount,
      status: status,
      createdAt: createdAt,
      updatedAt: updatedAt,
    );
  }
}

// File: lib/data/repositories/order_repository_impl.dart

import 'dart:async';
import 'package:isar/isar.dart';
import '../../domain/entities/order_entity.dart';
import '../../domain/repositories/order_repository.dart';
import '../models/order_model.dart';
import 'package:dio/dio.dart';

class OrderRepositoryImpl implements OrderRepository {
  final Isar _isar;
  final Dio _dio;

  OrderRepositoryImpl(this._isar, this._dio);

  @override
  Stream<List<OrderEntity>> watchOrders() {
    // Stream local changes instantly whenever Isar database updates
    return _isar.orderModels
        .where()
        .sortByCreatedAtDesc()
        .watch(fireImmediately: true)
        .map((models) => models.map((m) => m.toEntity()).toList());
  }

  @override
  Future<void> createOrder(OrderEntity order) async {
    final localModel = OrderModel.fromEntity(order.copyWith(status: 'pending'));
    
    // Write synchronously/asynchronously to local DB storage immediately
    await _isar.writeTxn(() async {
      await _isar.orderModels.put(localModel);
    });

    // Attempt immediate opportunistic synchronization in background
    // We do not await this, preventing local UI blocking
    unawaited(synchronizePendingOrders());
  }

  @override
  Future<void> synchronizePendingOrders() async {
    // Find all pending changes that have not been sent to backend
    final pendingModels = await _isar.orderModels
        .filter()
        .statusEqualTo('pending')
        .findAll();

    if (pendingModels.isEmpty) return;

    for (final model in pendingModels) {
      try {
        // Map local DTO into JSON API structure
        final payload = {
          'id': model.id,
          'customer_name': model.customerName,
          'total_amount': model.totalAmount,
          'created_at': model.createdAt.toIso8601String(),
        };

        // Make network post request
        final response = await _dio.post('/orders/sync', data: payload);

        if (response.statusCode == 200 || response.statusCode == 201) {
          // Synchronized successfully: mark as synced
          await _isar.writeTxn(() async {
            model.status = 'synced';
            model.updatedAt = DateTime.now();
            await _isar.orderModels.put(model);
          });
        }
      } on DioException catch (e) {
        // Log backend issues but keep the record in 'failed' status
        // to retry later during connectivity changes or periodic syncs
        if (e.type != DioExceptionType.connectionTimeout && 
            e.type != DioExceptionType.connectionError) {
          await _isar.writeTxn(() async {
            model.status = 'failed';
            await _isar.orderModels.put(model);
          });
        }
        // If network connectivity issue occurred, leave as pending to retry next cycle
      }
    }
  }
}

// File: lib/presentation/providers/order_provider.dart

import 'package:riverpod_annotation/riverpod_annotation.dart';
import '../../domain/entities/order_entity.dart';
import '../../domain/repositories/order_repository.dart';
import 'package:uuid/uuid.dart';

part 'order_provider.g.dart';

// These providers would be initialized in your application entry point
@Riverpod(keepAlive: true)
OrderRepository orderRepository(OrderRepositoryRef ref) {
  throw UnimplementedError('Initialize this provider in the top-level ProviderScope overrides');
}

@riverpod
Stream<List<OrderEntity>> orderList(OrderListRef ref) {
  final repository = ref.watch(orderRepositoryProvider);
  return repository.watchOrders();
}

@riverpod
class OrderController extends _$OrderController {
  @override
  FutureOr<void> build() {
    // No initial async action required here
  }

  Future<void> addOrder(String customerName, double amount) async {
    state = const AsyncValue.loading();
    
    final newOrder = OrderEntity(
      id: const Uuid().v4(),
      customerName: customerName,
      totalAmount: amount,
      status: 'pending',
      createdAt: DateTime.now(),
      updatedAt: DateTime.now(),
    );

    final repository = ref.read(orderRepositoryProvider);
    state = await AsyncValue.guard(() => repository.createOrder(newOrder));
  }

  Future<void> forceSync() async {
    state = const AsyncValue.loading();
    final repository = ref.read(orderRepositoryProvider);
    state = await AsyncValue.guard(() => repository.synchronizePendingOrders());
  }
}

// Execute heavy model mappings off the main Isolate thread
Future<List<OrderModel>> parseHeavyJson(String jsonString) async {
  return Isolate.run(() {
    final decoded = jsonDecode(jsonString) as List;
    return decoded.map((json) => OrderModel.fromJson(json)).toList();
  });
}