You'll also need to be quite intentional in selecting your folder structure, architecture, and the patterns you use in your projects.

Most Flutter apps start the same way. In the beginning, you have a lib folder, a few screens, maybe a models directory, and a services file that handles everything. It works, the app ships, and everyone is happy.

Then the app grows. New features come in. The team expands. What was once a manageable codebase becomes a maze. Changing one thing breaks another. Nobody is sure where business logic actually lives. The models folder has three hundred files. The services file is six thousand lines long. New engineers take weeks to understand where to add anything.

This isn't a discipline problem. It's a structure problem. The app was never organized in a way that could absorb growth without collapsing.

Feature Modularization is the organizational strategy that prevents this collapse. It's not a new framework, and it's not a replacement for Clean Architecture or Domain-Driven Design. It takes the principles of both and applies them feature by feature, so that every piece of your application is self-contained, independently testable, and scalable without interference.

In this article, we'll cover the current issues you might encounter using the layer first pattern, how Domain-Driven Design actually works, some business rules with value objects, what Clean Architecture means, and how they all come together in feature modularization.

Table of Contents

• Prerequisites

• What Feature Modularization Actually Is

• The Problem With Layer-First Organization

• The Building Blocks: Clean Architecture Meets DDD

• Entities, Value Objects, and DTOs in a Modular Feature

• Business Rules and Where They Live

• Exception Handling and Safe State Propagation

• The Folder Structure

• Real World Example One: The Employee Feature

• Real World Example Two: The Payment Feature

• Cross-Feature Communication

• Patterns That Enhance Modularization

• Scaling to Large Teams

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Building Flutter applications in Dart

• What object-oriented programming is: classes, inheritance, interfaces

• What layers mean in software architecture: separating UI from business logic from data access

• Async programming in Dart: Futures and async/await

You don't need prior experience with Clean Architecture or Domain-Driven Design. This article introduces the relevant concepts from both as they come up.

What Feature Modularization Actually Is

Feature Modularization is the practice of organizing your application around features, not around technical layers.

Every feature in your application contains everything it needs to function: its domain model, business rules, data access, and UI. The feature is a vertical slice through the entire application stack. It doesn't depend on other features to function. It doesn't expose its internals to other features. It stands alone.

This is fundamentally different from how most apps are initially organized, where all the domain code lives in one folder, all the data access lives in another folder, and all the UI lives in a third folder, regardless of which feature that code belongs to.

Feature Modularization isn't Clean Architecture. Clean Architecture defines what the layers are and the rules that govern how they interact. It tells you that the domain layer can't depend on the infrastructure layer, that business rules can't know about the UI, and that data flows inward through defined boundaries.

Feature Modularization isn't Domain-Driven Design either. DDD gives you the vocabulary for modeling complex business domains. It introduces entities, value objects, aggregates, domain services, and bounded contexts as tools for capturing business complexity in code.

Feature Modularization takes both of these and combines them. It uses Clean Architecture's layering rules and DDD's modeling vocabulary, and it applies them at the feature level. Each feature gets its own domain layer, its own application layer, its own infrastructure layer, and its own presentation layer. The rules from Clean Architecture govern how those layers interact within the feature. The concepts from DDD govern how the domain model is structured inside the domain layer.

The result is a codebase that can grow indefinitely without any single part of it becoming too large to understand or modify safely.

The Problem With Layer-First Organization

To understand why Feature Modularization matters, you need to see what the alternative looks like at scale.

In a layer-first organization, the folder structure groups code by technical role:

lib/
  domain/
    employee.dart
    payment.dart
    product.dart
    notification.dart
    user.dart
    ... 47 more files

  application/
    get_employee_usecase.dart
    process_payment_usecase.dart
    get_products_usecase.dart
    send_notification_usecase.dart
    ... 83 more use cases

  infrastructure/
    employee_repository_impl.dart
    payment_repository_impl.dart
    product_datasource.dart
    notification_service_impl.dart
    ... 91 more implementations

  presentation/
    employee_page.dart
    payment_page.dart
    product_list_page.dart
    ... 200 more screens and widgets

This works fine at small scale. At medium scale it starts to show cracks. At large scale it becomes genuinely painful.

When a developer needs to modify the Employee feature, they touch files in four separate top-level folders. A change to the Employee entity in the domain folder requires navigating to the application folder for the use case, then the infrastructure folder for the repository implementation, and then the presentation folder for the UI. These folders aren't next to each other. They're separated by all the other features sharing those folders.

Understanding any single feature requires mentally assembling it from pieces scattered across the entire codebase. Onboarding a new engineer to the Employee feature means showing them four different locations before they can see the complete picture.

Testing the Employee feature in isolation is difficult because its pieces aren't isolated. They share folders and sometimes share dependencies with other features in ways that make it hard to draw a clean boundary.

Feature Modularization solves this by keeping everything that belongs to a feature together.

The Building Blocks: Clean Architecture Meets DDD

Before looking at the folder structure and code, you need to understand what Clean Architecture and DDD each contribute to Feature Modularization and why both are necessary.

What Clean Architecture Contributes

Clean Architecture organizes code into layers with a strict dependency rule: inner layers never depend on outer layers. The domain is the innermost layer. The application layer wraps the domain. The infrastructure layer is outermost.

In a Flutter application, this means a few things:

The domain layer contains entities, value objects, and repository interfaces. It has zero dependencies on Flutter, on HTTP libraries, on local databases, or on any external package. It's pure Dart, and it's the business logic of the feature, completely isolated from how the app is built or deployed.

The application layer contains use cases. A use case orchestrates domain objects to accomplish a specific business task. It depends only on the domain layer. It knows about entities and repositories but doesn't know about HTTP or SQLite or Riverpod.

The infrastructure layer contains the concrete implementations of repository interfaces defined in the domain. It knows about HTTP clients, local databases, and external services. It depends on the domain layer interfaces but the domain layer never depends on it.

The presentation layer contains the UI: widgets, notifiers, and state. It depends on the application layer through use cases. It reacts to state and has no business logic.

This dependency direction ensures that business rules are never corrupted by infrastructure details. Changing your HTTP client from Dio to http doesn't require touching a single domain entity. Changing your state management from Riverpod to BLoC doesn't require touching a single use case.

What Domain-Driven Design Contributes

DDD provides the vocabulary for modeling the domain layer properly.

An Entity is a domain object with identity. It has an ID that distinguishes it from other entities of the same type. An Employee entity is identified by its employee ID. Two employees with the same name are still different entities because they have different IDs. Entities can have state that changes over time, and they enforce rules about how that state can change.

A Value Object wraps a single piece of data and enforces its intrinsic validity. An EmployeeId is a Value Object, as is an email address or monetary amount. Value Objects are immutable. If the data is invalid, the Value Object throws an exception at construction time, before invalid data can enter the domain.

A Domain Service handles business logic that doesn't naturally belong to a single entity. If a rule spans multiple entities or requires coordination between entities in ways that don't fit on any single entity, that logic belongs in a Domain Service.

A Repository is an interface defined in the domain layer that describes how to persist and retrieve domain objects. The domain knows what operations it needs. The infrastructure layer provides the concrete implementation. The domain never knows which database or API is behind the repository.

Entities, Value Objects, and DTOs in a Modular Feature

Understanding the distinction between these three types is fundamental to feature modularization. Getting this wrong leads to business rules leaking into the wrong layers.

Value Objects

A Value Object wraps a single piece of data and enforces that the data is always valid. It throws immediately when invalid data is provided. This means invalid data can never exist inside your domain.

class EmployeeId {
  final String value;

  EmployeeId(this.value) {
    if (value.isEmpty) {
      throw DomainException('Employee ID cannot be empty');
    }
    if (value.length < 4) {
      throw DomainException('Employee ID must be at least 4 characters');
    }
  }

  @override
  bool operator ==(Object other) =>
      other is EmployeeId && other.value == value;

  @override
  int get hashCode => value.hashCode;

  @override
  String toString() => value;
}

class Money {
  final double amount;
  final String currency;

  Money({required this.amount, required this.currency}) {
    if (amount < 0) {
      throw DomainException('Amount cannot be negative');
    }
    if (currency.isEmpty) {
      throw DomainException('Currency cannot be empty');
    }
  }

  Money add(Money other) {
    if (currency != other.currency) {
      throw DomainException('Cannot add different currencies');
    }
    return Money(amount: amount + other.amount, currency: currency);
  }

  @override
  String toString() => '$currency ${amount.toStringAsFixed(2)}';
}

Value Objects are immutable. You never modify a Value Object. Instead, you create a new one. EmployeeId and Money above both validate at construction. No invalid EmployeeId can ever exist anywhere in your domain. No negative Money can ever exist. The guard is built into the type itself.

Entities

An Entity is a domain object with an identity and rules about how its state can change.

class Employee {
  final EmployeeId id;
  final String name;
  DateTime? clockInTime;
  DateTime? clockOutTime;

  Employee({
    required this.id,
    required this.name,
  });

  void clockIn(DateTime time) {
    if (clockInTime != null && clockOutTime == null) {
      throw DomainException('Cannot clock in: already clocked in');
    }
    clockInTime = time;
    clockOutTime = null;
  }

  void clockOut(DateTime time) {
    if (clockInTime == null) {
      throw DomainException('Cannot clock out: not clocked in');
    }
    if (time.isBefore(clockInTime!)) {
      throw DomainException('Clock out time cannot be before clock in time');
    }
    clockOutTime = time;
  }

  bool get isClockedIn => clockInTime != null && clockOutTime == null;

  Duration? get hoursWorked {
    if (clockInTime == null || clockOutTime == null) return null;
    return clockOutTime!.difference(clockInTime!);
  }
}

The Entity owns its state transitions. clockIn and clockOut aren't just setters. They enforce business rules. An employee can't clock in twice without clocking out, just like they can't clock out before they've clocked in. These rules live on the Entity where they belong, not in a use case, widget, or repository.

DTOs

A Data Transfer Object carries raw data from an external source: an API response, database row, or JSON payload. DTOs have no business rules or behavior. They exist only to transport data across a boundary.

class EmployeeDTO {
  final String id;
  final String name;
  final String? clockInTime;
  final String? clockOutTime;

  const EmployeeDTO({
    required this.id,
    required this.name,
    this.clockInTime,
    this.clockOutTime,
  });

  factory EmployeeDTO.fromJson(Map<String, dynamic> json) {
    return EmployeeDTO(
      id: json['id'] as String,
      name: json['name'] as String,
      clockInTime: json['clock_in_time'] as String?,
      clockOutTime: json['clock_out_time'] as String?,
    );
  }

