DEV Community: Shashi Kant

MongoDB Backup and Restore Strategy on AWS

Shashi Kant — Fri, 17 Jul 2026 11:49:51 +0000

Whether you're running a side project or managing enterprise-scale applications, having a reliable backup strategy for MongoDB is essential. I've seen teams invest months building systems but spend only a few minutes thinking about disaster recovery.

In this article, I'll walk through a production-ready MongoDB backup and restore strategy using AWS that is reliable, secure, and cost-effective.

Why Backups Matter

Imagine these scenarios:

Someone accidentally runs deleteMany({}) on production.
A deployment corrupts important collections.
Your EC2 instance crashes permanently.
Ransomware encrypts your server.
An application bug overwrites critical data.

Without backups, recovery may be impossible.

A good backup strategy should satisfy three goals:

Automatic
Secure
Quick to Restore

Architecture

MongoDB
     │
     │ mongodump
     ▼
Compressed Archive (.gz)
     │
     ▼
AWS S3 Bucket
     │
Lifecycle Policy
     ▼
Glacier Archive

The workflow is simple:

Create a backup using mongodump
Compress the archive
Upload it to Amazon S3
Automatically move older backups to Glacier
Restore whenever necessary

Prerequisites

MongoDB installed
AWS Account
IAM User with S3 permissions
AWS CLI configured
Linux server (Ubuntu/Amazon Linux)

Install MongoDB Database Tools

sudo apt install mongodb-database-tools

Configure AWS CLI

aws configure

Step 1 — Create a Backup

mongodump \
  --uri="mongodb://username:password@host:27017/database" \
  --gzip \
  --archive=/backup/mongodb_$(date +%F_%H-%M).gz

This command creates a compressed archive of the database.

Example output:

mongodb_2026-07-17_02-00.gz

Step 2 — Upload to Amazon S3

aws s3 cp \
/backup/mongodb_2026-07-17_02-00.gz \
s3://company-backups/mongodb/

Your backups are now safely stored outside your production server.

This protects you even if the EC2 instance is completely lost.

Step 3 — Automate with Cron

Create a shell script.

#!/bin/bash

DATE=$(date +%F_%H-%M)

mongodump \
--uri="$MONGO_URI" \
--gzip \
--archive=/backup/mongodb_$DATE.gz

aws s3 cp \
/backup/mongodb_$DATE.gz \
s3://company-backups/mongodb/

find /backup -type f -mtime +7 -delete

Make it executable.

chmod +x backup.sh

Schedule it.

crontab -e

Daily at 2 AM

0 2 * * * /home/ubuntu/backup.sh

Now backups happen automatically every night.

Step 4 — Configure S3 Lifecycle Rules

Instead of paying premium storage forever, configure lifecycle policies.

Recommended policy:

Backup Age	Storage Class
0–30 Days	Standard
31–90 Days	Standard-IA
90+ Days	Glacier
365+ Days	Delete

This significantly reduces storage costs.

Step 5 — Encrypt Everything

Never store backups in plain text.

Use:

Server-side encryption (SSE-S3)
SSE-KMS for enterprise environments

Enable encryption directly on the bucket.

Also:

Block public access
Enable bucket versioning
Enable MFA Delete (where applicable)

Step 6 — Test Your Restores

Many teams create backups.

Very few verify them.

A backup that cannot be restored is useless.

Restore using:

mongorestore \
--gzip \
--archive=mongodb_2026-07-17_02-00.gz

Or restore a specific database.

mongorestore \
--db=mydatabase \
--gzip \
--archive=backup.gz

Schedule periodic restore tests in a staging environment.

Point-in-Time Recovery

If your application processes financial transactions or critical business data, daily backups may not be enough.

Enable MongoDB replication.

Then archive the oplog.

This allows recovery to almost any point in time.

Monitoring Backup Jobs

A backup process should notify you when it fails.

Recommended options:

CloudWatch Logs
CloudWatch Alarms
SNS Notifications
Slack Webhooks
Email alerts

Never assume backups are working.

Monitor them.

Security Best Practices

Store MongoDB credentials in AWS Secrets Manager.
Use IAM roles instead of long-lived AWS access keys.
Restrict S3 bucket access to the backup server.
Enable S3 Versioning.
Enable Bucket Encryption.
Rotate credentials regularly.
Keep backup servers updated.

Common Mistakes

❌ Keeping backups on the same server

❌ Never testing restore

❌ No encryption

❌ No lifecycle policy

