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!

When you're working with an application, sometimes it no longer makes sense to try to continue and improve what already exists. Instead, you need to rethink, restructure, and rebuild.

Making the decision to give up all the work you and others have put into the existing system is a difficult choice for many developers. Still, dogged devotion to existing code in the face of disruption is a disservice to developers and users alike.

The effects of any large-scale alterations to a system reach far beyond the development world. Wholesale system replacements are rarely invisible, which also makes life difficult for salespeople and marketers. They're the ones who have to explain to customers why such a drastic change happened.

But this does not make the changes any less necessary.

As with so many other things in life, just because a choice is difficult and painful does not mean it is wrong. Evolution can be a violent process. But failure to adapt leads to extinction.

When fish crawled out of the sea millions of years ago, they didn’t continue to improve on fins and gills. Entirely new systems were necessary for motion and breathing. It doesn’t mean that fins and gills weren’t valuable or that their design was flawed. Indeed, their designs fit perfectly with their intended purposes. But the purpose became irrelevant, and so they were no longer suitable in their current environment.

When the time comes (and it will), you must step back and take an objective look at the situation. Will another tweak to that fin work? Or will it just highlight how poorly adapted it is to current needs?

Intelligent Design Choice or Inevitable Reaction?

Much of the discussion on sacrificial architecture revolves around whether it should be a proactive development process as opposed to a last-ditch reactionary decision.

Should developers intentionally build systems with limited lifetimes? Or should they build for the long run and make large-scale changes only if absolutely necessary?

According to Martin Fowler, who introduced sacrificial architecture seven years ago, building it into the design process can be a good idea:

“So what does it mean to deliberately choose a sacrificial architecture? Essentially it means accepting now that, in a few years’ time, you'll (hopefully) need to throw away what you're currently building.

This can mean accepting limits to the cross-functional needs of what you're putting together. It can mean thinking now about things that can make it easier to replace when the time comes - software designers rarely think about how to design their creation to support its graceful replacement. It also means recognizing that software that's thrown away in a relatively short time can still deliver plenty of value.”

Intentional sacrifice can also be useful when considering new features or applications as a way to limit overall development effort.

Using sacrificial architecture for proof-of-concept systems can move the development process more quickly towards a launchable implementation. As noted in the Open Group Agile Architecture Framework:

“When the goal is to get rapid market feedback experimenting with an MVP, sacrificial architecture is an option to consider as it would not be worth spending too much time designing an architecture that would have to change should the product owner decide to pivot.”

This is not to say that proactively using sacrificial architecture will eliminate the need for reactive sacrifices. There are always going to be changes and disruptions that you and your team will not anticipate. And disruptions often lead to sacrifices and evolutions.

Just consider how the COVID pandemic crisis disrupted so many aspects of everyday life, from how employees work to how schools teach our children.

There are many less drastic examples as well. One side effect of the COVID crisis was the rapid acceleration of e-commerce business and online transactions.

But the industry had to adapt to rising consumer concerns about data privacy. All online businesses rely on software with crucial features such as online invoicing and payments. But application providers and payment processors had to rapidly adapt existing systems to ensure compliance with new standards like the Payment Card Data Security Standard (PCI-DSS) and the European Union General Data Protection Regulation (GDPR).

Image Source

In the same way, code can become obsolete or fail to accomplish its intended purposes. There are times when disruptions in coding practices or programming language capabilities mean that you need to make large-scale changes.

Just consider eBay, which has changed its underlying programming language twice since its founding in 1995. Why? Because the capabilities of the abandoned languages failed to meet eBay’s needs and requirements as the business grew.

How to Anticipate the Sacrifice

Developers cannot possibly build to avoid the need for replacements altogether, and they shouldn’t focus on doing so. There are, however, steps you can take to plan for obsolescence.

Build with replacement in mind

As Fowler stated, you can build code with the idea that it will require replacement in a few years. Outdated code will eventually become susceptible to malicious viruses that could result in browser hijacking or system slowdowns.

This means that you need to consider in advance the code’s limitations, including performance and scalability, and other characteristics.

Minimize sacrifice through modularity

As a general rule, it is easier to replace smaller pieces of code than it is to replace an entire structure.

Just as you don’t need to spend the time and money to replace your entire roof if a shingle gets blown off, there is no need to completely rewrite the code for a system if revising one module will do.

So building modular code results in an architecture that is easier for developers to modify as needed.

But modularity is not always an effective solution, and you should be aware of the limits of your code. Sometimes, replacing too many pieces can weaken a structure or make it unstable.

In the same way, the more modules you replace in your existing code, the more opportunities there are for problems with the operation of the code as a whole. That is the dividing line between continued piece-by-piece updating and wholesale replacement.

Maintain quality standards

Even when you intentionally decide to build code knowing you will sacrifice it in the near future, you should always continjue to strive to meet or exceed company quality standards. After all, the sacrificial architecture will still probably be in production.

Needs may also change, eliminating the reasons that you planned to retire the code in the first place. Poorly designed or implemented code also makes developers’ lives more difficult when modifying the code.

Poor documentation and code structure also hinder your ability to understand the connections between pieces of code, making replacements and updates more challenging.

Poorly designed code can also be a significant security risk, perhaps allowing hackers to access private data that companies have invested so much to protect.

Image Source

Quality is a mantra that must always be front-of-mind, even for disposable code.

Sacrificing for the Greater Good

While it may sound trite to quote this common saying, sacrificing your code may indeed be for the greater good of your systems and your company in the long run.

Judicious, proactive use of sacrificial architectures can help reduce time to market for new features. And, it can minimize how much effort it takes when an unplanned, large-scale replacement inevitably occurs.

Clean Architecture is a term coined by Robert C. Martin. The main idea is that entities and use cases are independent of frameworks, UI, the database, and external services.

A Clean Architecture style has a positive effect on maintainability because:

• We can test domain entities and use cases without a framework, UI, or infrastructure.
• Technology decisions can change without affecting domain code, and vice versa. It is even possible to switch to a new framework with limited effort.

My goal is to flatten the learning curve, and reduce the effort it might take you to implement a Clean Architecture. That’s why I created the Modern Clean Architecture libraries.

In this article, I will show you how to create an application with a modern clean architecture, from a HTML/JavaScript front end to a Spring Boot back end. The focus will be on the back end.