  Employee toDomain() {
    final employee = Employee(
      id: EmployeeId(id),
      name: name,
    );

    if (clockInTime != null) {
      employee.clockIn(DateTime.parse(clockInTime!));
    }
    if (clockOutTime != null) {
      employee.clockOut(DateTime.parse(clockOutTime!));
    }

    return employee;
  }
}

The DTO lives in the infrastructure layer. It knows about JSON, while the domain entity knows nothing about JSON. The toDomain() method converts raw data into a properly constructed domain object, firing the business rules along the way.

Business Rules and Where They Live

Every business rule in a modular feature lives in the domain layer. This isn't a preference. It's the architectural contract that makes the entire approach work.

Value Objects enforce atomic, intrinsic rules. An email address must contain an @ symbol. A monetary amount can't be negative. An employee ID can't be empty. These rules are about the data itself, and they belong on the Value Object.

Entities enforce stateful rules. An employee can't clock in twice. A payment can't be processed if it has already been refunded. A task can't be completed if its dependencies aren't complete. These rules involve the state of the entity changing over time. They belong on the Entity.

Domain Services enforce rules that span multiple entities or require coordination. An employee can't approve their own leave request. A payment requires verification from both the payer and a fraud detection check. These rules involve multiple entities and don't naturally belong on any single one. They belong in a Domain Service.

The rule is simple and absolute: if something is a business rule, it lives in the domain layer. The application layer calls the domain. The infrastructure layer implements the domain's interfaces. The presentation layer reacts to the results. None of them define or modify business rules.

This boundary is what makes the system trustworthy. Business rules can't be bypassed by going directly to the database. They can't be skipped by calling a repository method directly from a widget. They're always enforced because the only way to change domain state is through the domain objects themselves.

Exception Handling and Safe State Propagation

When a business rule is violated in the domain layer, the domain throws a DomainException. This exception travels up through the application layer to the presentation layer where it's converted into UI state.

The key insight is that the exception doesn't crash the app. It's caught at a defined boundary and converted into a safe state that the UI can render.

Here's the complete flow:

// domain layer — throws when rules are violated
class Employee {
  void clockIn(DateTime time) {
    if (clockInTime != null && clockOutTime == null) {
      throw DomainException('Cannot clock in: already clocked in');
    }
    clockInTime = time;
  }
}

// application layer — catches domain exceptions and returns Result
class ClockInUseCase {
  final EmployeeRepository _repository;

  ClockInUseCase(this._repository);