❌ No monitoring

❌ Manual backups only

Sample Recovery Workflow

Imagine production fails.

Launch a new EC2 instance.
Install MongoDB.
Download the latest backup from S3.
Run mongorestore.
Point your application to the restored database.
Resume normal operations.

A well-prepared recovery can take minutes instead of hours.

Final Thoughts

Backups are one of those things nobody appreciates until they're desperately needed.

A reliable MongoDB backup strategy isn't just about creating dump files—it's about ensuring you can recover quickly, securely, and with confidence. By combining mongodump, Amazon S3, lifecycle policies, encryption, and automated scheduling, you can build a robust disaster recovery process without excessive complexity.

Remember: The value of a backup is measured by how quickly and successfully you can restore it.

What backup strategy do you use?

Native MongoDB tools?
MongoDB Atlas backups?
AWS Backup?
Snapshot-based backups?
Something else?

Share your experience in the comments—I'd love to learn how others handle production backups.

If you found this helpful, consider following me for more articles on Backend Engineering, DevOps, Data Engineering, and Flutter.

Flutter Repository Pattern Explained (Stop Accessing APIs Directly)

Shashi Kant — Tue, 31 Mar 2026 14:45:11 +0000

Flutter Repository Pattern Explained (Stop Accessing APIs Directly)

If your BLoC is calling APIs directly…

👉 your architecture is already broken.

It might work today — but as your app grows, it turns into a nightmare:

Hard to test ❌
Hard to scale ❌
Impossible to swap data sources ❌

Let’s fix that properly.

🧠 The Real Problem

Most Flutter apps look like this:

final response = await dio.get('/users');

Inside:

BLoC ❌
UI ❌
Even widgets sometimes ❌

👉 This creates tight coupling between your app and your API.

🏗️ The Solution: Repository Pattern

The repository acts as a bridge between:

Data sources (API, local DB)
Domain layer (business logic, BLoC)

UI → Bloc → UseCase → Repository → DataSource

👉 Your app depends on abstraction, not implementation.

📦 Step 1: Define Repository Contract (Domain Layer)

abstract class UserRepository {
  Future<User> getUser(int id);
}

✔ No API
✔ No JSON
✔ Pure business logic contract

🔌 Step 2: Create Data Source (Data Layer)

class UserRemoteDataSource {
  final Dio dio;

  UserRemoteDataSource(this.dio);

  Future<Map<String, dynamic>> fetchUser(int id) async {
    final response = await dio.get('/users/$id');
    return response.data;
  }
}

👉 This is the only place that talks to your API.

🔄 Step 3: Implement Repository

class UserRepositoryImpl implements UserRepository {
  final UserRemoteDataSource remoteDataSource;

  UserRepositoryImpl(this.remoteDataSource);

  @override
  Future<User> getUser(int id) async {
    final data = await remoteDataSource.fetchUser(id);

    return User(
      id: data['id'],
      name: data['name'],
      email: data['email'],
    );
  }
}

👉 Converts raw data → Entity

🧩 Step 4: Use It in BLoC

class UserBloc extends Bloc<UserEvent, UserState> {
  final UserRepository repository;

  UserBloc(this.repository) : super(UserInitial()) {
    on<FetchUser>((event, emit) async {
      emit(UserLoading());

      try {
        final user = await repository.getUser(event.id);
        emit(UserLoaded(user));
      } catch (e) {
        emit(UserError(e.toString()));
      }
    });
  }
}

👉 BLoC has no idea where data comes from.

🎯 Why This Matters (Real Benefits)

✅ 1. Swap API → Local DB easily

You can replace:

UserRemoteDataSource

with:

UserLocalDataSource

No changes in BLoC.

✅ 2. Testing becomes EASY

class MockUserRepository implements UserRepository {
  @override
  Future<User> getUser(int id) async {
    return User(id: 1, name: 'Test', email: 'test@mail.com');
  }
}

👉 No API calls in tests. Ever.

✅ 3. Scales like a real production app

You can add:

Caching
Multiple APIs
Offline mode

Without breaking your app.

🚨 Common Mistakes

❌ Returning JSON from repository
❌ Calling Dio inside BLoC
❌ Mixing model & entity
❌ Skipping abstraction “to save time”

👉 These kill scalability.

💡 Pro Tip (Most Important)

👉 Repository should return Entities, not Models.

Model → Data layer
Entity → Domain layer

🔚 Final Thoughts

The repository pattern is not “extra code”.