Let’s start with an overview of the sample application – a timeless classic, the TODO app.

Sample TODO List Application

A to do list is a collection of tasks. A task has a name, and is either completed or not. As a user, you can:

• Create a single to do list, and persist it
• Add a task
• Complete a task, or “uncomplete” it
• Delete a task
• List all tasks
• Filter completed/uncompleted tasks

Here’s what a todo list with 1 uncompleted and 2 completed tasks looks like:

We'll start at the core of the application, the domain entities. Then we'll work our way outwards to the front end.

The Domain Entities

The central domain entities are TodoList and Task.

The TodoList entity contains:

• a unique id,
• a list of tasks,
• domain methods for adding, completing, and deleting tasks

The TodoList entity doesn’t contain public setters. Setters would break proper encapsulation.

Here’s part of the TodoList entity. Lombok annotations shorten the code.

public class TodoList implements AggregateRoot<TodoList, TodoListId> {
    private final TodoListId id;
    private final List<Task> tasks;

    @Value(staticConstructor = "of")
    public static class TodoListId implements Identifier {
        @NonNull
        UUID uuid;
    }

    @Override
    public TodoListId getId() {
        return id;
    }
    ...
    public TaskId addTask(String taskName) {
        if (taskName == null || isWhitespaceName(taskName)) {
            throw new IllegalTaskName("Please specify a non-null, non-whitespace task name!");
        }
        TaskId taskId = add(TaskId.of(UUID.randomUUID()), taskName, false);
        return taskId;
    }
      ...
    public void deleteTask(TaskId task) {
        Optional<Task> foundTask = findTask(task);
        foundTask.ifPresent(tasks::remove);
    }
     ...
}

What is the AggregateRoot interface good for? Aggregate root is a term from Domain Driven Design (DDD) by Eric Evans:

An aggregate is a cluster of associated objects that we treat as a unit for the purpose of data changes. Each aggregate has a root and a boundary. The boundary defines what is inside the aggregate. The root is a single, specific entity contained in the aggregate.

We can change the aggregate’s state only through the aggregate root. In our example that means: we always have to use the TodoList to add, remove, or change a task.

That allows the TodoList to enforce constraints. For example, we can’t add a task with a blank name to the list.

The AggregateRoot interface is part of the jMolecules library. This library makes DDD concepts explicit in the domain code. During build, a ByteBuddy plugin maps the annotations to Spring Data annotations.

So we only have a single model, both for representing domain concepts, and persistence. Still, we don’t have any persistence-specific annotations in the domain code. We don’t tie ourselves to any framework.

The Task class is similar, but it implements the jMolecules Entity interface instead:

public class Task implements Entity<TodoList, TaskId> {
    private final TaskId id;
    private final String name;
    private final boolean completed;

    @Value(staticConstructor = "of")
    public static class TaskId implements Identifier {
        @NonNull
        UUID uuid;
    }

    Task(@NonNull TaskId id, @NonNull String name, boolean completed) {
        this.id = id;
        this.name = name;
        this.completed = completed;
    }
}

The constructor of Task is package private. So we can’t create an instance of Task from outside of the domain package. And the Task class is immutable. No changes to its state are possible from outside of the aggregate’s boundary.

We need a repository for storing the TodoList. To stick to domain terms in the domain code, it is called TodoLists:

public interface TodoLists extends Repository<TodoList, TodoListId> {
    TodoList save(TodoList entity);
    Optional<TodoList> findById(TodoListId id);
    Iterable<TodoList> findAll();
}

Again, the code uses a jMolecues annotation: Repository. During build, the ByteBuddy plugin translates it to a Spring Data repository.

We’ll skip the domain exceptions, since there’s nothing special about them. That’s the complete domain package.

The App's Behavior (and Use Cases)

Next, we define the behavior of the application that is visible to the end user. Any interaction of the user with the application happens as follows:

1. The user interface sends a request.
2. The backend reacts by executing a request handler. The request handler does everything necessary to fulfill the request:
3. Access the database
4. Call external services
5. Call domain entity methods
6. The request handler may return a response.

We implement a request handler with a Java 8 functional interface.

A handler that returns a response implements the java.util.Function interface. Here’s the code of the AddTask handler. This handler

• extracts the to do list id and task name from an AddTaskRequest,
• finds the to do list in the repository (or throws an exception),
• adds a task with the name from the request to the list,
• returns an AddTaskResponse with the added task’s id.

@AllArgsConstructor
class AddTask implements Function<AddTaskRequest, AddTaskResponse> {
    @NonNull
    private final TodoLists repository;

    @Override
    public AddTaskResponse apply(@NonNull AddTaskRequest request) {
        final UUID todoListUuid = request.getTodoListUuid();
        final String taskName = request.getTaskName();

        final TodoList todoList = repository.findById(TodoListId.of(todoListUuid))
            .orElseThrow(() -> new TodoListNotFound("Repository doesn't contain a TodoList of id " + todoListUuid));

        TaskId taskId = todoList.addTask(taskName);
        repository.save(todoList);

        return new AddTaskResponse(taskId.getUuid());
    }
}

Lombok creates a constructor with the TodoLists repository interface as constructor argument. We pass in any external dependency as interface to the handler’s constructor.

The requests and responses are immutable objects:

@Value
public class AddTaskRequest {
    @NonNull
    UUID todoListUuid;

    @NonNull
    String taskName;
}

The Modern Clean Architecture libraries (de)serialize them from/to JSON.

Next, an example of a handler that doesn’t return a response. The DeleteTask handler receives a DeleteTaskRequest. Since the handler doesn’t return a response, it implements the Consumer interface.

@AllArgsConstructor
class DeleteTask implements Consumer<DeleteTaskRequest> {
    @NonNull
    private final TodoLists repository;

    @Override
    public void accept(@NonNull DeleteTaskRequest request) {
        final UUID todoListUuid = request.getTodoListUuid();
        final UUID taskUuid = request.getTaskUuid();

        final TodoList todoList = repository.findById(TodoListId.of(todoListUuid))
            .orElseThrow(() -> new TodoListNotFound("Repository doesn't contain a TodoList of id " + todoListUuid));

        todoList.deleteTask(TaskId.of(taskUuid));
        repository.save(todoList);
    }
}