  Future<Result<Employee, AppException>> execute(
    String employeeId,
    DateTime time,
  ) async {
    try {
      final employee = await _repository.findById(EmployeeId(employeeId));

      if (employee == null) {
        return Result.failure(AppException.notFound('Employee not found'));
      }

      employee.clockIn(time);
      await _repository.save(employee);

      return Result.success(employee);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

// presentation layer — converts result into UI state
@riverpod
class EmployeeNotifier extends _$EmployeeNotifier {
  @override
  AsyncValue<Employee?> build() => const AsyncData(null);

  Future<void> clockIn(String employeeId) async {
    state = const AsyncLoading();

    final result = await ref
        .read(clockInUseCaseProvider)
        .execute(employeeId, DateTime.now());

    result.fold(
      onSuccess: (employee) => state = AsyncData(employee),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

// widget — renders state, owns nothing
class EmployeeClockInWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(employeeNotifierProvider);

    return state.when(
      data: (employee) => employee != null
          ? ClockInSuccess(employee: employee)
          : const ClockInForm(),
      loading: () => const LoadingIndicator(),
      error: (error, _) => ErrorMessage(message: error.toString()),
    );
  }
}

The flow is linear and predictable:

1. User input triggers a use case.

2. The use case calls the domain.

3. The domain enforces rules.

4. If a rule is violated, a DomainException is thrown.

5. The use case catches it and returns a failure Result.

6. The notifier converts the Result into AsyncError state.

7. The widget renders the error.

At no point does the exception escape unhandled. And at no point does the widget touch business logic.

The Folder Structure

With these concepts in place, the folder structure follows naturally:

lib/
  shared/
    core/
      errors/
        domain_exception.dart
        app_exception.dart
      result/
        result.dart
      di/
        injection.dart
      utils/
        date_utils.dart

  features/
    employee/
      domain/
        entities/
          employee.dart
        value_objects/
          employee_id.dart
        repositories/
          employee_repository.dart
        services/
          attendance_domain_service.dart
        exceptions/
          employee_exceptions.dart

      application/
        use_cases/
          clock_in_usecase.dart
          clock_out_usecase.dart
          get_employee_usecase.dart

      infrastructure/
        datasources/
          employee_remote_datasource.dart
          employee_local_datasource.dart
        repositories/
          employee_repository_impl.dart
        dtos/
          employee_dto.dart

      presentation/
        notifier/
          employee_notifier.dart
          employee_notifier.g.dart
        state/
          employee_state.dart
        pages/
          employee_dashboard_page.dart
          clock_in_page.dart
        widgets/
          employee_card.dart
          clock_in_button.dart

    payment/
      domain/
        entities/
          payment.dart
        value_objects/
          money.dart
          payment_reference.dart
        repositories/
          payment_repository.dart
        services/
          payment_verification_service.dart

      application/
        use_cases/
          initiate_payment_usecase.dart
          verify_payment_usecase.dart
          refund_payment_usecase.dart

      infrastructure/
        datasources/
          payment_remote_datasource.dart
        repositories/
          payment_repository_impl.dart
        dtos/
          payment_dto.dart

      presentation/
        notifier/
          payment_notifier.dart
          payment_notifier.g.dart
        pages/
          payment_page.dart
          payment_confirmation_page.dart
        widgets/
          payment_summary_card.dart

  main.dart

The shared/core folder holds only what's genuinely shared across all features: base error types, the Result type, dependency injection configuration, and utilities that have no business logic. Everything else belongs inside a feature.

Each feature is a complete vertical slice. Every layer a feature needs lives inside that feature's folder. A developer working on the Employee feature never needs to navigate outside the features/employee directory to understand or modify the feature.

Real World Example One: The Employee Feature

The Employee feature manages the complete lifecycle of employee attendance in a workforce management application. Clock-in, clock-out, shift management, and attendance records.

The Domain

// value objects
class EmployeeId {
  final String value;

  EmployeeId(this.value) {
    if (value.isEmpty) throw DomainException('Employee ID cannot be empty');
  }
}

class ShiftDuration {
  final Duration duration;

  ShiftDuration(this.duration) {
    if (duration.isNegative) {
      throw DomainException('Shift duration cannot be negative');
    }
    if (duration.inHours > 16) {
      throw DomainException('Shift duration cannot exceed 16 hours');
    }
  }
}

// entity
class Employee {
  final EmployeeId id;
  final String name;
  final String teamId;
  DateTime? clockInTime;
  DateTime? clockOutTime;

  Employee({
    required this.id,
    required this.name,
    required this.teamId,
  });

  void clockIn(DateTime time) {
    if (isClockedIn) {
      throw DomainException('Employee is already clocked in');
    }
    clockInTime = time;
    clockOutTime = null;
  }

  void clockOut(DateTime time) {
    if (!isClockedIn) {
      throw DomainException('Employee is not clocked in');
    }
    if (time.isBefore(clockInTime!)) {
      throw DomainException('Clock out time cannot be before clock in time');
    }

    final shift = ShiftDuration(time.difference(clockInTime!));
    clockOutTime = time;
  }

  bool get isClockedIn => clockInTime != null && clockOutTime == null;

  Duration? get currentShiftDuration {
    if (!isClockedIn) return null;
    return DateTime.now().difference(clockInTime!);
  }
}

// repository interface — in the domain layer
abstract class EmployeeRepository {
  Future<Employee?> findById(EmployeeId id);
  Future<List<Employee>> findByTeam(String teamId);
  Future<void> save(Employee employee);
}

The Application Layer

class ClockInUseCase {
  final EmployeeRepository _repository;

  ClockInUseCase(this._repository);

  Future<Result<Employee, AppException>> execute(String employeeId) async {
    try {
      final id = EmployeeId(employeeId);
      final employee = await _repository.findById(id);

      if (employee == null) {
        return Result.failure(
          AppException.notFound('Employee $employeeId not found'),
        );
      }

      employee.clockIn(DateTime.now());
      await _repository.save(employee);

      return Result.success(employee);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

class ClockOutUseCase {
  final EmployeeRepository _repository;

  ClockOutUseCase(this._repository);

  Future<Result<Employee, AppException>> execute(String employeeId) async {
    try {
      final id = EmployeeId(employeeId);
      final employee = await _repository.findById(id);

      if (employee == null) {
        return Result.failure(
          AppException.notFound('Employee $employeeId not found'),
        );
      }

      employee.clockOut(DateTime.now());
      await _repository.save(employee);

      return Result.success(employee);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

The Infrastructure Layer

class EmployeeDTO {
  final String id;
  final String name;
  final String teamId;
  final String? clockInTime;
  final String? clockOutTime;

  const EmployeeDTO({
    required this.id,
    required this.name,
    required this.teamId,
    this.clockInTime,
    this.clockOutTime,
  });

  factory EmployeeDTO.fromJson(Map<String, dynamic> json) {
    return EmployeeDTO(
      id: json['id'] as String,
      name: json['name'] as String,
      teamId: json['team_id'] as String,
      clockInTime: json['clock_in_time'] as String?,
      clockOutTime: json['clock_out_time'] as String?,
    );
  }

  Employee toDomain() {
    final employee = Employee(
      id: EmployeeId(id),
      name: name,
      teamId: teamId,
    );

    if (clockInTime != null) {
      employee.clockIn(DateTime.parse(clockInTime!));
    }
    if (clockOutTime != null) {
      employee.clockOut(DateTime.parse(clockOutTime!));
    }

    return employee;
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'team_id': teamId,
      'clock_in_time': clockInTime,
      'clock_out_time': clockOutTime,
    };
  }
}

class EmployeeRepositoryImpl implements EmployeeRepository {
  final EmployeeRemoteDataSource _remote;

  EmployeeRepositoryImpl(this._remote);

  @override
  Future<Employee?> findById(EmployeeId id) async {
    final dto = await _remote.fetchEmployee(id.value);
    return dto?.toDomain();
  }

  @override
  Future<List<Employee>> findByTeam(String teamId) async {
    final dtos = await _remote.fetchTeamEmployees(teamId);
    return dtos.map((dto) => dto.toDomain()).toList();
  }

  @override
  Future<void> save(Employee employee) async {
    final dto = EmployeeDTO(
      id: employee.id.value,
      name: employee.name,
      teamId: employee.teamId,
      clockInTime: employee.clockInTime?.toIso8601String(),
      clockOutTime: employee.clockOutTime?.toIso8601String(),
    );
    await _remote.updateEmployee(dto);
  }
}

The Presentation Layer

@riverpod
class EmployeeNotifier extends _$EmployeeNotifier {
  @override
  AsyncValue<Employee?> build() => const AsyncData(null);

  Future<void> clockIn(String employeeId) async {
    state = const AsyncLoading();

    final result = await ref
        .read(clockInUseCaseProvider)
        .execute(employeeId);

    result.fold(
      onSuccess: (employee) => state = AsyncData(employee),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }

  Future<void> clockOut(String employeeId) async {
    state = const AsyncLoading();

    final result = await ref
        .read(clockOutUseCaseProvider)
        .execute(employeeId);

    result.fold(
      onSuccess: (employee) => state = AsyncData(employee),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

class EmployeeDashboardPage extends ConsumerWidget {
  final String employeeId;

  const EmployeeDashboardPage({required this.employeeId, super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(employeeNotifierProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('Employee Dashboard')),
      body: state.when(
        data: (employee) => employee != null
            ? EmployeeDashboardContent(
                employee: employee,
                onClockIn: () => ref
                    .read(employeeNotifierProvider.notifier)
                    .clockIn(employeeId),
                onClockOut: () => ref
                    .read(employeeNotifierProvider.notifier)
                    .clockOut(employeeId),
              )
            : const EmptyDashboard(),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (error, _) => ErrorView(message: error.toString()),
      ),
    );
  }
}

The widget knows nothing about clocking in, the EmployeeId Value Object, or the DomainException. It renders state and delegates actions to the notifier. Everything else happens in the layers below.

Real World Example Two: The Payment Feature

The Payment feature handles the complete payment lifecycle: initiation, processing, verification, and failure handling. This is a domain with complex business rules that benefit enormously from being modeled explicitly.

The Domain

enum PaymentStatus {
  pending,
  processing,
  completed,
  failed,
  refunded,
}

class PaymentReference {
  final String value;

  PaymentReference(this.value) {
    if (value.isEmpty) {
      throw DomainException('Payment reference cannot be empty');
    }
    if (!RegExp(r'^[A-Z0-9]{8,16}$').hasMatch(value)) {
      throw DomainException('Invalid payment reference format');
    }
  }
}

class Payment {
  final PaymentReference reference;
  final Money amount;
  final String payerId;
  final String recipientId;
  PaymentStatus status;
  String? failureReason;
  DateTime? processedAt;

  Payment({
    required this.reference,
    required this.amount,
    required this.payerId,
    required this.recipientId,
    this.status = PaymentStatus.pending,
  });

  void startProcessing() {
    if (status != PaymentStatus.pending) {
      throw DomainException(
        'Cannot process payment: current status is ${status.name}',
      );
    }
    status = PaymentStatus.processing;
  }

  void complete() {
    if (status != PaymentStatus.processing) {
      throw DomainException(
        'Cannot complete payment: current status is ${status.name}',
      );
    }
    status = PaymentStatus.completed;
    processedAt = DateTime.now();
  }

  void fail(String reason) {
    if (status != PaymentStatus.processing) {
      throw DomainException(
        'Cannot fail payment: current status is ${status.name}',
      );
    }
    status = PaymentStatus.failed;
    failureReason = reason;
  }

  void refund() {
    if (status != PaymentStatus.completed) {
      throw DomainException(
        'Cannot refund payment: only completed payments can be refunded',
      );
    }
    status = PaymentStatus.refunded;
  }

  bool get canBeRefunded => status == PaymentStatus.completed;
  bool get isTerminal =>
      status == PaymentStatus.completed ||
      status == PaymentStatus.failed ||
      status == PaymentStatus.refunded;
}

The Payment entity enforces every valid status transition. A payment that's already processing can't start processing again. A payment that hasn't completed can't be refunded. And a payment that has failed can't be completed.

These rules are encoded into the entity and enforced at every state change.

The Application Layer

class InitiatePaymentUseCase {
  final PaymentRepository _repository;

  InitiatePaymentUseCase(this._repository);

  Future<Result<Payment, AppException>> execute({
    required String reference,
    required double amount,
    required String currency,
    required String payerId,
    required String recipientId,
  }) async {
    try {
      final payment = Payment(
        reference: PaymentReference(reference),
        amount: Money(amount: amount, currency: currency),
        payerId: payerId,
        recipientId: recipientId,
      );

      payment.startProcessing();
      await _repository.save(payment);

      return Result.success(payment);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

class VerifyPaymentUseCase {
  final PaymentRepository _repository;
  final PaymentVerificationService _verificationService;

  VerifyPaymentUseCase(this._repository, this._verificationService);

  Future<Result<Payment, AppException>> execute(String reference) async {
    try {
      final ref = PaymentReference(reference);
      final payment = await _repository.findByReference(ref);

      if (payment == null) {
        return Result.failure(
          AppException.notFound('Payment $reference not found'),
        );
      }

      final isVerified = await _verificationService.verify(payment);

      if (isVerified) {
        payment.complete();
      } else {
        payment.fail('Verification failed');
      }

      await _repository.save(payment);
      return Result.success(payment);
    } on DomainException catch (e) {
      return Result.failure(AppException.businessRule(e.message));
    } catch (e) {
      return Result.failure(AppException.unknown(e.toString()));
    }
  }
}

The Presentation Layer

@riverpod
class PaymentNotifier extends _$PaymentNotifier {
  @override
  AsyncValue<Payment?> build() => const AsyncData(null);

  Future<void> initiatePayment({
    required String reference,
    required double amount,
    required String currency,
    required String payerId,
    required String recipientId,
  }) async {
    state = const AsyncLoading();

    final result = await ref.read(initiatePaymentUseCaseProvider).execute(
          reference: reference,
          amount: amount,
          currency: currency,
          payerId: payerId,
          recipientId: recipientId,
        );

    result.fold(
      onSuccess: (payment) => state = AsyncData(payment),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }

  Future<void> verifyPayment(String reference) async {
    state = const AsyncLoading();

    final result = await ref
        .read(verifyPaymentUseCaseProvider)
        .execute(reference);

    result.fold(
      onSuccess: (payment) => state = AsyncData(payment),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

class PaymentPage extends ConsumerWidget {
  const PaymentPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(paymentNotifierProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('Payment')),
      body: state.when(
        data: (payment) {
          if (payment == null) return const PaymentForm();
          return PaymentStatusView(payment: payment);
        },
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (error, _) => PaymentErrorView(message: error.toString()),
      ),
    );
  }
}

Cross-Feature Communication

Self-contained features inevitably need to communicate. The Employee feature might need to check if a user is authenticated. The Payment feature might need to notify the Employee feature about a salary disbursement.

The rules for cross-feature communication preserve the self-containment of each feature:

1. Features never import directly from each other's internal layers.

The Employee feature should never import from features/payment/domain/entities/payment.dart. Direct imports between features create tight coupling that defeats the purpose of modularization.

2. Shared domain concepts live in shared/core.

If both the Employee feature and the Payment feature need a concept like a UserId or a Money value object, that concept lives in shared/core/domain and both features import from there.

3. Cross-feature communication happens through defined interfaces.

If the Payment feature needs to know about an employee to process a salary, it depends on an EmployeeService interface defined in shared/core. The Employee feature provides the implementation. The Payment feature never knows which feature provided it.

4. Events and domain notifications use a shared event bus.

When a payment completes, the Payment feature publishes a PaymentCompleted domain event. Any feature that needs to react to payment completion subscribes to that event. The Payment feature doesn't know who's listening. The listening features don't import from the Payment feature directly.

Patterns That Enhance Modularization

Certain design patterns work particularly well within a modularized feature structure.

The Prototype Pattern is useful for creating employee templates in the Employee feature. An organization might have standard employee profiles for different roles. Cloning a template employee creates a new instance with the same configuration, allowing business rules to fire during the clone's state transitions rather than being bypassed.

class Employee {
  Employee clone() {
    return Employee(
      id: EmployeeId('${id.value}_copy_${DateTime.now().millisecondsSinceEpoch}'),
      name: name,
      teamId: teamId,
    );
  }
}

The Singleton Pattern applies to genuinely unique domain objects. The currently authenticated user is a Singleton. The current session is a Singleton. These live in shared/core because they are cross-feature concerns.

The Repository Pattern is the backbone of infrastructure abstraction in every feature. Domain layers define the interface. Infrastructure layers provide the implementation. Application layers use the interface without knowing which implementation is behind it.

The Observer Pattern, through domain events, enables cross-feature communication without tight coupling. Each feature publishes events when significant domain state changes. Other features subscribe to those events through a shared event bus.

Scaling to Large Teams

Feature Modularization becomes even more valuable as teams grow. At ten engineers working on different features simultaneously, the self-contained nature of each feature prevents constant merge conflicts. Engineers working on the Employee feature and engineers working on the Payment feature are almost never touching the same files.

At thirty engineers, features can become separate Dart packages. The Employee feature becomes packages/employee. The Payment feature becomes packages/payment. They depend on a shared packages/core package. Each package has its own pubspec.yaml, its own tests, and can be independently versioned. This is the next level of modularization and it follows naturally from the feature-first structure.

At fifty engineers, teams can own entire features. The Employee team owns packages/employee. The Payment team owns packages/payment. The contracts between features, defined through interfaces in packages/core, become the API boundaries between teams. A team can release a new version of their feature package independently, and other teams update to that version when they're ready.

The folder structure you start with today is the same structure that scales to a package-based monorepo at fifty engineers. The concepts don't change. The boundaries just become more explicit.

Conclusion

Feature Modularization isn't a folder structure trick. It's a strategic decision about how to organize software so that it can grow without degrading.

It takes Clean Architecture's layering rules and DDD's domain modeling vocabulary and applies them at the feature level. Each feature owns its domain, business rules, data access, and UI. Nothing leaks out or bleeds in. Each feature can be understood, modified, and tested without understanding the entire application.

The Employee feature enforces attendance rules in its entity. The Payment feature enforces transaction state transitions in its entity. Both features use Value Objects to prevent invalid data from ever entering the domain. Both features use the same Result pattern to propagate failures safely from the domain through the application layer to the presentation layer.

When a new requirement arrives for the Employee feature, you open the employee folder and make the change. The Payment feature is untouched. When a new payment method is added to the Payment feature, you open the payment folder and make the change. The Employee feature is untouched.

This is what self-contained actually means. Not just a folder with a name. A complete vertical slice of your application that owns everything it needs and shares nothing it should not.

That is Feature Modularization. And that's how Flutter apps scale from one engineer to fifty without the codebase becoming a liability.

Happy Coding!!

A user logs in, and the app needs to save a token, cache the user profile, fire an analytics event, and navigate to the home screen.

A payment is confirmed, and the inventory needs to update, the user needs a receipt, and the fulfillment system needs to kick off delivery.

A sensor reading changes, and three different UI panels need to reflect the new value simultaneously.

The naïve solution is to write all of that logic in one place. One function that does everything or one class that knows about everything.

This works at first. Then requirements change. A new reaction needs to be added. An existing one needs to be removed. A side effect starts failing and takes everything else down with it. The code becomes a wall of responsibilities that's impossible to test, painful to extend, and dangerous to touch.

The Observer Design Pattern exists to solve exactly this problem. It gives you a structured, production-grade way to say: when this event happens, notify everyone who cares, without the event source knowing who those people are.

In this handbook, you'll learn the Observer pattern from first principles. You'll see how it's implemented in Dart, understand how it connects to Event-Driven Architecture, and discover how it integrates cleanly with Domain-Driven Design and Riverpod in a real Flutter application.

By the end, you won't just understand the pattern. You'll know how to use it deliberately in production code.

Table of Contents

• What is the Observer Design Pattern?

• The Problem It Solves

• Core Components

• Implementing Observer in Dart

• A Real-World Example: The Login Flow

• Making It Production-Grade with a Generic EventBus

• Observer Is Already in Your Flutter Code

• Deep Dive Into Event-Driven Architecture

• Application in Domain-Driven Design

• The Riverpod Hybrid: Clean Architecture in Practice

• Testing the Observer Architecture

• When to Use the Observer Pattern

• When Not to Use It

• Conclusion

What is the Observer Design Pattern?

The Observer pattern is a behavioural design pattern that defines a one-to-many dependency between objects. When one object changes state or fires an event, all of its dependents are notified and updated automatically.

Think of a newspaper subscription service. The newspaper publisher doesn't know who its individual subscribers are. It doesn't call each reader personally. It publishes the paper, and every subscriber who signed up receives it.

A subscriber can cancel at any time. A new subscriber can join at any time. The publisher's job never changes. It just publishes.

That's the Observer pattern in plain terms.

The publisher is called the Subject. The subscribers are called Observers. The newspaper is the event.

The pattern was formally defined in the Gang of Four book, Design Patterns: Elements of Reusable Object-Oriented Software. It remains one of the most widely used patterns in software engineering, especially in reactive and event-driven systems.

The Problem It Solves

Let's look at what happens without the Observer pattern.

Say you have a login feature. When login succeeds, you need to do four things:

• Save the authentication token to secure storage

• Cache the user profile data

• Navigate to the home screen

• Fire an analytics event

The straightforward approach puts all of this inside the login function:

Future<void> login(String email, String password) async {
  final response = await _authRepository.login(email, password);

  await _secureStorage.write(key: 'token', value: response.token);
  await _userCache.save(response.user);
  _navigationService.navigateTo('/home');
  _analytics.track('login_success', {'userId': response.user.id});
}

This looks fine at first glance. But count how many reasons this single function has to change:

• The token storage strategy changes. You modify this function.

• The navigation destination changes. You modify this function.

• The analytics event name or payload changes. You modify this function.

• The user caching logic changes. You modify this function.

Every single change to any of these four concerns forces you back into this one function. And every time you touch it, you risk breaking all the other three things it's doing.

Now imagine you need to add a fifth thing, such as enrolling the user in push notifications. You open this function again. You add more code. The function grows. Testing it requires mocking four, then five different dependencies. New teammates struggle to understand what this function is actually responsible for. The answer, of course, is everything. And that's the problem.

This is called tight coupling. The login logic is coupled to every single consequence of a successful login.

The Observer pattern breaks these couplings completely. The login logic does one thing: it performs the login and announces the result. Every consequence is handled by a separate, independent observer. Each observer has one job. None of them know about each other. The login logic doesn't know they exist.

Core Components

The Observer pattern has four core building blocks. Understanding each one before writing code makes the implementation much easier to follow.

Subject

The Subject is the object that something happens to. It holds a list of observers and is responsible for notifying them when an event occurs. It exposes methods for observers to register and unregister themselves. The Subject doesn't care what observers do with the notification. It just delivers it.

Observer

The Observer is an interface or abstract class that defines the contract all observers must follow. It declares the method or methods the Subject will call when notifying. Any class that wants to react to an event must implement this interface.

Concrete Subject

The Concrete Subject is the real implementation of the Subject. It manages the actual list of observers, handles subscriptions, and fires notifications at the right moment.

Concrete Observers

These are the real classes that implement the Observer interface. Each one has a specific, focused job to do when notified. One saves the token. One navigates. One fires analytics. They don't know about each other and don't need to.

Here's how they relate to each other:

Subject (LoginService)
    |
    |-- subscribe(observer)    <- observer registers itself
    |-- unsubscribe(observer)  <- observer removes itself
    |-- notifySuccess(data)    <- fires when login succeeds
    |-- notifyFailure(error)   <- fires when login fails
         |
         |-----> TokenObserver.onLoginSuccess()
         |-----> UserObserver.onLoginSuccess()
         |-----> NavigationObserver.onLoginSuccess()
         |-----> AnalyticsObserver.onLoginSuccess()

The Subject notifies all of them. They each handle their own job independently.

Implementing Observer in Dart

Let's build the pattern step by step.

Step 1: Define the Observer Interface

abstract class LoginObserver {
  void onLoginSuccess(UserDto user);
  void onLoginFailed(AppException error);
}

This is the contract that every observer must sign. Any class that wants to react to login events must implement both of these methods.

onLoginSuccess is called when the login succeeds and receives the user data. onLoginFailed is called when the login fails and receives the error.

Step 2: Define the Subject Interface

abstract class LoginSubject {
  void subscribe(LoginObserver observer);
  void unsubscribe(LoginObserver observer);
  void notifySuccess(UserDto user);
  void notifyFailure(AppException error);
}

subscribe lets an observer join the notification list. unsubscribe lets an observer leave the notification list. notifySuccess broadcasts a success event with the user data to all registered observers. notifyFailure broadcasts a failure event with the error to all registered observers.

Defining this as an abstract class instead of going straight to a concrete class is important. It means anything that depends on the subject depends on the abstraction, not the implementation. This makes your code testable and swappable.

Step 3: Implement the Concrete Subject

class LoginService implements LoginSubject {
  final List<LoginObserver> _observers = [];

  @override
  void subscribe(LoginObserver observer) {
    _observers.add(observer);
  }

  @override
  void unsubscribe(LoginObserver observer) {
    _observers.remove(observer);
  }

  @override
  void notifySuccess(UserDto user) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onLoginSuccess(user);
      } catch (e) {
        debugPrint('Observer error on success: $e');
      }
    }
  }

  @override
  void notifyFailure(AppException error) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onLoginFailed(error);
      } catch (e) {
        debugPrint('Observer error on failure: $e');
      }
    }
  }
}

There are two important decisions in this implementation that are easy to miss.

1. Snapshot iteration with List.of()

Instead of iterating directly over _observers, we iterate over List.of(_observers), which creates a copy of the list before the loop runs.

Why does this matter? Imagine a NavigationObserver that, after navigating to the home screen, unsubscribes itself because it no longer needs to listen. If it calls unsubscribe while the notifySuccess loop is still running over the same list, Dart throws a ConcurrentModificationError. The list is being modified while it's being read.

List.of() prevents this entirely. The loop runs over the snapshot. The original list can be modified freely during iteration without any errors.

2. Per-observer try/catch

Each observer call is wrapped in its own try/catch block. This is a deliberate choice. If TokenObserver throws an exception while writing to secure storage, you don't want NavigationObserver and AnalyticsObserver to silently never fire. Each observer gets its chance to run regardless of what the others do.

Without this, one failing observer would stop the entire notification chain. That's a hidden bug that's extremely difficult to trace in production.

A Real-World Example: The Login Flow

Now let's build the full login flow using this foundation.

The Login Logic

class LoginLogic {
  final LoginSubject _subject;
  final AuthRepository _repository;

  LoginLogic({
    required LoginSubject subject,
    required AuthRepository repository,
  })  : _subject = subject,
        _repository = repository;

  Future<void> callLogin(LoginRequest request) async {
    try {
      final user = await _repository.login(request);
      _subject.notifySuccess(user);
    } on AppException catch (e) {
      _subject.notifyFailure(e);
    } catch (e) {
      _subject.notifyFailure(AppException.unknown(message: e.toString()));
    }
  }
}

Let's walk through this carefully.

LoginLogic takes two dependencies through its constructor: a LoginSubject and an AuthRepository. Notice it takes LoginSubject, the abstraction, not LoginService, the concrete class. This means you can swap the implementation in tests or in different environments without changing LoginLogic at all.

Inside callLogin, the logic is straightforward. It calls the repository to perform the actual login. If that succeeds, it calls notifySuccess on the subject with the returned user. If it throws an AppException, it calls notifyFailure with that error. If it throws anything unexpected, it wraps it in an AppException.unknown and notifies failure.

Notice what LoginLogic does NOT do. It doesn't save a token. It doesn't navigate anywhere. It doesn't cache anything. It doesn't fire analytics. And it doesn't know how many observers exist or what they do.

Its entire responsibility is: perform the login, announce the result.

The Concrete Observers

class TokenObserver implements LoginObserver {
  final SecureStorageService _storage;

  TokenObserver(this._storage);

  @override
  void onLoginSuccess(UserDto user) {
    _storage.write(key: 'auth_token', value: user.token);
  }

  @override
  void onLoginFailed(AppException error) {
    _storage.delete(key: 'auth_token');
  }
}

TokenObserver has one job: manage the authentication token. On success, it saves the token. On failure, it clears any stale token that might be sitting in storage. It knows nothing about navigation, caching, or analytics.

class UserObserver implements LoginObserver {
  final UserCacheService _cache;

  UserObserver(this._cache);

  @override
  void onLoginSuccess(UserDto user) {
    _cache.save(user);
  }

  @override
  void onLoginFailed(AppException error) {
    _cache.clear();
  }
}

UserObserver has one job: manage the user cache. On success, it saves the user profile. On failure, it clears the cache. It knows nothing about tokens, navigation, or analytics.

class NavigationObserver implements LoginObserver {
  final NavigationService _navigation;

  NavigationObserver(this._navigation);

  @override
  void onLoginSuccess(UserDto user) {
    _navigation.navigateTo('/home');
  }

  @override
  void onLoginFailed(AppException error) {
    _navigation.showError(error.message);
  }
}

NavigationObserver has one job: handle navigation after a login attempt. It uses an injected NavigationService abstraction rather than a BuildContext. This is intentional. An observer that depends on BuildContext is tied to the widget lifecycle. Using an abstraction keeps this observer completely independent of the UI layer.

class AnalyticsObserver implements LoginObserver {
  final AnalyticsService _analytics;

  AnalyticsObserver(this._analytics);

  @override
  void onLoginSuccess(UserDto user) {
    _analytics.track('login_success', {'userId': user.id});
  }

  @override
  void onLoginFailed(AppException error) {
    _analytics.track('login_failed', {'reason': error.message});
  }
}

AnalyticsObserver has one job: fire the right analytics event for each outcome. It has no knowledge of storage, navigation, or caching.

Each observer has exactly one responsibility. Each one has exactly one reason to change. When the analytics payload needs to change, you touch only AnalyticsObserver. When navigation logic changes, you touch only NavigationObserver. Nothing else is affected.

Wiring It Together

void setupLogin() {
  final service = LoginService();

  service
    ..subscribe(TokenObserver(secureStorage))
    ..subscribe(UserObserver(userCache))
    ..subscribe(NavigationObserver(navigationService))
    ..subscribe(AnalyticsObserver(analyticsService));

  final loginLogic = LoginLogic(
    subject: service,
    repository: authRepository,
  );
}

This is the composition step. All observers are created with their dependencies and registered onto the service. The cascade operator .. calls subscribe multiple times on the same service object, which keeps the setup readable.

LoginLogic receives the service as its LoginSubject. From this point forward, every time callLogin is called and an outcome occurs, all four observers are notified automatically.

Adding a fifth observer, say a PushNotificationObserver, means creating the class and adding one line here: ..subscribe(PushNotificationObserver(pushService)). Nothing else in the entire codebase changes.

Making It Production-Grade with a Generic EventBus

The login example above works well, but it's specific to login. In a real application, many features have the same fan-out requirement. Payment confirmed, order placed, profile updated, session expired. All of them need one event to trigger multiple independent reactions.

Rewriting the Subject and Observer interfaces per feature is repetitive and unnecessary. The better approach is a generic EventBus that any feature can use.

abstract class DomainObserver<T> {
  void onSuccess(T data);
  void onFailure(AppException error);
}

DomainObserver<T> is a generic observer. The type parameter T represents the data type the observer expects on success. A login observer would be DomainObserver<UserDto>. A payment observer would be DomainObserver<PaymentDto>. The interface is the same. The data type changes per feature.

class EventBus<T> {
  final List<DomainObserver<T>> _observers = [];

  void subscribe(DomainObserver<T> observer) {
    _observers.add(observer);
  }

  void unsubscribe(DomainObserver<T> observer) {
    _observers.remove(observer);
  }

  void publishSuccess(T data) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onSuccess(data);
      } catch (e) {
        debugPrint('[EventBus] Observer error on success: $e');
      }
    }
  }

  void publishFailure(AppException error) {
    for (final observer in List.of(_observers)) {
      try {
        observer.onFailure(error);
      } catch (e) {
        debugPrint('[EventBus] Observer error on failure: $e');
      }
    }
  }
}

EventBus<T> is a generic subject. It manages a list of typed observers and notifies them with the same snapshot iteration and per-observer error isolation we established earlier.

Now every feature gets the same infrastructure without duplicating a single line of the pattern:

final loginBus = EventBus<UserDto>();
final paymentBus = EventBus<PaymentDto>();
final orderBus = EventBus<OrderDto>();

Each bus is typed to its domain concept. Observers registered on loginBus will never accidentally receive payment events. The type system enforces correctness.

Observer Is Already in Your Flutter Code

Before going further into architecture, here's something worth pausing on. You've been using the Observer pattern all along without calling it by that name.

Streams and StreamController:

final controller = StreamController<String>();

controller.stream.listen((event) {
  print('Observed: $event');
});

controller.sink.add('Login succeeded');

StreamController is a Subject. stream.listen is subscribe. sink.add is notifyObservers. Every stream subscription is an Observer. The pattern is identical. Flutter just gave it different names.

ChangeNotifier:

class CounterModel extends ChangeNotifier {
  int _count = 0;

  void increment() {
    _count++;
    notifyListeners();
  }
}

notifyListeners() iterates over every registered listener and calls them. Those listeners are Observers. addListener is subscribe. removeListener is unsubscribe. ChangeNotifier is a concrete Subject.

BLoC:

When a BLoC emits a new state, every widget that wrapped itself in a BlocBuilder or BlocListener reacts. The BLoC is the Subject. The builders and listeners are Observers. The state emission is the notification.

Flutter's entire reactive system (Streams, ChangeNotifier, BLoC, ValueNotifier) is the Observer pattern with lifecycle management built in. Understanding the pattern at this fundamental level means you understand why all of these tools work the way they do. You aren't just using them. You understand them.

Deep Dive Into Event-Driven Architecture

Understanding Observer at the class level is the foundation. The pattern becomes significantly more powerful when applied at the architectural level, and that's where Event-Driven Architecture comes in.

What is Event-Driven Architecture?

Event-Driven Architecture is a design paradigm where the flow of the application is determined by events. Instead of components calling each other directly, they communicate by producing and consuming events through a shared bus or channel.

In a traditional request-driven flow, this is what happens:

Component A calls Component B directly
Component B does its work and returns a result
Component A waits for that result and then continues

Component A knows about Component B. It depends on it by name. It waits for it to finish. If you want Component C to also react to whatever Component A is doing, you have to go back into Component A and add that call.

But then Component A grows. Component A becomes responsible for orchestrating consequences it should know nothing about.

In an event-driven flow, this is what happens instead:

Component A publishes an event to the EventBus
EventBus delivers the event to whoever is registered

Component B handles the event
Component C handles the event
Component D handles the event

Component A doesn't know about B, C, or D. It doesn't wait for them. It publishes what happened and moves on. New handlers can be added without touching Component A at all. This is the Observer pattern scaled to the architectural level.

Events Are Facts, Not Commands

This distinction is one of the most important concepts in Event-Driven Architecture.

A command says: "do this." It's an instruction that can be rejected. It expects a response.

An event says: "this happened." It's an immutable record of a fact. It doesn't expect a response. It doesn't care who handles it.

SaveUserToken is a command. UserLoggedIn is an event.

When you model your system with events as facts, you get a historical record of everything that happened in your application. You can replay events to reconstruct state. You can add new handlers that process historical events. Your system becomes auditable and predictable in ways that command-driven systems are not.

Modelling Domain Events in Dart

Events should be immutable value objects. They're facts. Facts don't change after they happen.

abstract class DomainEvent {
  final DateTime occurredAt;
  final String eventId;

  const DomainEvent({
    required this.occurredAt,
    required this.eventId,
  });
}

DomainEvent is the base class for all events in the system. Every event has a timestamp (occurredAt) recording when it happened, and a unique identifier (eventId) for traceability.

class UserLoggedIn extends DomainEvent {
  final UserDto user;

  const UserLoggedIn({
    required this.user,
    required super.occurredAt,
    required super.eventId,
  });
}

class LoginFailed extends DomainEvent {
  final AppException error;

  const LoginFailed({
    required this.error,
    required super.occurredAt,
    required super.eventId,
  });
}

UserLoggedIn carries the user data. LoginFailed carries the error. Both are immutable. Both have timestamps and identifiers. Both are concrete facts about something that happened in the domain.

A Type-Safe DomainEventBus

Now we can build an event bus that's typed to domain events specifically:

abstract class EventHandler<T extends DomainEvent> {
  void handle(T event);
}

EventHandler<T> is the Observer interface for this architecture. Any class that wants to handle a domain event implements this with the specific event type it cares about.

class DomainEventBus {
  final _handlers = <Type, List<EventHandler>>{};

  void register<T extends DomainEvent>(EventHandler<T> handler) {
    _handlers.putIfAbsent(T, () => []).add(handler);
  }

  void publish<T extends DomainEvent>(T event) {
    final handlers = List.of(_handlers[T] ?? []);
    for (final handler in handlers) {
      try {
        (handler as EventHandler<T>).handle(event);
      } catch (e) {
        debugPrint('[DomainEventBus] Handler error for ${T}: $e');
      }
    }
  }
}

Let's go through DomainEventBus carefully.

_handlers is a map where the key is a Type (the event class itself, like UserLoggedIn) and the value is a list of all handlers registered for that event type.

register<T> takes a handler and adds it to the list for type T. putIfAbsent ensures the list is created if this is the first handler for that event type.

publish<T> looks up all handlers registered for the type of event being published and calls each one's handle method. The snapshot with List.of() and the per-handler try/catch are both present for the same reasons we established earlier.

Here's how you register handlers and publish events:

// Registration happens once at startup
eventBus.register<UserLoggedIn>(TokenHandler(secureStorage));
eventBus.register<UserLoggedIn>(UserCacheHandler(userCache));
eventBus.register<UserLoggedIn>(NavigationHandler(navigationService));
eventBus.register<UserLoggedIn>(AnalyticsHandler(analyticsService));

eventBus.register<PaymentConfirmed>(ReceiptHandler(receiptService));
eventBus.register<PaymentConfirmed>(InventoryHandler(inventoryService));

// Publishing happens at the use case level
eventBus.publish(UserLoggedIn(
  user: user,
  occurredAt: DateTime.now(),
  eventId: const Uuid().v4(),
));

When UserLoggedIn is published, only its registered handlers fire. Payment handlers aren't touched. Every handler for UserLoggedIn runs independently with full error isolation.

Application in Domain-Driven Design

Event-Driven Architecture and the Observer pattern find their most structured home inside Domain-Driven Design. DDD gives us the vocabulary and structure to know exactly where events belong, who creates them, and who handles them.

Key DDD Concepts You Need to Know

Domain Events are first-class citizens in DDD. They represent something meaningful that happened in the business domain. Not a technical detail, not an HTTP response, but a business fact.

UserLoggedIn is a domain event. LoginResponseDto is a data transfer object. The distinction matters deeply. The event belongs to the domain model and expresses business language. The DTO belongs to the data layer and expresses data structure.

Aggregates are the natural source of domain events. An Aggregate is a cluster of domain objects that form a consistency boundary. The Aggregate enforces business rules and raises domain events when significant state changes occur within it.

Use Cases are the orchestrators. A use case calls the repository, gets the result, raises the appropriate domain event, and returns the outcome. It doesn't handle side effects directly. It announces what happened and lets the registered handlers take over.

Where Everything Lives in Clean Architecture

lib/
  core/
    events/
      domain_event.dart           <- Base DomainEvent class
      domain_event_bus.dart       <- The DomainEventBus
      event_handler.dart          <- Base EventHandler interface

  features/
    auth/
      domain/
        events/
          user_logged_in.dart     <- Domain event (pure Dart, no Flutter)
          login_failed.dart       <- Domain event
        handlers/
          token_handler.dart      <- Handles token storage
          user_cache_handler.dart <- Handles user caching
          analytics_handler.dart  <- Handles analytics
        entities/
          user.dart
        repositories/
          auth_repository.dart    <- Abstract interface only
        usecases/
          login_usecase.dart      <- Orchestrates, publishes events

      data/
        repositories/
          auth_repository_impl.dart
        datasources/
          auth_remote_datasource.dart

      presentation/
        providers/
          login_provider.dart     <- Riverpod notifier (thin)
        pages/
          login_page.dart

The critical rule: the domain layer is pure Dart. No Flutter imports. No Riverpod imports. No HTTP imports. The DomainEventBus, domain events, handlers, and use cases all live in the domain layer and have zero framework dependencies.

This means that the same domain logic works in Flutter, server-side Dart, or a CLI tool without changing a single line. Framework upgrades, say from Riverpod 2.x to a future version, never touch the domain. Unit tests for the domain run in milliseconds with no widget test overhead.

The Login Use Case in DDD

class LoginUseCase {
  final AuthRepository _repository;
  final DomainEventBus _eventBus;

  LoginUseCase({
    required AuthRepository repository,
    required DomainEventBus eventBus,
  })  : _repository = repository,
        _eventBus = eventBus;

  Future<Result<UserDto, AppException>> execute(LoginRequest request) async {
    try {
      final user = await _repository.login(request);

      _eventBus.publish(UserLoggedIn(
        user: user,
        occurredAt: DateTime.now(),
        eventId: const Uuid().v4(),
      ));

      return Result.success(user);
    } on AppException catch (e) {
      _eventBus.publish(LoginFailed(
        error: e,
        occurredAt: DateTime.now(),
        eventId: const Uuid().v4(),
      ));

      return Result.failure(e);
    }
  }
}

Let's walk through this step by step.

LoginUseCase receives two dependencies: an AuthRepository abstraction and a DomainEventBus. Neither is a concrete class. Both can be swapped in tests.

Inside execute, it calls the repository to perform the login. If the login succeeds, it publishes a UserLoggedIn event to the bus, which immediately notifies all registered handlers. Then it returns a Result.success wrapping the user data.

If an AppException is caught, it publishes a LoginFailed event to the bus, which notifies all failure handlers. Then it returns a Result.failure wrapping the error.

The use case doesn't know how many handlers are registered. It doesn't know what they do. It performs the operation, publishes the outcome as a domain event, and returns the result.

The Result type is a return value for the caller (the Riverpod notifier) to know the outcome. The domain event is the broadcast for all side effect handlers. Both travel from the same single use case call. This is what makes the architecture clean.

The Riverpod Hybrid: Clean Architecture in Practice

This is where everything comes together in a real Flutter application.

The Problem We Are Solving

There are two common pain points in Flutter apps that use Riverpod:

Fat ref.listen in widgets:

// This is messy
ref.listen<AsyncValue<UserDto?>>(loginProvider, (previous, next) {
  next.whenData((user) {
    if (user != null) {
      secureStorage.write(key: 'token', value: user.token);
      userCache.save(user);
      context.go('/home');
      analytics.track('login_success');
    }
  });
});

The widget is mounted. If it unmounts before all of this completes, some side effects may never run. Business consequences like token storage and navigation shouldn't depend on whether a widget is still alive. This is fragile architecture.

Fat notifiers:

// Notifier doing too much
Future<void> login(LoginRequest request) async {
  state = const AsyncLoading();
  try {
    final user = await _loginUseCase.execute(request);
    await _secureStorage.write(key: 'token', value: user.token);
    await _userCache.save(user);
    _navigationService.navigateTo('/home');
    _analytics.track('login_success');
    state = AsyncData(user);
  } catch (e, st) {
    state = AsyncError(e, st);
  }
}

The notifier is violating the Single Responsibility Principle. It's performing the login, saving the token, caching the user, navigating, tracking analytics, and managing UI state. That's six responsibilities in one class. It's impossible to test cleanly and painful to maintain.

The Clean Rule

Before looking at the solution, establish this rule clearly:

The use case owns domain consequences. The notifier owns UI state. Widgets own nothing.

The use case performs the operation and publishes domain events. Handlers fire when those events are published and run completely independently of the widget lifecycle. The notifier receives the result from the use case and emits loading, success, or error state so the UI knows what to display. Widgets read that state and render accordingly.

That's the full picture. And it means this architecture works correctly whether login is triggered from a widget, a biometric prompt, a deep link, or a background service. The use case always publishes. The handlers always fire. The notifier only deals with UI state.

Understanding AsyncNotifier

Before writing the notifier, let's understand what AsyncNotifier is and how it works.

AsyncNotifier is a Riverpod 2.0 class designed specifically for asynchronous state. It holds an AsyncValue<T>, which is a sealed type that can be one of three things:

AsyncData<T> means the operation succeeded and data is available. AsyncLoading means an operation is in progress. AsyncError means an operation failed.

When you extend AsyncNotifier<T>, you implement a build method that returns the initial state, and you write methods that mutate state as async operations progress.

With code generation using @riverpod, you annotate your class and run flutter pub run build_runner build. The generator creates the provider and all the boilerplate automatically. You focus entirely on the logic.

Here's the full setup for code generation:

# pubspec.yaml
dependencies:
  flutter_riverpod: ^2.5.1
  riverpod_annotation: ^2.3.5

dev_dependencies:
  riverpod_generator: ^2.4.0
  build_runner: ^2.4.9

The Thin Notifier

// login_provider.dart
part 'login_provider.g.dart';

@riverpod
class LoginNotifier extends _$LoginNotifier {

  @override
  AsyncValue<UserDto?> build() {
    return const AsyncData(null);
  }

  Future<void> login(LoginRequest request) async {
    state = const AsyncLoading();

    final result = await ref.read(loginUseCaseProvider).execute(request);

    result.fold(
      onSuccess: (user) => state = AsyncData(user),
      onFailure: (error) => state = AsyncError(error, StackTrace.current),
    );
  }
}

Let's go through this line by line.

part 'login_provider.g.dart' tells Dart that the generated file is part of this library. The @riverpod annotation and _$LoginNotifier base class come from the generated file.

build() is the initialisation method. It runs when the provider is first read. It returns AsyncData(null), meaning the initial state is a successful state with no user yet. This is correct because no login has been attempted.

Inside login, the first thing we do is set state = const AsyncLoading(). This immediately notifies any widget watching this provider that an operation is in progress. The UI can show a loading indicator.

We then call the use case and await its result. The use case returns a Result<UserDto, AppException>, which is a type that holds either a success value or a failure value, never both. We call fold on it to handle each case.

In the onSuccess branch, we set state = AsyncData(user). This tells the UI the operation succeeded and here is the user data to render.

In the onFailure branch, we set state = AsyncError(error, StackTrace.current). This tells the UI something went wrong so it can display the appropriate error state.

That's the entire notifier. It does exactly one thing: reflect the outcome of the use case as UI state.

Notice there's no token saving here. No navigation, caching, or analytics. All of that is already handled. The moment the use case called _eventBus.publish(UserLoggedIn(...)) inside execute, every registered handler fired automatically. By the time result is returned to this notifier, all side effects are already done. The notifier just needs to update the UI.

This is the cleanest possible separation. The use case owns domain consequences. The notifier owns render state. Each has exactly one responsibility.

The Widget

class LoginPage extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final loginState = ref.watch(loginNotifierProvider);

    return Scaffold(
      body: loginState.when(
        data: (_) => const LoginForm(),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (error, _) => ErrorView(message: error.toString()),
      ),
    );
  }
}

class LoginForm extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return Column(
      children: [
        ElevatedButton(
          onPressed: () {
            ref.read(loginNotifierProvider.notifier).login(
              LoginRequest(email: 'user@example.com', password: 'secret'),
            );
          },
          child: const Text('Login'),
        ),
      ],
    );
  }
}

ref.watch(loginNotifierProvider) subscribes this widget to the notifier's state. Every time state changes inside the notifier, build is called again and the widget re-renders.

loginState.when is how you handle each case of AsyncValue. When the state is AsyncData, it renders the login form. When it is AsyncLoading, it renders a loading indicator. When it is AsyncError, it renders the error view.

The widget knows nothing about tokens, navigation, or caching. It renders what it's told to render by the state. That's its entire job.

Wiring the Composition Root

All handler registrations happen once at app startup inside a Riverpod provider:

@riverpod
DomainEventBus eventBus(EventBusRef ref) {
  final bus = DomainEventBus();

  bus.register<UserLoggedIn>(
    TokenHandler(ref.read(secureStorageProvider)),
  );
  bus.register<UserLoggedIn>(
    UserCacheHandler(ref.read(userCacheProvider)),
  );
  bus.register<UserLoggedIn>(
    NavigationHandler(ref.read(navigationServiceProvider)),
  );
  bus.register<UserLoggedIn>(
    AnalyticsHandler(ref.read(analyticsServiceProvider)),
  );

  bus.register<LoginFailed>(
    AnalyticsFailureHandler(ref.read(analyticsServiceProvider)),
  );

  return bus;
}

eventBus is a provider that creates the DomainEventBus and registers all handlers at the moment it is first read. Because Riverpod providers are lazy by default and cached after first creation, this runs once and the bus lives for the entire app session.

Every handler gets its dependencies injected via ref.read. Nothing is hardcoded. Everything is swappable in tests.

The LoginUseCase receives this event bus as a dependency through its own provider:

@riverpod
LoginUseCase loginUseCase(LoginUseCaseRef ref) {
  return LoginUseCase(
    repository: ref.read(authRepositoryProvider),
    eventBus: ref.read(eventBusProvider),
  );
}

This is the only place that connects the use case to the event bus. The notifier receives only the use case. The widget receives only the notifier's state. Each layer knows only about the layer directly below it and nothing else.

Adding a new side effect to login means creating a new handler class and adding one bus.register line in the composition root. The notifier, the use case logic, the widget, and every existing handler remain completely untouched.

Testing the Observer Architecture

One of the most significant advantages of this architecture is how clearly it separates test concerns. Each layer has its own focused test scope.

Testing the Use Case

void main() {
  group('LoginUseCase', () {
    late LoginUseCase useCase;
    late MockAuthRepository mockRepository;
    late MockDomainEventBus mockEventBus;

    setUp(() {
      mockRepository = MockAuthRepository();
      mockEventBus = MockDomainEventBus();
      useCase = LoginUseCase(
        repository: mockRepository,
        eventBus: mockEventBus,
      );
    });

    test('publishes UserLoggedIn event on success', () async {
      final user = UserDto(id: '1', token: 'token123');
      when(() => mockRepository.login(any())).thenAnswer((_) async => user);

      await useCase.execute(LoginRequest(email: 'a@b.com', password: '123'));

      verify(() => mockEventBus.publish(any<UserLoggedIn>())).called(1);
    });

    test('publishes LoginFailed event on error', () async {
      when(() => mockRepository.login(any()))
          .thenThrow(AppException.unauthorized(message: 'Invalid credentials'));

      await useCase.execute(LoginRequest(email: 'a@b.com', password: 'wrong'));

      verify(() => mockEventBus.publish(any<LoginFailed>())).called(1);
    });
  });
}

The use case test mocks the repository and the event bus. It verifies that the correct event type was published for each outcome. It doesn't test what any handler does. That's not the use case's responsibility, so it's not the use case's test.

Testing Each Handler

void main() {
  group('TokenHandler', () {
    late TokenHandler handler;
    late MockSecureStorageService mockStorage;

    setUp(() {
      mockStorage = MockSecureStorageService();
      handler = TokenHandler(mockStorage);
    });

    test('writes token to secure storage on UserLoggedIn', () {
      final event = UserLoggedIn(
        user: UserDto(id: '1', token: 'abc123'),
        occurredAt: DateTime.now(),
        eventId: 'event-1',
      );

      handler.handle(event);

      verify(
        () => mockStorage.write(key: 'auth_token', value: 'abc123'),
      ).called(1);
    });
  });
}

Each handler test is tiny. It creates the handler with a mocked dependency, fires the event, and verifies the exact side effect that handler is responsible for. No other handler is involved, no notifier is involved, and no widget is involved.

Testing the Notifier

void main() {
  group('LoginNotifier', () {
    test('transitions from loading to data on success', () async {
      final mockUseCase = MockLoginUseCase();
      final user = UserDto(id: '1', token: 'token123');

      when(() => mockUseCase.execute(any()))
          .thenAnswer((_) async => Result.success(user));

      final container = ProviderContainer(overrides: [
        loginUseCaseProvider.overrideWithValue(mockUseCase),
      ]);

      final notifier = container.read(loginNotifierProvider.notifier);

      await notifier.login(LoginRequest(email: 'a@b.com', password: '123'));

      expect(
        container.read(loginNotifierProvider),
        isA<AsyncData<UserDto?>>(),
      );
    });

    test('transitions from loading to error on failure', () async {
      final mockUseCase = MockLoginUseCase();
      final error = AppException.unauthorized(message: 'Invalid credentials');

      when(() => mockUseCase.execute(any()))
          .thenAnswer((_) async => Result.failure(error));

      final container = ProviderContainer(overrides: [
        loginUseCaseProvider.overrideWithValue(mockUseCase),
      ]);

      final notifier = container.read(loginNotifierProvider.notifier);

      await notifier.login(LoginRequest(email: 'a@b.com', password: 'wrong'));

      expect(
        container.read(loginNotifierProvider),
        isA<AsyncError>(),
      );
    });
  });
}

The notifier test only verifies state transitions. It doesn't need to mock the event bus because the notifier no longer touches the event bus. That's the use case's job, and the use case has its own test that verifies events are published correctly. Each layer is tested in complete isolation with no overlap.

When to Use the Observer Pattern

Use Observer when:

• One event needs to trigger multiple independent reactions

• You want to add or remove reactions without modifying the event source

• Side effects need to be decoupled from business logic

• Each reaction should be independently testable

• Multiple parts of the system need to react to the same state change

• You are building a feature that will grow in number of side effects over time

When Not to Use It

Avoid Observer when:

• You have only one consumer and no realistic expectation of more

• The relationship between producer and consumer is simple and direct

• The pattern adds structural overhead without meaningful benefit

• Streams, ChangeNotifier, or Riverpod's built-in reactivity already solve the problem naturally

• Strict ordering of side effects is critical and fan-out makes that hard to guarantee

Conclusion

The Observer Design Pattern is one of the most important tools in a software engineer's arsenal. This isn't because it's clever, but because it solves a problem every growing application faces: how do you let one event trigger many reactions without turning your codebase into a tightly coupled mess?

You started by understanding the pattern at its core. A Subject holds a list of Observers and notifies them when events occur. You saw it built step by step in Dart, with snapshot iteration to prevent concurrent modification errors, per-observer try/catch to prevent failure cascades, and dependency inversion to keep everything testable.

You discovered that the Observer pattern is already embedded in Flutter's Streams, ChangeNotifier, and BLoC. Understanding its foundations means you understand why those tools work the way they do.

You then took the pattern into Event-Driven Architecture, where events become immutable domain facts and the system is composed of producers and consumers with no direct coupling between them.

You applied it inside Domain-Driven Design, giving events a proper home in a pure Dart domain layer that is framework-independent, fully portable, and fully testable.

And you saw how it integrates with Riverpod through a hybrid architecture with a clear and enforced rule: handlers own side effects, the notifier owns UI state, and widgets own nothing.

The result is a codebase that scales gracefully. When a new side effect needs to be added, you create one handler and register it in one place. Nothing else changes. That's the promise of the Observer pattern. And as you've seen throughout this handbook, it's a promise it keeps.

Happy Coding!

I was at a software craftsmanship meetup recently, where we formed pairs to solve a simplified Berlin Clock Kata. A Berlin Clock displays the time using rows of flashing lights, which you can see below (although in the kata we just output a text representation, and the lights in a row are all the same colour).

Initial Test Driven solution

Most pairs used inside out TDD, and there were a lot of solutions that looked something like this (complete code available on GitHub).

def berlin_clock_time(julian_time):
    hours, minutes, seconds = list(map(int, julian_time.split(":")))

    return [
        seconds_row_lights(seconds % 2)
        , five_hours_row_lights(hours)
        , single_hours_row_lights(hours % 5)
        , five_minutes_row_lights(minutes)
        , single_minutes_row_lights(minutes % 5)
    ]

def five_hours_row_lights(hours):
    lights_on = hours // 5
    lights_in_row = 4
    return lights_for_row("R", lights_on, lights_in_row)

# ...

This type of solution drops out naturally from applying inside out TDD to the problem. You write some tests for the seconds row, then some tests for the five hours row, and so on, and then you put it all together and do some refactoring. This solution does expose some of the domain concepts at a glance:

• There are 5 rows
• There is one second row, 2 hour rows and 2 minute rows

Some more concepts are available after a bit of digging, but aren't immediately obvious. The rows are made up of lights that can be on (or presumably off), and that the number of lights on is an indication of the time.

However there are some big parts of the problem that are not exposed. And since I haven't yet explained it, you probably don't know exactly how the Berlin Clock works yet.

Elevate the concepts

To improve this we can bring some of the details that are buried in the helper functions (such as get_five_hours) closer to the top of the file. This brings you to something like the following (complete code available on GitHub), although the downside is that it breaks nearly all of the tests. Solutions like this are rarer on GitHub, but do exist.

def berlin_clock_time(julian_time):
    hours, minutes, seconds = list(map(int, julian_time.split(":")))

    single_seconds = seconds_row_lights(seconds % 2)
    five_hours = row_lights(
        light_colour="R",
        lights_on=hours // 5,
        lights_in_row=4)
    single_hours = row_lights(
        light_colour="R",
        lights_on=hours % 5,
        lights_in_row=4)
    five_minutes = row_lights(
        light_colour="Y",
        lights_on=minutes // 5,
        lights_in_row=11)
    single_minutes = row_lights(
        light_colour="Y",
        lights_on=minutes % 5,
        lights_in_row=4)

    return [
        single_seconds,
        five_hours,
        single_hours,
        five_minutes,
        single_minutes
    ]

# ...

This improves the concepts that are now exposed at a glance:

• There are 5 rows
• The seconds row is a special case
• There are 2 hour rows and 2 minute rows
• The rows use different colour lights
• The rows have a different number of lights

This is pretty good, and is already better that most of the solutions out there. However, it's still a bit mysterious how the rows are related to each other (there are 2 rows to display the hours and the minutes, so presumably these are linked). It's also not obvious what amount of time each light represents.

Name implicit concepts

At the moment some of the concepts (such as the amount of time each light represents) are implicit in the code. Making these explicit, and naming them, forces us to understand them and to embed that understanding in the code.

In order to make the amount of time each light represents explicit, it seems like it would be sensible to pass a time_per_light value to row_lights. This means we have to push the calculation of lights_on down into row_lights.

This in turn makes it obvious that there are two kinds of rows: one related to the quotient (\\) of the time value, and one related to the remainder / modulus (%). If we look at the quotient case, we see that the 2nd parameter to the operation is the time_per_light, which is 5 in both cases (5 hours in one case and 5 minutes in the other).

This allows us to write these rows like this:

five_hour_row = row_lights(
    time_per_light=5,
    value=hours, 
    light_colour="R",
    lights_in_row=4)

If we now turn our attention to the remainder case, we realise that time_per_light is always singular (one hour or one minute), as it is filling in the gaps in the quotient case.

For example, the five hours row can represent 0, 5, 10, 15, or 20 hours, but nothing in between. In order to represent any hour, there must be another row to represent +1, +2, +3 and +4. This means that this row must have exactly 4 lights, and that each light must represent 1 hour.

This implies that the remainder case is dependent on the quotient one, which most people would describe as a parent / child relationship.

With this knowledge in hand, we can now create a function for the child remainder rows, and the solution now looks like this (complete code on GitHub):

def berlin_clock_time(julian_time):
    hours, minutes, seconds = list(map(int, julian_time.split(":")))

    return [
        seconds_row_lights(
            seconds % 2),
        parent_row_lights(
            time_per_light=5,
            value=hours, 
            light_colour="R",
            lights_in_row=4),
        child_remainder_row_lights(
            parent_time_per_light=5,
            value=hours,
            light_colour="R"),
        parent_row_lights(
            time_per_light=5,
            value=minutes, 
            light_colour="Y",
            lights_in_row=11),
        child_remainder_row_lights(
            parent_time_per_light=5,
            light_colour="Y",
            value=minutes)
    ]

# ...

A quick glance at this code now reveals nearly all the domain concepts

• The first row represents the seconds and is a special case
• On the second row each "R" light represents 5 hours
• The third row shows the remainder from the second
• On the fourth row each "Y" light represents 5 hours
• The fifth row shows the remainder from the fourth

This took something thinking about, which will have cost us some time / money. But we increased our understanding of the problem while we did it, and most importantly we embedded that knowledge in to the code. This means that the next person to read the code will not have to do this, which will save some time / money. Since we spend about 10 times longer reading code than we do writing it, this is probably a worthwhile endeavour.

Embedding this understanding has also made it harder for future programmers to make mistakes. For example, the concept of parent / child rows didn't exist in earlier examples, and it would be easy to mismatch them. Now the concept is plain to see, and the values are mostly worked out for you. It is also easier to refactor to support new clock variants, for example where lights in the first hours row represent 6 hours.

How far should you take it?

There are things we can do to take this further. For example the parent_time_per_light of a child row must match the time_per_light of its parent, and there is nothing enforcing this. There is also a relationship between time_per_light and lights_in_row for the parent rows, and again it is not enforced.

However, at the moment we are only required to support one clock variant, so these probably aren't worth doing. When a change is required for the code, we should refactor so that the change is easy (which might be hard) and then make the easy change.

Conclusions

Embedding domain concepts in code requires thought and skill, and TDD won't necessarily do it for you. It takes longer than a naive solution, but makes the code easier to understand, and will very likely save time in the medium term. Time is money, and finding the right balance of spending time now versus saving time later is also an important skill for a professional programmer to have.

Event Sourcing is a thought challenge when starting out. In this story, I will describe my experiences from the perspective of an engineer.

My goal is to help you decide if you want to invest the resources to get started with Event Sourcing.

_[The Matrix](https://www.amazon.com/Complete-Trilogy-Reloaded-Revolutions-Blu-ray/dp/B001CEE1YE/ref=sr_1_6?keywords=the+matrix&qid=1550756146&s=movies-tv&sr=1-6" rel="noopener" target="blank" title="): Neo is offered a choice.

About The Author

Hi ? I’m Noël. I live near Zurich (Switzerland) and am proudly working on Switzerland’s largest E-Commerce platform. My team and I have applied Event Sourcing throughout the last 12 months, and we learned a lot.

I want to share four essentials with you that I wish we knew one year ago.

A Tiny Introduction To Event Sourcing

This article is not about introducing you to the concepts of Event Sourcing.
I still feel like I should take one step back though — to paint a clearer picture.

In state-oriented applications, you store the result of some computation in your data store. You might also keep a log where you archive old states for auditing or debugging purposes. But by storing state you lose the information about the transition from one state to the other. If a user’s username has disappeared, you’ll be wondering how that could have happened.

Storing state in a state-oriented application.

Sourcing events preserves that information. This is achieved by storing state transitions rather than the resulting state.

Storing state transitions (events) in an event sourced application.

The current state can be restored by applying all events to an empty canvas. That means we can still access the current state but need to invest computational resources to do so.

There are many articles on the web that go into more detail. Martin Fowler wrote one about it. And Greg Young talks a lot about Event Sourcing. Greg is so obsessed with event sourcing that he implemented a data store which is specifically designed for event sourcing. My team is using Greg’s event store — it’s great!

1) Event Sourcing Is Not A Silver Bullet

Once you fall for the bitter sweet taste of Event Sourcing it becomes compelling to apply the concept to all your problems.

This will provide you with loads of data to analyze and you will have a powerful foundation to detect interesting correlations in it. You’ll be able to detect inefficient processes and make them more efficient.

And every engineer’s (my) favorite:

Tracking down a bug becomes much easier when you can “time travel” to the exact moment when the bug happened. In the end you will save time and money.

Well — not quite. ☝️

Sourcing your events sure allows you to do the analysis. But you still need to do it. This will cost time. Luckily, “time travel” comes for free. Enhanced debugging is thus guaranteed from day one.

Seth Godin wrote a great blog post on the subject. It’s a 2 minute read, so check it out.

Now you know about the price you’ll pay if you use your events for analytical purposes which is the main business benefit of Event Sourcing after all.

There is another cost though. Event Sourcing will increase the complexity of your application. Instead of dealing with your application’s current state you’ll have to deal with everything that has ever happened since it went live. Events that are no longer used will remain in your data store and you’ll have to support them for a long time.

It’s great if you deploy a feature and keep iterating on it. Just be aware that there are now multiple versions of that feature’s events in your data store and you’ll have to support all of them. Even if you no longer create new instances of those events.

Event Sourcing imposes additional time complexities that you will have to get used to. Apply it where you see a non-zero chance that the collected data becomes relevant. Where I’d define “relevant” as:

• the data could give you more insight into your domain
• the data could help your business to improve their processes on their own
• the data could help you find bugs faster

Note that I added the word “could” in each of the last three bullet points. It’s likely you won’t know the exact benefit of Event Sourcing in advance. Make your best guess.

2) Recognize The Functional Nature Of Event Sourcing

The authors of the famous Patterns, Principles, and Practices of Domain-Driven Design recommend object-oriented programming languages like C# or Java.

I assume that the implicit reasoning behind that recommendation is the number of people using such languages. It’s true. New team members will likely have an easier start into the domain when confronted with familiar languages.

But I disagree. So does Greg Young. Event Sourcing is not an object-oriented concept.

One might argue that state transitions are objects too. And indeed. You can model everything as objects. Just because you can does not imply that this is the best model to use.

Consider using a language that supports functional paradigms. Especially tagged unions and pattern matching are extremely valuable. Working with your events will feel natural and you won’t have to fight your language’s type system. If your team has no experience with the functional world it might be best to stick to familiar languages though.

Even more important to understand is that choosing a relational data store will be a painful experience. You’re not dealing with relational data when sourcing your events. Each event has its own schema which can change over time. Using a relational data store will hurt.

SQL is the master of nothing but it sucks at nothing. - Greg Young

3) Expect A Steep Learning Curve

As with all new things there will be learning involved. Don’t try to sidestep it. That won’t work.

_[The Matrix](https://www.amazon.com/Complete-Trilogy-Reloaded-Revolutions-Blu-ray/dp/B001CEE1YE/ref=sr_1_6?keywords=the+matrix&qid=1550756146&s=movies-tv&sr=1-6" rel="noopener" target="blank" title="): Neo learns something special.

A great way to learn is to prototype. Try this:

• build at least one prototype of your first event sourced application
• run and observe your prototype for a while
• implement new features and get used to iterating on what you’ve built

Iterate as often as possible before your go live. Once you are live it won’t be as easy to implement new learnings.

Go live once your team feels confident with maintaining the application.

Also think about how your team will introduce new team members to Event Sourcing. New joiners are already in an overwhelming position and learning new concepts won’t make it any easier for them.

Figure out a way to introduce them to Event Sourcing in a soft and safe way. This is important to figure out once you start getting new team members. It’s fine to delay it until that happens.

4) Prepare for political debates

Have you realized that your company wants cheap and quality results today?

Oh my, who am I talking to — of course you did. ?

Will they like it when you experiment with a mind-bending concept they might never heard of? And what is your company’s tech stack like? Do you usually use object-oriented programming languages in combination with relational data stores? Will they like it when you switch to a functional tech stack?

Depending on your companies culture you might have to fight your colleagues on multiple fronts. Act as an example. Tell the truth. You know it will be hard, especially in the beginning. Share your concerns. Make sure everyone involved knows the risks and what you’ll do to prevent them.

And don’t leave out how you picture the Event Sourcing paradise. Get the business on board by allowing them to build reports based on your valuable events. They’ll love it.

Get the concerned engineering people on board by sharing the improved debugging experience. Engineers are stubborn, they might still not like it.

I found it useful to practice such debates with my colleagues. Establish a safe environment for training and encourage your team members to take part.

_[The Matrix](https://www.amazon.com/Complete-Trilogy-Reloaded-Revolutions-Blu-ray/dp/B001CEE1YE/ref=sr_1_6?keywords=the+matrix&qid=1550756146&s=movies-tv&sr=1-6" rel="noopener" target="blank" title="): Neo trains in a safe environment.

Be ready and know your stuff. You’ll make it! ?

Conclusion

Let me summarize.

• More data isn’t always good.
• Additional data without the time to analyze it is useless.
• Analysis without the intention and time to act on the result is useless.
• Event Sourcing enhances the ability to debug your application.
• Event Sourcing is a functional paradigm.
• Expect a steep learning curve.
• Not everybody will be happy about your plans.

That’s it. My intention was to prepare your expectations to my experiences. Don’t worry. Be determined and choose the red pill!

The Matrix

All images in this story are borrowed from the movie The Matrix.

I’ve spent 9 years writing object-oriented code and working with relational data stores. About two years ago I started to experiment with functional code and non-relational data stores. The mind shift has been one of the most important lessons in my career to date.

Question your environment. Find the flaws. Exit the Matrix and get to experience a whole new world.

Farewell. Until next time. And good luck!

_[The Matrix](https://www.amazon.com/Complete-Trilogy-Reloaded-Revolutions-Blu-ray/dp/B001CEE1YE/ref=sr_1_6?keywords=the+matrix&qid=1550756146&s=movies-tv&sr=1-6" rel="noopener" target="blank" title="): Neo receives a goodbye gift.

I only write about programming and technology. If you follow me, I won’t waste your time. ?