👉 It’s what separates:

Small apps from
Production systems

👇 Next Article

👉 Stop Throwing Exceptions ❌ Proper Error Handling in Flutter Clean Architecture

Follow me to continue the series 🚀

Clean Architecture with BLoC in Flutter: A Practical Guide

Shashi Kant — Sat, 28 Mar 2026 08:58:37 +0000

Clean Architecture with BLoC in Flutter: A Practical Guide

After working across multiple Flutter products — from fleet management apps to OCR pipelines — one thing becomes clear fast: the way you structure your code matters more than the features you ship. Bad architecture slows you down exponentially. Clean Architecture with BLoC is the combination I keep reaching for on production Flutter apps.

This isn't a theoretical post. Every pattern here is drawn from real app structure decisions.

Why Clean Architecture?

Flutter makes it dangerously easy to write everything in one widget file. It works — until it doesn't.

Clean Architecture enforces a boundary between:

What your app does (business logic)
How it does it (data sources, APIs, databases)
How it shows it (UI)

The payoff: you can swap your REST API for GraphQL, your local DB for Hive, or your UI framework entirely — without touching your core business rules.

The Three Layers

┌──────────────────────────────────┐
│         Presentation Layer       │  ← Widgets, BLoC/Cubit
├──────────────────────────────────┤
│           Domain Layer           │  ← Entities, Use Cases, Repository Contracts
├──────────────────────────────────┤
│            Data Layer            │  ← Repository Impl, Data Sources, Models
└──────────────────────────────────┘

Dependency Rule: Arrows point inward only. Domain knows nothing about Data or Presentation.

Folder Structure

lib/
├── core/
│   ├── error/
│   │   ├── exceptions.dart
│   │   └── failures.dart
│   ├── usecases/
│   │   └── usecase.dart          # Abstract base UseCase
│   └── utils/
│       └── input_converter.dart
│
├── features/
│   └── vehicle/
│       ├── data/
│       │   ├── datasources/
│       │   │   ├── vehicle_local_datasource.dart
│       │   │   └── vehicle_remote_datasource.dart
│       │   ├── models/
│       │   │   └── vehicle_model.dart
│       │   └── repositories/
│       │       └── vehicle_repository_impl.dart
│       │
│       ├── domain/
│       │   ├── entities/
│       │   │   └── vehicle.dart
│       │   ├── repositories/
│       │   │   └── vehicle_repository.dart   # Abstract
│       │   └── usecases/
│       │       ├── get_vehicle_details.dart
│       │       └── update_vehicle_status.dart
│       │
│       └── presentation/
│           ├── bloc/
│           │   ├── vehicle_bloc.dart
│           │   ├── vehicle_event.dart
│           │   └── vehicle_state.dart
│           ├── pages/
│           │   └── vehicle_detail_page.dart
│           └── widgets/
│               └── vehicle_card.dart
│
└── injection_container.dart      # GetIt DI setup

This feature-first layout scales well. Each feature is a self-contained vertical slice.

Layer 1: Domain

This is the heart of your app. No Flutter imports here — this layer is pure Dart.

Entity

// features/vehicle/domain/entities/vehicle.dart

class Vehicle {
  final String id;
  final String plateNumber;
  final String ownerName;
  final VehicleStatus status;

  const Vehicle({
    required this.id,
    required this.plateNumber,
    required this.ownerName,
    required this.status,
  });
}

enum VehicleStatus { active, inactive, underService }

Repository Contract

// features/vehicle/domain/repositories/vehicle_repository.dart
import 'package:dartz/dartz.dart';
import '../../../../core/error/failures.dart';
import '../entities/vehicle.dart';

abstract class VehicleRepository {
  Future<Either<Failure, Vehicle>> getVehicleDetails(String vehicleId);
  Future<Either<Failure, List<Vehicle>>> getFleetVehicles();
}

Either<Failure, T> from dartz makes error handling explicit and typed — no more catching exceptions across layers.

Use Case

// features/vehicle/domain/usecases/get_vehicle_details.dart
import 'package:dartz/dartz.dart';
import '../../../../core/error/failures.dart';
import '../../../../core/usecases/usecase.dart';
import '../entities/vehicle.dart';
import '../repositories/vehicle_repository.dart';

class GetVehicleDetails implements UseCase<Vehicle, String> {
  final VehicleRepository repository;

  GetVehicleDetails(this.repository);

  @override
  Future<Either<Failure, Vehicle>> call(String vehicleId) {
    return repository.getVehicleDetails(vehicleId);
  }
}