One question remains: who creates these handlers?

The answer: a class implementing the BehaviorModel interface. The behavior model maps each request class to the request handler for this kind of request.

Here’s a part of the TodoListBehaviorModel:

@AllArgsConstructor
public class TodoListBehaviorModel implements BehaviorModel {
    @NonNull
    private final TodoLists todoLists;
    ...
    @Override
    public Model model() {
        return Model.builder()
            .user(FindOrCreateListRequest.class).systemPublish(findOrCreateList())
            .user(AddTaskRequest.class).systemPublish(addTask())
            .user(ToggleTaskCompletionRequest.class).system(toggleTaskCompletion())
            ...
            .build();
    }

    private Function<FindOrCreateListRequest, FindOrCreateListResponse> findOrCreateList() {
        return new FindOrCreateList(todoLists);
    }

    private Function<AddTaskRequest, AddTaskResponse> addTask() {
        return new AddTask(todoLists);
    }

    private Consumer<ToggleTaskCompletionRequest> toggleTaskCompletion() {
        return new ToggleTaskCompletion(todoLists);
    }
    ...
}

The user(...) statements define the request classes. We use systemPublish(...) for handlers that return a response, and system(...) for handlers that don’t.

The behavior model has a constructor with external dependencies passed in as interfaces. And it creates all handlers and injects the appropriate dependencies into them.

By configuring the dependencies of the behavior model, we configure all handlers. That’s exactly what we want: a central place where we can change or switch the dependencies to technology. That’s how technology decisions can change without affecting the domain code.

The Apps' Web Layer (the Adapters)

The web layer in a modern clean architecture can be very thin. In its simplest form, it consists of only 2 classes:

• One class for configuration of dependencies
• One class for exception handling

Here’s the TodoListConfiguration class:

@Configuration
class TodoListConfiguration {
    @Bean
    TodoListBehaviorModel behaviorModel(TodoLists repository) {
        return new TodoListBehaviorModel(repository);
    }
}

Spring injects the implementation of the TodoLists repository interface into the behaviorModel(…) method. That method creates a behavior model implementation as a bean.

If the application uses external services, the configuration class is the place to create the concrete instances as beans. And inject them into the behavior model.

So, where are all the controllers?

Well, there aren’t any that you have to create. At least if you only handle POST requests. (For the handling of GET requests, see the Q&A later.)

The spring-behavior-web library is part of the Modern Clean Architecture libraries. We define a single endpoint for requests. We specify the URL of that endpoint in the application.properties:

behavior.endpoint = /todolist

If that property exists, spring-behavior-web sets up a controller for the endpoint in the background. That controller receives POST requests.

We don’t need to write Spring specific code to add new behavior. And we don’t need to add or change a controller.

Here’s what happens when the endpoint receives a POST request:

1. spring-behavior-web deserializes the request,
2. spring-behavior-web passes the request to a behavior configured by the behavior model,
3. the behavior passes the request to the appropriate request handler (if there is one),
4. spring-behavior-web serializes the response and passes it back to the endpoint (if there is one).

By default, spring-behavior-web wraps every call to a request handler in a transaction.

How to send POST requests

Once we start the Spring Boot application, we can send POST requests to the endpoint.

We include a @type property in the JSON content so that spring-behavior-web can determine the right request class during deserialization.

For example, this is a valid curl command of the To Do List application. It sends a FindOrCreateListRequest to the endpoint.