Base UseCase

// core/usecases/usecase.dart
import 'package:dartz/dartz.dart';
import '../error/failures.dart';

abstract class UseCase<Type, Params> {
  Future<Either<Failure, Type>> call(Params params);
}

Layer 2: Data

This is where implementation details live — API calls, local DB, models.

Model (extends Entity)

// features/vehicle/data/models/vehicle_model.dart
import '../../domain/entities/vehicle.dart';

class VehicleModel extends Vehicle {
  const VehicleModel({
    required super.id,
    required super.plateNumber,
    required super.ownerName,
    required super.status,
  });

  factory VehicleModel.fromJson(Map<String, dynamic> json) {
    return VehicleModel(
      id: json['id'] as String,
      plateNumber: json['plate_number'] as String,
      ownerName: json['owner_name'] as String,
      status: VehicleStatus.values.firstWhere(
        (e) => e.name == json['status'],
        orElse: () => VehicleStatus.inactive,
      ),
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'plate_number': plateNumber,
      'owner_name': ownerName,
      'status': status.name,
    };
  }
}

Remote Data Source

// features/vehicle/data/datasources/vehicle_remote_datasource.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import '../../../../core/error/exceptions.dart';
import '../models/vehicle_model.dart';

abstract class VehicleRemoteDataSource {
  Future<VehicleModel> getVehicleDetails(String vehicleId);
}

class VehicleRemoteDataSourceImpl implements VehicleRemoteDataSource {
  final http.Client client;

  VehicleRemoteDataSourceImpl({required this.client});

  @override
  Future<VehicleModel> getVehicleDetails(String vehicleId) async {
    final response = await client.get(
      Uri.parse('https://api.example.com/vehicles/$vehicleId'),
      headers: {'Content-Type': 'application/json'},
    );

    if (response.statusCode == 200) {
      return VehicleModel.fromJson(json.decode(response.body));
    } else {
      throw ServerException();
    }
  }
}

Repository Implementation

// features/vehicle/data/repositories/vehicle_repository_impl.dart
import 'package:dartz/dartz.dart';
import '../../../../core/error/exceptions.dart';
import '../../../../core/error/failures.dart';
import '../../domain/entities/vehicle.dart';
import '../../domain/repositories/vehicle_repository.dart';
import '../datasources/vehicle_remote_datasource.dart';
import '../datasources/vehicle_local_datasource.dart';

class VehicleRepositoryImpl implements VehicleRepository {
  final VehicleRemoteDataSource remoteDataSource;
  final VehicleLocalDataSource localDataSource;

  VehicleRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
  });

  @override
  Future<Either<Failure, Vehicle>> getVehicleDetails(String vehicleId) async {
    try {
      final vehicle = await remoteDataSource.getVehicleDetails(vehicleId);
      await localDataSource.cacheVehicle(vehicle); // cache after fetch
      return Right(vehicle);
    } on ServerException {
      try {
        final cached = await localDataSource.getCachedVehicle(vehicleId);
        return Right(cached);
      } on CacheException {
        return Left(CacheFailure());
      }
    }
  }

  @override
  Future<Either<Failure, List<Vehicle>>> getFleetVehicles() async {
    try {
      final vehicles = await remoteDataSource.getFleetVehicles();
      return Right(vehicles);
    } on ServerException {
      return Left(ServerFailure());
    }
  }
}

The repository is where the offline-first strategy lives — try network, fall back to cache. Neither the domain nor the UI needs to know this.

Layer 3: Presentation — BLoC

Events

// features/vehicle/presentation/bloc/vehicle_event.dart
part of 'vehicle_bloc.dart';

abstract class VehicleEvent extends Equatable {
  const VehicleEvent();

  @override
  List<Object> get props => [];
}

class GetVehicleDetailsEvent extends VehicleEvent {
  final String vehicleId;

  const GetVehicleDetailsEvent(this.vehicleId);

  @override
  List<Object> get props => [vehicleId];
}

class RefreshFleetEvent extends VehicleEvent {
  const RefreshFleetEvent();
}

States

// features/vehicle/presentation/bloc/vehicle_state.dart
part of 'vehicle_bloc.dart';

abstract class VehicleState extends Equatable {
  const VehicleState();

  @override
  List<Object?> get props => [];
}

class VehicleInitial extends VehicleState {}

class VehicleLoading extends VehicleState {}

class VehicleLoaded extends VehicleState {
  final Vehicle vehicle;

  const VehicleLoaded(this.vehicle);

  @override
  List<Object?> get props => [vehicle];
}

class VehicleError extends VehicleState {
  final String message;

  const VehicleError(this.message);

  @override
  List<Object?> get props => [message];
}

BLoC

// features/vehicle/presentation/bloc/vehicle_bloc.dart
import 'package:bloc/bloc.dart';
import 'package:equatable/equatable.dart';
import '../../domain/entities/vehicle.dart';
import '../../domain/usecases/get_vehicle_details.dart';

part 'vehicle_event.dart';
part 'vehicle_state.dart';

const String serverFailureMessage = 'Server Failure';
const String cacheFailureMessage = 'Cache Failure';

class VehicleBloc extends Bloc<VehicleEvent, VehicleState> {
  final GetVehicleDetails getVehicleDetails;

  VehicleBloc({required this.getVehicleDetails}) : super(VehicleInitial()) {
    on<GetVehicleDetailsEvent>(_onGetVehicleDetails);
  }

  Future<void> _onGetVehicleDetails(
    GetVehicleDetailsEvent event,
    Emitter<VehicleState> emit,
  ) async {
    emit(VehicleLoading());

    final result = await getVehicleDetails(event.vehicleId);

    result.fold(
      (failure) => emit(VehicleError(_mapFailureToMessage(failure))),
      (vehicle) => emit(VehicleLoaded(vehicle)),
    );
  }

  String _mapFailureToMessage(Failure failure) {
    switch (failure.runtimeType) {
      case ServerFailure:
        return serverFailureMessage;
      case CacheFailure:
        return cacheFailureMessage;
      default:
        return 'Unexpected error';
    }
  }
}

UI Page

// features/vehicle/presentation/pages/vehicle_detail_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import '../bloc/vehicle_bloc.dart';
import '../widgets/vehicle_card.dart';

class VehicleDetailPage extends StatelessWidget {
  final String vehicleId;

  const VehicleDetailPage({super.key, required this.vehicleId});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Vehicle Details')),
      body: BlocConsumer<VehicleBloc, VehicleState>(
        listener: (context, state) {
          if (state is VehicleError) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text(state.message)),
            );
          }
        },
        builder: (context, state) {
          if (state is VehicleLoading) {
            return const Center(child: CircularProgressIndicator());
          }
          if (state is VehicleLoaded) {
            return VehicleCard(vehicle: state.vehicle);
          }
          return const Center(child: Text('Press load to fetch vehicle'));
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          context.read<VehicleBloc>().add(GetVehicleDetailsEvent(vehicleId));
        },
        child: const Icon(Icons.refresh),
      ),
    );
  }
}

Dependency Injection with GetIt

Wire everything together in one place:

// injection_container.dart
import 'package:get_it/get_it.dart';
import 'package:http/http.dart' as http;
import 'features/vehicle/data/datasources/vehicle_remote_datasource.dart';
import 'features/vehicle/data/datasources/vehicle_local_datasource.dart';
import 'features/vehicle/data/repositories/vehicle_repository_impl.dart';
import 'features/vehicle/domain/repositories/vehicle_repository.dart';
import 'features/vehicle/domain/usecases/get_vehicle_details.dart';
import 'features/vehicle/presentation/bloc/vehicle_bloc.dart';

final sl = GetIt.instance;

Future<void> init() async {
  // BLoC — factory: new instance per registration
  sl.registerFactory(() => VehicleBloc(getVehicleDetails: sl()));

  // Use Cases
  sl.registerLazySingleton(() => GetVehicleDetails(sl()));

  // Repository
  sl.registerLazySingleton<VehicleRepository>(
    () => VehicleRepositoryImpl(
      remoteDataSource: sl(),
      localDataSource: sl(),
    ),
  );

  // Data Sources
  sl.registerLazySingleton<VehicleRemoteDataSource>(
    () => VehicleRemoteDataSourceImpl(client: sl()),
  );
  sl.registerLazySingleton<VehicleLocalDataSource>(
    () => VehicleLocalDataSourceImpl(),
  );

  // External
  sl.registerLazySingleton(() => http.Client());
}

Call await init() before runApp() in main.dart.

Provide the BLoC using BlocProvider:

BlocProvider(
  create: (_) => sl<VehicleBloc>(),
  child: VehicleDetailPage(vehicleId: 'VH-001'),
)

Failures & Exceptions