curl -H "Content-Type: application/json" -X POST -d '{"@type": "FindOrCreateListRequest"}' [http://localhost:8080/todolist](http://localhost:8080/todolist)

And that’s the corresponding syntax to use in Windows PowerShell:

iwr http://localhost:8080/todolist -Method 'POST' -Headers @{'Content-Type' = 'application/json'} -Body '{"@type": "FindOrCreateListRequest"}'

Exception handling

Exception handling with spring-behavior-web is no different than in “normal” Spring applications. We create a class annotated with @ControllerAdvice. And we place methods annotation with @ExceptionHandler in it.

See the TodoListExceptionHandling for example:

@ControllerAdvice
class TodoListExceptionHandling {
    @ExceptionHandler({ Exception.class })
    public ResponseEntity<ExceptionResponse> handle(Exception e) {
        return responseOf(e, BAD_REQUEST);
    }
    ...
}

Note that in a real application, the different exception types need different treatment.

The App's Front End

The front end of the To Do List application consists of:

• a HTML page,
• a CSS file for formatting,
• and a the main.js JavaScript file

We focus on main.js here. It sends requests and updates the web page.

Here’s part of its content:

// URL for posting all requests,
// Must be the same as the one in application.properties
// (See https://github.com/bertilmuth/modern-clean-architecture/blob/main/samples/todolist/src/main/resources/application.properties)
const BEHAVIOR_ENDPOINT = "/todolist";

//variables
var todoListUuid;
...

// functions
function restoreList(){
    const request = {"@type":"FindOrCreateListRequest"};

    post(request, function(response){
        todoListUuid = response.todoListUuid;
        restoreTasksOf(todoListUuid);
    });
}

function restoreTasksOf(todoListUuid) {
    const request = {"@type":"ListTasksRequest", "todoListUuid":todoListUuid};

    post(request, function(response){    
        showTasks(response.tasks);
    });
}
...
function post(jsonObject, responseHandler) {    
    const xhr = new XMLHttpRequest();
    xhr.open("POST", BEHAVIOR_ENDPOINT);

    xhr.setRequestHeader("Accept", "application/json");
    xhr.setRequestHeader("Content-Type", "application/json");

    xhr.onreadystatechange = function() {
        if (xhr.readyState === 4) {
            response = xhr.responseText.length > 0? JSON.parse(xhr.response) : "";
            if(response.error){
                alert('Status ' + response.status + ' "' + response.message + '"');
            } else{
                responseHandler(response);
            }
        }    
    };

    const jsonString = JSON.stringify(jsonObject);
    xhr.send(jsonString);
}

So for example, this is the JSON object for a ListTasksRequest:

const request = {“@type”:”ListTasksRequest”, “todoListUuid”:todoListUuid};

The post(…) method sends the request to the backend, and passes the response to the response handler (the callback function you passed in as second parameter).

That’s all about the To Do List application.

Questions & Answers

What if…

… I want to send GET requests instead of POST requests?

… I want the web layer to evolve separately from the behavior?

… I want to use a different framework than Spring?

… I have a much bigger application than the To Do List sample. How do I structure it?

Here are the answers.

Conclusion

In this article, I presented you a particular way to implement a Clean Architecture. There are many other ways.

My goal is to reduce the effort of building a Clean Architecture and flatten the learning curve.

To achieve this, the Modern Clean Architecture libraries provide the following features:

• Serialization of immutable requests and responses without serialization specific annotations.
• No necessity for DTOs. You can use the same immutable objects for requests/responses in web layer and use cases..
• Generic endpoint that receives and forwards POST requests. New behavior and domain logic can be added and used without the need to write framework specific code.

In my next article, I will describe how to test a Modern Clean Architecture.

I invite you to visit the Modern Clean Architecture GitHub page.

See the To Do List sample application.

And please share any feedback you have with me. What do you think about it?

If you want to keep up with what I’m doing or drop me a note, follow me on LinkedIn or Twitter.

Acknowledgements

Thank you to Surya Shakti for publishing the original front end only to do list code.

Thank you to Oliver Drotbohm for pointing me to the awesome jMolecules library.

Recently I attended a meeting with multiple stakeholders from the business side. When asked to explain a feature, I started explaining them the details of the feature and its implementation. After the meeting one of my colleagues told me even though I explained it in detail, they will be requesting a follow-up meeting to discuss the same thing and it was true — the next day we had a meeting invite for the same thing as a follow-up. He explained to me that the reason was I had provided them more details than necessary which probably confused them. This incident led me to the principle of Occam’s Razor.

Quoted from Wikipedia

Occam’s razor or the law of parsimony is the problem-solving principle that essentially states that “simpler solutions are more likely to be correct than complex ones.” When presented with competing hypotheses to solve a problem, one should select the solution with the fewest assumptions. The idea is attributed to English Franciscan friar William of Ockham (c. 1287–1347), a scholastic philosopher and theologian.

We have all heard the famous quote by Sherlock Holmes

Once you eliminate the impossible, whatever remains, no matter however improbable, must be the truth.

This follows directly from Occam’s Razor. This principle states that given two explanations of a situation, the one in which there is the least number of variables(simpler) however improbable is the most likely explanation. This principle is very helpful and it can be used in a wide variety of situations but it is especially powerful in the hands of software professional.

There are many areas of Software development which can benefit from this principle. A few of them are:

Coding

The first and foremost area is coding. As developers, we make hundreds of decisions every day which directly affects the health of the codebase and in turn the business. Few of the mistakes we make include adding unwanted abstractions, designing for the future, making it “extensible”(whatever that means). These code with unwanted additional complexity slowly rots over time and becomes “that” part of the codebase that no one understands and nobody is willing to touch. These are the things we do either knowingly or unknowingly which can put a dent on our codebase health in the long-run.

To overcome this it would be prudent for us to think in terms of Occam’s Razor. Always do the simplest thing possible at any point in time. Principles like YAGNI and KISS are examples of Occam’s Razor in coding. If you want to combine 3 design patterns to accommodate a feature request you expect in the future, restrain your primal instincts and stick with a single class for now. Using Occam’s razor during the development process would keep the codebase simple and readable and your future peers will really thank you.

A word of caution here is, this principle should not be used as an excuse to write bad code or take shortcuts. If there is a real need to add complexity, by all means, you should do that. Consider this a framework for you to step back and think for a moment and weigh the cost of your decision in the long run.

Debugging

Another interesting application of this principle is while debugging. The hard part about debugging is nobody knows the answer especially when you work in a legacy code base with business critical functionalities. Bigger the codebase, more complex the debugging process and thus the Occam’s Razor comes in really handy. All the good software developers I know trace the root cause of a bug by using this principle without even realising it.

Let's say there you write a program to display a few stats in the dashboard. You observe that each time the dashboard is updated you get 2x instead of x for a particular stat. What would be your first instinct? Is it a double counting issue or some thread level race condition? I am guessing most of you with go with the former. This is Occam’s Razor in action. You picked the choice which provides the simplest explanation for the issue intuitively.

This is not to say that always the simplest explanation is the right one. Instead, you start from the simplest one and eliminate one by one either by theory or experimentation until you arrive at the actual root cause for the problem. This provides a framework for you to tackle problems methodically.

Communication

One of the most under-rated functions of a software developer is communication. Be it with peers/ managers/ stakeholders, communication is as important as coding for any developer. As developers, we are the closest to any given problem and it is natural for people to rely on us for understanding the whole picture of a product/feature. This makes what you communicate and how you communicate extremely crucial from a business standpoint.

As we are closest to a problem, we will have a lot of technical and domain knowledge around it. But it is extremely important to communicate the right things to the right people. Assume you are in a mail thread with Sr. engineer, PM, Manager, and a Business development executive, you need to provide just the right amount of detail so that the Engineer can get the technical challenges and the others can also understand the complexity technically as well as the business justification. You need to achieve the right amount of balance in the technical/business mixture for the audience to understand and not lose interest. This is where Occam’s razor comes in. You need to provide the least level of detail in the mail and schedule a follow up for the people who need to understand more.

Take this as an example “we did a POC on x and we were able to achieve y. Even though we discussed A in the previous mail, we could not achieve A due to the complexities in a library that we were using. There were a lot of assumptions in the threading model in the library and thus it prevented us from achieving A”.

Now, what do you think the different stakeholders will understand?

1. Engineer — Yes I get the issue.
2. PM- So basically we cant achieve A. And what is a threading model?
3. Manager — Did he try enough to achieve A?

Instead, if we write “we did a POC on x and were able to achieve y. A was targetted but not achieved. I’ll schedule a meeting to demo the POC and go into details on the blocker for A.” After that, you have all the time in the world to explain in detail the blockers for the right audience and achieve a consensus.

Now, what is the thought process after the demo?

1. Engineer — Makes sense.
2. PM — The POC is good for now. I guess we can drop A for now and proceed without it.
3. Manager — He has done an in-depth analysis and knows what he is doing.

Conclusion

Occam’s Razor can be employed in a wide variety of scenarios and these are just a few examples. Developers use this principle intuitively without knowing it. But knowing it and using it deliberately in various situations will greatly improve you as a software developer. If you can think of any other area of Software where this principle is being used feel free to leave your thoughts in comments.

If you liked this article, feel free to reach out to me at https://kaizencoder.com/contact.

A hexagonal architecture simplifies deferring or changing technology decisions. You want to change to a different framework? Write a new adapter. You want to use a database, instead of storing data in files? Again, write an adapter for it.

Draw a boundary around the business logic. The hexagon. Anything inside the hexagon must be free from technology concerns.
The outside of the hexagon talks with the inside only by using interfaces, called ports. Same the other way around. By changing the implementation of a port, you change the technology.

Isolating business logic inside the hexagon has another benefit. It enables writing fast, stable tests for the business logic. They do not depend on web technology to drive them, for example.

Here’s an example diagram. It shows Spring MVC technology as boxes with dotted lines, ports and adapters as solid boxes, and the hexagon without its internals:

An adapter translates between a specific technology and a technology free port. The PoemController adapter on the left receives requests and sends commands to the IReactToCommands port. The PoemController is a regular Spring MVC Controller. Because it actively uses the port, it's called a driver adapter.

IReactToCommands is called a driver port. Its implementation is inside the hexagon. It's not shown on the diagram.

On the right side, the SpringMvcPublisher adapter implements the IWriteLines port. This time, the hexagon calls the adapter through the port. That's why SpringMvcPublisher is called a driven adapter. And IWriteLines is called a driven port.

I show you how to implement that application. We go all the way from a user story to a domain model inside the hexagon. We start with a simple version of the application that prints to the console. Then we switch to Spring Boot and Spring MVC.

From a user story to ports & adapters

The company FooBars.io decides to build a Poetry App. The product owner and the developers agree on the following user story:

As a reader
I want to read at least one poem each day
So that I thrive as a human being

As acceptance criteria, the team agrees on:

• When the user asks for a poem in a specific language, the system displays a random poem in that language in the console
• It's ok to "simulate" the user at first, i.e. no real user interaction. (This will change in future versions.)
• Supported languages: English, German

The developers meet and draw the following diagram:

So the SimulatedUser sends commands to the IReactToCommands port. It asks for poems in English and German. Here's the code, it's available on Github.

_poem/simple/driver_adapter/SimulatedUser.java_

public class SimulatedUser {
    private IReactToCommands driverPort;

    public SimulatedUser(IReactToCommands driverPort) {
        this.driverPort = driverPort;
    }

    public void run() {
        driverPort.reactTo(new AskForPoem("en"));
        driverPort.reactTo(new AskForPoem("de"));
    }
}

The IReactToCommands port has only one method to receive any kind of command.

_poem/boundary/driver_port/IReactToCommands.java_

public interface IReactToCommands{
    void reactTo(Object command);
}

AskForPoem is the command. Instances are simple, immutable POJOs. They carry the language of the requested poem.

poem/command/AskForPoem.java

public class AskForPoem {
    private String language;

    public AskForPoem(String language) {
        this.language = language;
    }

    public String getLanguage() {
        return language;
    }
}

And that's it for the left, driver side of the hexagon. On to the right, driven side.

When the SimulatedUser asks the IReactToCommands port for a poem, the hexagon:

1. Contacts the IObtainPoems port for a collection of poems
2. Picks a random poem from the collection
3. Tells the IWriteLines port to write the poem to the output device

You can't see Step 2 yet. It happens inside the hexagon, in the domain model. That's the business logic of the example. So we focus on Step 1 and Step 3 first.

In Step 1, the collection of poems is a language dependent, hard coded array. It's provided by the HardcodedPoemLibrary adapter that implements the IObtainPoems port.

_poem/boundary/driven_port/IObtainPoems.java_

public interface IObtainPoems {
    String[] getMePoems(String language);
}

_poem/simple/driven_adapter/HardcodedPoemLibrary.java_

public class HardcodedPoemLibrary implements IObtainPoems {
    public String[] getMePoems(String language) {
        if ("de".equals(language)) {
            return new String[] { /* Omitted for brevity */ };
        } else { 
            return new String[] { /* Omitted for brevity */ };
        }
    }
}

In Step 3, the ConsoleWriter adapter writes the lines of the poems to the output device, i.e. the console.

_poem/boundary/driven_port/IWriteLines.java_

public interface IWriteLines {
    void writeLines(String[] strings);
}

_poem/simple/driven_adapter/ConsoleWriter.java_

public class ConsoleWriter implements IWriteLines {
    public void writeLines(String[] lines) {
        Objects.requireNonNull(lines);
        for (String line : lines) {
            System.out.println(line);
        }
        System.out.println("");
    }
}

We have created all the ports, and a simple implementation of all the adapters. So far, the inside of the hexagon remained a mystery. It's up next.

Command handlers (inside the hexagon)

When a user asks for a poem, the system displays a random poem.
Similar in the code: when the IReactToCommands port receives an AskForPoemcommand, the hexagon calls a DisplayRandomPoem command handler.

The DisplayRandomPoem command handler obtains a list of poems, picks a random one and writes it to the output device. This is exactly the list of steps we talked about in the last clause.

_poem/boundary/internal/command_handler/DisplayRandomPoem.java_

public class DisplayRandomPoem implements Consumer<AskForPoem> {
        /* Omitted for brevity */

    @Override
    public void accept(AskForPoem askForPoem) {
        List<Poem> poems = obtainPoems(askForPoem);
        Optional<Poem> poem = pickRandomPoem(poems);
        writeLines(poem);   
    }

        /* Rest of class omitted for brevity */
}

It's also the job of the command handler to translate between the domain model data and the data used in the port interfaces.

Tying commands to command handlers

In my implementation of a hexagonal architecture, there is only a single driver port, IReactToCommands. It reacts to all types of commands.

public interface IReactToCommands{
    void reactTo(Object command);
}

The Boundary class is the implementation of the IReactToCommands port. It creates a behavior model using a library. The behavior model maps each command type to a command handler. Then, a behavior dispatches the commands based on the behavior model.

poem/boundary/Boundary.java

public class Boundary implements IReactToCommands, BehaviorModel {
  private final IObtainPoems poemObtainer;
  private final IWriteLines lineWriter;
  private final StatelessBehavior behavior;

  private static final Class<AskForPoem> asksForPoem = AskForPoem.class;

  public Boundary(IObtainPoems poemObtainer, IWriteLines lineWriter) {
    this.poemObtainer = poemObtainer;
    this.lineWriter = lineWriter;
    this.behavior = StatelessBehavior.of(this);
  }

  @Override
  public Model model() {
    return Model.builder()
        .user(asksForPoem).system(displaysRandomPoem())
        .build();
  }

  @Override
  public void reactTo(Object commandObject) {
    behavior.reactTo(commandObject);
  }

  private Consumer<AskForPoem> displaysRandomPoem() {
    return new DisplayRandomPoem(poemObtainer, lineWriter);
  }
}

The domain model

The domain model of the example doesn’t have very interesting functionality. The RandomPoemPicker picks a random poem from a list.

A Poem has a constructor that takes a String containing line separators, and splits it into verses.

The really interesting bit about the example domain model: it doesn’t refer to a database or any other technology, not even by interface!

That means that you can test the domain model with plain unit tests. You don’t need to mock anything.

Such a pure domain model is not a necessary property of an application implementing a hexagonal architecture. But I like the decoupling and testability it provides.

Plug adapters into ports, and that's it

A final step remains to make the application work. The application needs a main class that creates the driven adapters. It injects them into the boundary.
It then creates the driver adapter, for the boundary, and runs it.

poem/simple/Main.java

public class Main {
    public static void main(String[] args) {
        new Main().startApplication();
    }

    private void startApplication() {
        // Instantiate driven, right-side adapters
        HardcodedPoemLibrary poemLibrary = new HardcodedPoemLibrary();
        ConsoleWriter consoleWriter = new ConsoleWriter();

        // Inject driven adapters into boundary
        Boundary boundary = new Boundary(poemLibrary, consoleWriter);

        // Start the driver adapter for the application
        new SimulatedUser(boundary).run();
    }
}

And that's it! The team shows the result to the product owner. And she's happy with the progress. Time for a little celebration.

Switching to Spring

The team decides to turn the poem app into a web application. And to store poems in a real database. They agree to use the Spring framework to implement it.
Before they start coding, the team meets and draws the following diagram:

Instead of a SimulatedUser, there is a PoemController now, that sends commands to the hexagon.

_poem/springboot/driver_adapter/PoemController.java_

@Controller
public class PoemController {
    private SpringMvcBoundary springMvcBoundary;

    @Autowired
    public PoemController(SpringMvcBoundary springMvcBoundary) {
        this.springMvcBoundary = springMvcBoundary;
    }

    @GetMapping("/askForPoem")
    public String askForPoem(@RequestParam(name = "lang", required = false, defaultValue = "en") String language,
            Model webModel) {
        springMvcBoundary.basedOn(webModel).reactTo(new AskForPoem(language));

        return "poemView";
    }
}

When receiving a command, the PoemController calls springMvcBoundary.basedOn(webModel). This creates a new Boundary instance, based on the webModel of the request:

poem/springboot/boundary/SpringMvcBoundary.java

public class SpringMvcBoundary {
    private final IObtainPoems poemObtainer;

    public SpringMvcBoundary(IObtainPoems poemObtainer) {
        this.poemObtainer = poemObtainer;
    }

    public IReactToCommands basedOn(Model webModel) {
        SpringMvcPublisher webPublisher = new SpringMvcPublisher(webModel);
        IReactToCommands boundary = new Boundary(poemObtainer, webPublisher);
        return boundary;
    }
}

The call to reactTo() sends the command to the boundary, as before. On the right side of the hexagon, the SpringMvcPublisher adds an attribute lines to the Spring MVC model. That's the value Thymeleaf uses to insert the lines into the web page.

_poem/springboot/driven_adapter/SpringMvcPublisher.java_

public class SpringMvcPublisher implements IWriteLines {
    static final String LINES_ATTRIBUTE = "lines";

    private Model webModel;

    public SpringMvcPublisher(Model webModel) {
        this.webModel = webModel;
    }

    public void writeLines(String[] lines) {
        Objects.requireNonNull(lines);
        webModel.addAttribute(LINES_ATTRIBUTE, lines);
    }
}

The team also implements a PoemRepositoryAdapter to access the PoemRepository. The adapter gets the Poem objects from the database. It returns the texts of all poems as a String array.

_poem/springboot/driven_adapter/PoemRepositoryAdapter.java_

public class PoemRepositoryAdapter implements IObtainPoems {
    private PoemRepository poemRepository;

    public PoemRepositoryAdapter(PoemRepository poemRepository) {
        this.poemRepository = poemRepository;
    }

    @Override
    public String[] getMePoems(String language) {
        Collection<Poem> poems = poemRepository.findByLanguage(language);
        final String[] poemsArray = poems.stream()
            .map(p -> p.getText())
            .collect(Collectors.toList())
            .toArray(new String[0]);
        return poemsArray;
    }
}

Finally, the team implements the Application class that sets up an example repository and plugs the adapters into the ports.

And that's it. The switch to Spring is complete.

Conclusion

There are many ways to implement a hexagonal architecture. I showed you a straightforward approach that provides an easy to use, command driven API for the hexagon. It reduces the number of interfaces you need to implement. And it leads to a pure domain model.

If you want to get more information on the topic, read Alistair Cockburn’s original article on the subject.

The example in this article is inspired by a three part series of talks by Alistair Cockburn on the subject.

Last updated on 30 July 2021.__. If you want to keep up with what I’m doing or drop me a note, follow me on dev.to, LinkedIn or Twitter. Or visit my GitHub project. To learn about agile software development, visit my online course.

#

Clean Architecture

There are many videos and articles explaining clean architecture. Most of these go over the concepts from a 20,000 foot view. I don’t know about you, but I don’t learn things very well at that elevation. Not a lot of oxygen up there. I learn by jumping in head first and coding. This article and the accompanying code is what I ended up with after such a leap.

Bob’s Your Uncle

The term “Clean Architecture” was made popular by Robert Martin (Uncle Bob) and his book “Clean Architecture: A Craftsman’s Guide to Software Structure and Design.” Now I don’t proclaim to be an expert in this field and I haven’t read his book, though I intend to. But I can completely relate to the problems it is trying to solve.

How do you write a software system that is not dependent on anything other than a primary language ? We were promised this in the past with interfaces and other OO principles, but I had never before seen a “clean”, pun intended, explanation on how to do this regarding the whole system. And yes, I am a bit late to this party, being that Uncle Bob started to talk about these concepts in 2012, which is a century ago in software years.

The Diagram That Baffled Me

Here is the original diagram Uncle Bob and others used in their presentations when explaining Clean Architecture. This simple little diagram became an obsession of mine. I had long ago purged my memory of anything UML related and was struggling with the has-a, and uses-a relationships indicated by the open and close arrow heads. The only way I was going to figure this out was by writing some code.

Image Credit: Uncle Bob

Know Your Onions

One way to look at Clean Architecture is as an onion with layers. All layers can only depend on a layer that is closer to the center. That is, all dependencies point inward and not outward.

_[Image Credit](https://android.jlelse.eu/thoughts-on-clean-architecture-b8449d9d02df" rel="noopener" target="blank" title=")

One of These Days, I’m Gonna Get Organizized

In our example, there are 4 modules that correspond with each layer of this onion. Eventually these could be separate npm modules. For readability’s sake, I tried to name things according to Uncle Bob’s original Clean Architecture diagram at the top of this article. In the real world you would probably preface all names with what ever use case they represented.

Image Credit: Myself

The infrastructure (blue) layer is where all of our outside pluggable systems live. These outside systems such as devices, web, and UIs, shown in the onion diagram, will use our IRequest and IViewModel interfaces to communicate with our Controller and Presenter while the db and external interfaces, shown in the onion diagram, will use the IEntityGateway interface to communicate with our Interactor.

Our example will have one entity called a Widget with three properties. It also uses one use case “create widget” which takes a widget from the UI, saves the widget to some sort of storage, and returns back to the UI a newly created widget with an id and a revision number.

More Visual Aids

Here is the directory structure. Everything gets wired together in each module’s index.ts file. The entry point is demonstrated in a test located in infrastructure/test/TestEntryPoint.spec.ts .

Image Credit: Shift Command 4

Which Way Did He Go?

One of my original hangups was how the outer most layer communicates with the inner layers. I thought all you had to do is call some createWidget() function, for example, on a Controller and you would get a nice shiny new widget returned back to you. Wrong.

What you want to do is send the widget to be created down to the use case (Interactor) on a certain path and have the use case (Interactor) send the new widget back up to you on a different path. This is similar to a callback function or a Promise. I found a good diagram illustrating this in an article titled “Implementing Clean Architecture — Of controllers and presenters” (link below). In our example I have not implemented a RequestModel or a ResponseModel.

_[Image Credit](https://plainionist.github.io/Implementing-Clean-Architecture-Controller-Presenter/" rel="noopener" target="blank" title=")

Step Into, Step Over, and Step Out, the OO Way

So let’s first create a widget with classes and interfaces.

OO Step 1

This is the entry point. This code would be located in the infrastructure (blue) layer. This layer is where your mobile app, web app, API, CLI, etc. lives. Also all of your outside systems like external APIs, frameworks, libraries and databases live here too. Everything is pluggable in this layer and communicates with our system via interfaces we provide.

First you create your ViewModel implementation of the IViewModel interface where a new widget will appear and you can update your UI within the implemented function presentWidget(widget).

You then create a Controller that implements the IRequest interface by passing the EntityGateway and the ViewModel you created above to a constructor. Finally your UI calls createWidget(widget) on the Controller where your new widget begins its journey to the Interactor.

What’s an EntityGateway?

An EntityGateway implements the IEntityGateway interface and is where you implement specific code that persists your widget. It lives in the infrastructure (blue) layer. This could be any type of existing or future external API or persistence system such as a database.

To change out to a different system, you would just simply wire together the new EntityGateway implementation with the IEntityGateway interface. In this example, I use a Promise to simulate some sort of persistence operation.

Wire up What?

The file infrastructure/src/index.ts in the infrastructure module is where you can wire up your different implementations of your IEntityGateway interface. The “from” path of the import statement points to the correct implementation. In this case it is a persistence system named AnyDB.

Uncle Bob also talks about the use of a Main class where you can do this type of wiring up or do other initializing code. The Main class would also live in the infrastructure module and be pluggable. It would also communicate in the same manner as the other systems in the infrastructure module do. For example, you would initiate this class in your UI’s initializing code and pass it down into your more inner layers to be used via some sort of configuration interface.

Our example does not use a Main class and instead is passing the persistence system down into the interactor via the createWidget() function. This is probably not the “pure” way of doing this, but was done to make our example easier to read.

OO Step 2

The Controller is a very busy place. First, the EntityGateway passes through unchanged to our Interactor constructor. Then our ViewModel gets passed to the constructor of our Presenter which in turn also gets passed to our Interactor constructor. This all happens in the createWidget(widget) function of the Controller which was called by our UI in step 1 via the IRequest interface. We will talk about our Presenter in step 4 when the newly created widget travels back up to the UI.

OO Step 3

Finally we are at the most inner layer of our journey, the usecase layer where our Interactor lives. Or better known as our home for all of our app’s use case logic. There is one more inner layer, the domain. This is where all of our business entities and business specific logic lives. In this example, we really don’t have any need to go there except to borrow the WidgetType and IEntityGateway interfaces.

Movin On Up

Here in our Interactor we take the EntityGateway that was passed through from the Controller and call its saveWidget(widget) function via the IEntityGateway interface. This function returns a Promise from the EntityGateway which resolves in .then() with a newly created widget. We then call the Presenter’s presentWidget(widget) function via the IOutputBoundary interface which starts the newly created widget back up to the UI. This all happens in the Interactor’s createWidget(widget) function which was called by our Controller via the IInputBoundary interface in step 2.

OO Step 4

Here in our Presenter, we simply pass the widget to our ViewModel’s presentWidget(widget) function we created in our UI. This all happens in the Presenter’s presentWidget(widget) function via the IOutputBoundary interface which was called in the Interactor’s createWidget(widget) function in step 3. More can happen here, but not in our example.

OO Step 5

Finally our newly created widget is back home ready to be displayed in our UI. This is the exact spot (code) where we started in step 1. Updating the UI happens in the ViewModel’s presentWidget(widget) function via the IViewModel interface which was called in the Presenter’s presentWidget(widget) function in step 4.

OO Supporting Cast Members

Here are all the remaining interfaces and type definitions clumped together in one file.

2 Men Enter 1 Man Leaves

I wrote the class and interface version of this project first. I wanted to try and make it match Uncle Bob’s original diagram as close as I could. When I finished that project, I realized I could have done the same thing with functions and type definitions. So I created an identical project and replaced Classes with Functions and Interfaces with Type definitions.

And here is the difference between a Controller class and a Controller function.

Step Into, Step Over, and Step Out, the Function Way

Now lets give a stab at creating widgets with functions and type definitions.

General Differences

WidgetType is identical as the OO version above and IEntityGateway, IRequest, IViewModel, IInputBoundary, and IOutputBoundary are now type definitions instead of interfaces.

Function Step 1

Every thing is the same as OO step 1 above, other than that we are now importing a function named “controllerConstructor” instead of a class named “Controller.” And importing a function named “entityGateway” instead of a class named EntityGateway. Last but not least, the ViewModel we created is now an object with a presentWidget() function in it instead of a class with a presentWidget() function.

EntityGateway Again?

The EntityGateway does the same task as the OO version above. It is now a function instead of a class. It returns a saveWidget() function wrapped in an object.

More Wiring

Same as OO version above except we are now exporting a function instead of a class.

Function Step 2

Our Controller is still a busy place and does the same tasks as the OO version. We are now importing a function named interactorConstructor instead of a class named Interactor. We are exporting a function named “controllerConstructor” instead of a class named “Controller.” It returns a function named “createWidget wrapped in an object.

Function Step 3

Back in the Iteractor in our usecase module, we are executing the same tasks as the OO version above. We are now exporting a function named “interactorConstructor” instead of a class named “Interactor.” It returns a function named “createWidget wrapped in an object.

Function Step 4

We are now passing the newly created widget back up in our Presenter where we are executing the same tasks as the OO version above. We export a function named “presenterConstructor” instead of a class named “Presenter.” It returns a function named “presentWidget wrapped in an object.

Function Step 5

Again we have come full circle and we are back in the exact spot (code) where we started in step 1. Our UI gets updated with our newly created widget in the ViewModel’s presentWidget() function.

Function Supporting Cast Members

Here are all the remaining type definitions clumped together in one file. These are our interfaces.

All That for a Damn Widget?

Yes, but you also get the promise of a completely decoupled system where you can plug in different implementations of your outside (infrastructure blue layer) systems, including different types of UIs, external APIs, databases, libraries, frameworks and more.

We Don’t Need No Stinkin Profilers

My original hunch was that the class and interface version would be slower than the function version. So I ran both projects through my advance profiling tools of typing “npm test” and pressing enter until my finger cramped up.

My first observation was that the function version was about twice as fast, WOW. Then I decided to refactor the function version to return all of the important functions wrapped in objects so I could enforce the function names. I then ran both versions through my advance profilers and they were about the same speed.

I have no idea why wrapping a function in an object would slow it down that much. Maybe I didn’t actually get Adobe Flash completely uninstalled from my laptop and it decided to interfere. Anyways, it would be interesting to get a more accurate measure of speed using the correct tools against the compiled JavaScript.

The Take Away

The OO version has more code but may be easier to read and follow. The function version has less code but may be harder to read and follow.

Personally I like the function version, being that I have done a lot of programming in Java and I am tired of writing so many classes. One of the things I like the most about TypeScript/JavaScript is the ability to use object literals. And with TypeScript type definitions, you can now apply some safety to using object literals.

Another take away is that you don’t need to rigidly conform to the clean architecture as diagrammed above to achieve a decoupled system. For example, you could just as easily have your UI communicate directly with your use case layer bypassing the delivery layer if it’s not needed. All of these layers may physically live in different places and have different ways of communicating with each other.

Give it a Try

Here are some of the things I intend to enforce in my next project.

1. Dependencies should always go one way.
2. Dependencies should always point from your outside systems (UI, db, etc.) to your business entities and business logic.
3. Your inner layers (delivery, use case, and business entities) need to expose interfaces for the more outer layers to use.
4. You should always start developing from the most inner layer out. Start with the business entities and logic first and test. Create the interfaces that will be used and then test these interfaces. I am guilty of working the other way around. I think we all like to start with the UI, because it immediately lets us visually see how our system will look to a user. Plus the UI is where a lot of the “cool” technologies live.
5. Use TDD (Test Driven Development). Clean architecture allows you to do this much more easily. Everything is more compartmentalized and easier to mock. The implementation of the IEntityGateway above is basically a mock of a database.
6. Last but not least, be flexible. Don’t knock yourself out trying to adhere to clean architecture when that library or framework you want to use just won’t work with it. But be warned that this is probably a good indication that you will eventually have some sort of problems regarding that library or framework, especially if it wants you to extend their classes. Decoupling should be your goal.

But, But, What About…

Please ask questions and give feedback, there is no better way to learn than to get constructive criticism from your peers. And it is highly probable that I missed something somewhere.

Resources:

Code for the OO version is located at:

https://github.com/warrenbell/cleanarch-tsoo

Code for the function version is located at:

https://github.com/warrenbell/cleanarch-tsfun

ts-node

Handy little TypeScript tool.

https://github.com/TypeStrong/ts-node

The Clean Architecture by Uncle Bob

https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html

The Book

https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164

One of Many Videos

They are all basically the same except for the the first 5 minutes where Uncle Bob likes to muse about something loosely related and then makes a hard segue into clean architecture.

https://www.youtube.com/watch?v=Nltqi7ODZTM

Implementing Clean Architecture — Of controllers and presenters

https://plainionist.github.io/Implementing-Clean-Architecture-Controller-Presenter/

Clean Architecture: Standing on the shoulders of giants

https://herbertograca.com/2017/09/28/clean-architecture-standing-on-the-shoulders-of-giants/

Clean Architecture: Use case containing the presenter or returning data?

https://softwareengineering.stackexchange.com/questions/357052/clean-architecture-use-case-containing-the-presenter-or-returning-data

Clean architecture. What are the jobs of presenter?

https://stackoverflow.com/questions/46510550/clean-architecture-what-are-the-jobs-of-presenter