Keep these two concepts separate — exceptions are implementation details, failures are domain concepts.

// core/error/exceptions.dart
class ServerException implements Exception {}
class CacheException implements Exception {}

// core/error/failures.dart
import 'package:equatable/equatable.dart';

abstract class Failure extends Equatable {
  @override
  List<Object> get props => [];
}

class ServerFailure extends Failure {}
class CacheFailure extends Failure {}

The Dependency Flow (Visualized)

main.dart
   └── injection_container.dart (GetIt)
          │
          ├── VehicleBloc
          │      └── GetVehicleDetails (UseCase)
          │             └── VehicleRepository (abstract)
          │                    └── VehicleRepositoryImpl
          │                           ├── VehicleRemoteDataSourceImpl
          │                           └── VehicleLocalDataSourceImpl
          │
          └── http.Client

Domain sits in the middle — it defines the contracts, and both data and presentation depend on it. Neither depends on the other.

Key Packages

dependencies:
  flutter_bloc: ^8.1.5
  equatable: ^2.0.5
  dartz: ^0.10.1
  get_it: ^7.7.0
  http: ^1.2.1

dev_dependencies:
  bloc_test: ^9.1.7
  mocktail: ^1.0.4

Testing the BLoC

Clean Architecture makes testing trivial — mock the use case, test the BLoC in isolation:

// test/features/vehicle/presentation/bloc/vehicle_bloc_test.dart
import 'package:bloc_test/bloc_test.dart';
import 'package:dartz/dartz.dart';
import 'package:mocktail/mocktail.dart';
import 'package:test/test.dart';

class MockGetVehicleDetails extends Mock implements GetVehicleDetails {}

void main() {
  late VehicleBloc bloc;
  late MockGetVehicleDetails mockGetVehicleDetails;

  setUp(() {
    mockGetVehicleDetails = MockGetVehicleDetails();
    bloc = VehicleBloc(getVehicleDetails: mockGetVehicleDetails);
  });

  const testVehicle = Vehicle(
    id: 'VH-001',
    plateNumber: 'DL01AB1234',
    ownerName: 'Ravi Kumar',
    status: VehicleStatus.active,
  );

  blocTest<VehicleBloc, VehicleState>(
    'emits [Loading, Loaded] when vehicle fetch succeeds',
    build: () {
      when(() => mockGetVehicleDetails('VH-001'))
          .thenAnswer((_) async => const Right(testVehicle));
      return bloc;
    },
    act: (bloc) => bloc.add(const GetVehicleDetailsEvent('VH-001')),
    expect: () => [
      VehicleLoading(),
      const VehicleLoaded(testVehicle),
    ],
  );

  blocTest<VehicleBloc, VehicleState>(
    'emits [Loading, Error] when server fails',
    build: () {
      when(() => mockGetVehicleDetails('VH-001'))
          .thenAnswer((_) async => Left(ServerFailure()));
      return bloc;
    },
    act: (bloc) => bloc.add(const GetVehicleDetailsEvent('VH-001')),
    expect: () => [
      VehicleLoading(),
      const VehicleError(serverFailureMessage),
    ],
  );
}

When to Use Cubit vs BLoC

Scenario	Use
Simple toggle, counter, form state	Cubit
Multiple event types driving the same state	BLoC
Complex event pipelines, debouncing	BLoC
Search with transformers	BLoC

Cubit is BLoC without events — less boilerplate, fine for simpler state machines.

Common Pitfalls

1. Skipping the UseCase layer for "simple" features
That simple feature grows. Write the use case.

2. Putting business logic in the repository
Repositories fetch and cache. Decisions belong in use cases.

3. Importing dart:io or package:flutter in domain
If it slips in, your architecture has a leak. Domain is pure Dart.

4. Using a single BLoC for multiple features
One BLoC per feature. Shared state should go through a shared use case, not a god-BLoC.

5. Not handling Either properly
Always fold your results. Don't unwrap with getOrElse and swallow failures.

Wrapping Up

Clean Architecture with BLoC gives you:

Testability — every layer is independently testable
Scalability — add a feature without touching existing ones
Replaceability — swap Hive for Drift, REST for gRPC, zero domain changes
Clarity — a new dev can find any piece of logic by knowing which layer to look in

The upfront cost is real. The folder structure feels ceremonious for a hello-world app. But on a real product with multiple developers, multiple data sources, and multiple app variants — it pays back every single day.

Got questions about adapting this to your specific app structure? Drop them in the comments.