You have a set of objects: different types, shapes, and data. And at some point, someone asks you to perform an operation on all of them, like exporting them them to PDF, sending them a notification, generating a report, or calculating their fees.

Your first instinct might be to write a function that checks the type and branches accordingly, like an if-else block or switch statement. Something that says: if this is a NewUser, do this. If this is a JointAccountUser, do that. It works, you ship it, and everyone is happy.

Then another operation comes in. And another. Every single time, you go back to the same place and add another branch. The function grows. The class grows. The test surface grows. What started as a clean model is now a god object that knows how to do everything for everyone.

The Visitor Design Pattern exists to break this cycle completely.

Table of Contents

• What is the Visitor Design Pattern?

• The Problem the Visitor Pattern Solves

• Core Components

• Real World Example One: Document Export

• Real World Example Two: Notification System

• Real World Example Three: Fee Calculation

• The Power of Combining All Three Operations

• When to Use the Visitor Pattern

• When Not to Use It

• Conclusion

What is the Visitor Design Pattern?

The Visitor pattern is a behavioral design pattern that lets you define a new operation on a family of objects without changing the objects themselves.

The key word there is behavioral. Behavioral patterns are about how objects communicate and distribute responsibility. Where creational patterns deal with how objects are created and structural patterns deal with how they are composed, behavioral patterns deal with how they interact and who is responsible for what.

The Visitor pattern specifically deals with the question of who should own an operation when that operation needs to work differently across multiple object types.

The classic answer is: put the operation on each object. Give each class a method that handles the operation for its own type. But this breaks down the moment you have multiple operations, because now every new operation means touching every class. You're spreading one concern across your entire object hierarchy.

The Visitor pattern flips this. Instead of spreading the operation across the objects, you collect it into one place called a Visitor. The objects simply accept the visitor and let it do its work. Adding a new operation means creating a new Visitor. The existing objects don't change at all.

This is the Open/Closed Principle working exactly as intended: open for extension, closed for modification.

The Problem the Visitor Pattern Solves

Let me show you exactly what this looks like without the Visitor pattern.

Say you have a fintech platform with four types of users: existing customers, new customers, minor account holders, and joint account holders. Your product manager comes in and asks you to add document export. Every user type should be exportable to PDF, Excel, and CSV.

Without Visitor, the natural approach looks something like this:

class ExistingUser {
  final int id;
  final String firstName;
  final String lastName;
  final DateTime lastPaymentDate;
  final num accountBalance;

  String exportToPdf() {
    return '$firstName\n$lastName\n$lastPaymentDate\n$accountBalance';
  }

  String exportToExcel() {
    return '$firstName,$lastName,$lastPaymentDate,$accountBalance';
  }

  String exportToCsv() {
    return '"$firstName","$lastName","$lastPaymentDate","$accountBalance"';
  }
}

And you repeat this for NewUser, MinorAccountUser, and JointAccountUser. Twelve methods spread across four classes just for document export.

Now the product manager comes back. They want notifications: email, SMS, and Push. Back you go to all four classes, adding three more methods each. Twelve more methods spread across the same four classes.

Then they want fee calculation. Then they want KYC status checks. Every new operation multiplies across every user type. The classes grow, the reasons to change multiply, and testing becomes painful.

This is the exact problem the Visitor pattern was built to solve.

Core Components

The Visitor pattern has four core components. Understanding each one before looking at code makes the implementation much easier to follow.

The Visitor Interface

This is the contract that every visitor must implement. It declares one method per object type it needs to visit. A visitor that handles four user types declares four visit methods, one for each type.

The Concrete Visitors

These are the real implementations of the Visitor interface. Each one represents a single operation and knows how to handle every object type. A PdfHandler is a concrete visitor. An ExcelHandler is a concrete visitor. A SmsNotificationHandler is a concrete visitor. Each one has one job and knows how to do that job for every user type.

The Consumer Interface (also called Element or Acceptor)

This is the contract that every object in the hierarchy must implement. It declares a single accept method that takes a Visitor and calls the right visit method on it. This is the double dispatch mechanism that makes the pattern work.

The Concrete Consumers

These are the real objects in the hierarchy: ExistingCustomers, NewCustomers, MinorCustomer, and JointCustomer. Each one implements accept by calling the specific visit method that corresponds to its own type.

Think of it this way. The Visitor interface is implemented by every operation you want to perform: PdfHandler, ExcelHandler, and CsvHandler. Each of these knows how to handle all four user types.

The Consumer interface is implemented by every object in the hierarchy: ExistingCustomers, NewCustomers, MinorCustomer, and JointCustomer. Each of these knows how to receive a visitor and route it to the correct method.

When you call existingCustomer.accept(pdfHandler), ExistingCustomers calls pdfHandler.visitExistingCustomer(this) and passes itself as the argument. The right method fires automatically. There's no type checking, if-else, or switch. The object tells the visitor who it is, and the visitor knows exactly what to do with that information.

Real World Example One: Document Export

This is a real scenario from a fintech platform. There are four user types with different data structures, all needing to export their information to three document formats: PDF, Excel, and CSV.

Step 1: Define the User Models

class ExistingUser {
  final int id;
  final String firstName;
  final String lastName;
  final DateTime lastPaymentDate;
  final num accountBalance;

  const ExistingUser({
    required this.id,
    required this.firstName,
    required this.lastName,
    required this.lastPaymentDate,
    required this.accountBalance,
  });
}

class NewUser {
  final String firstName;
  final String lastName;

  const NewUser({
    required this.firstName,
    required this.lastName,
  });
}

class MinorAccountUser {
  final int age;
  final int guardianId;
  final String firstName;
  final String lastName;
  final String guardianName;

  const MinorAccountUser({
    required this.age,
    required this.guardianId,
    required this.firstName,
    required this.lastName,
    required this.guardianName,
  });
}

class JointAccountUser {
  final int jointAccountId;
  final List<String> accountHoldersInfo;
  final num accountBalance;

  const JointAccountUser({
    required this.jointAccountId,
    required this.accountHoldersInfo,
    required this.accountBalance,
  });
}

We have four models. Each one owns its own data and nothing else. There's no export logic or notification logic. And no business operations of any kind. Just clean data structures.

This is exactly how it should be. The model's job is to hold data. The visitor's job is to operate on it.

Step 2: Define the Visitor and Consumer Interfaces

abstract class UserVisitor<T> {
  T visitExistingCustomer(ExistingUser user);
  T visitNewCustomer(NewUser user);
  T visitMinorCustomer(MinorAccountUser user);
  T visitJointCustomer(JointAccountUser user);
}

abstract class UserConsumer {
  T accept<T>(UserVisitor<T> visitor);
}

UserVisitor<T> is generic. The type parameter T represents what the visitor returns. A document export visitor returns a String. A fee calculation visitor might return a double. A validation visitor might return a bool. The same pattern works for any return type.

UserConsumer declares the accept method. Every object in the hierarchy must implement this. The accept method is what makes the double dispatch work. The object receives the visitor and immediately calls the right visit method on it, passing itself as the argument.

Step 3: Implement the Concrete Consumers

class ExistingCustomers implements UserConsumer {
  final ExistingUser user;
  ExistingCustomers({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitExistingCustomer(user);
  }
}

class NewCustomers implements UserConsumer {
  final NewUser user;
  NewCustomers({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitNewCustomer(user);
  }
}

class MinorCustomer implements UserConsumer {
  final MinorAccountUser user;
  MinorCustomer({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitMinorCustomer(user);
  }
}

class JointCustomer implements UserConsumer {
  final JointAccountUser user;
  JointCustomer({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitJointCustomer(user);
  }
}

Each consumer wraps one user model and implements accept by forwarding to the correct visit method. This is the entire job of a concrete consumer. It knows who it is, and it tells the visitor by calling the right method.

Notice that none of these classes know anything about PDF, Excel, CSV, email, SMS, or any operation. They're completely decoupled from every operation that will ever be performed on them.

Step 4: Implement the Concrete Visitors

class PdfHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '${user.firstName} ${user.lastName}'
        '\nBalance: ${user.accountBalance}'
        '\nLast Payment: ${user.lastPaymentDate}';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '${user.firstName} ${user.lastName}';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '${user.firstName} ${user.lastName}'
        '\nAge: ${user.age}'
        '\nGuardian: ${user.guardianName} (ID: ${user.guardianId})';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.join(', ');
    return 'Joint Account ID: ${user.jointAccountId}'
        '\nHolders: $holders'
        '\nBalance: ${user.accountBalance}';
  }
}

class ExcelHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '${user.firstName}\t${user.lastName}'
        '\t${user.accountBalance}\t${user.lastPaymentDate}';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '${user.firstName}\t${user.lastName}';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '${user.firstName}\t${user.lastName}'
        '\t${user.age}\t${user.guardianName}\t${user.guardianId}';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.join('\t');
    return '${user.jointAccountId}\t$holders\t${user.accountBalance}';
  }
}

class CsvHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '"${user.firstName}","${user.lastName}"'
        ',"${user.accountBalance}","${user.lastPaymentDate}"';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '"${user.firstName}","${user.lastName}"';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '"${user.firstName}","${user.lastName}"'
        ',"${user.age}","${user.guardianName}","${user.guardianId}"';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.map((h) => '"$h"').join(',');
    return '"${user.jointAccountId}",$holders,"${user.accountBalance}"';
  }
}

Each handler implements the visitor interface and knows exactly how to format each user type for its specific document format. PdfHandler uses newlines and labels. ExcelHandler uses tabs. CsvHandler wraps values in quotes and separates with commas.

The formatting logic for each document type lives in exactly one class. If the PDF format changes, you touch only PdfHandler. If the CSV format changes, you touch only CsvHandler. The user models never change.

Step 5: Use It

void existingUserLogic() {
  final customer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  final pdf = customer.accept(PdfHandler());
  final excel = customer.accept(ExcelHandler());
  final csv = customer.accept(CsvHandler());

  print('PDF:\n$pdf\n');
  print('Excel:\n$excel\n');
  print('CSV:\n$csv\n');
}

void newUserLogic() {
  final customer = NewCustomers(
    user: NewUser(
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

void minorUserLogic() {
  final customer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      guardianName: 'Inioluwa',
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

void jointUserLogic() {
  final customer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

The same customer object accepts any visitor with the same call. The type dispatch happens automatically through the accept method. There's no type checking anywhere in the calling code, and no if-else or switch. Just customer.accept(handler) and the right method fires.

Now think about what happens when you need to add an XML export. You create one new class, XmlHandler, implement the four visit methods, and that's it. You don't touch ExistingUser, NewUser, MinorAccountUser, JointAccountUser, or any of the existing handlers. The system is genuinely open for extension and closed for modification.

Real World Example Two: Notification System

Here we have the same four user types and the same pattern. But it's a different operation entirely.

Your platform needs to notify users about account events. But not every user type should be notified the same way.

Existing users get email and push notifications. New users only get email because they haven't fully set up their profile yet. Minor account users get SMS to their guardian's number. Joint account users get notified on all channels because multiple people share the account.

Without the Visitor pattern, this logic would spread across all four user models or collapse into one enormous function full of type checks. With Visitor, it lives in three focused classes.

The Notification Visitor Interface

abstract class NotificationVisitor {
  void visitExistingCustomer(ExistingUser user);
  void visitNewCustomer(NewUser user);
  void visitMinorCustomer(MinorAccountUser user);
  void visitJointCustomer(JointAccountUser user);
}

This visitor returns void because notifications are side effects. They send messages, they don't return values.

The Concrete Notification Visitors

class EmailNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Sending email to existing customer: ${user.firstName}');
    // email service call with full account details
  }

  @override
  void visitNewCustomer(NewUser user) {
    print('Sending welcome email to new customer: ${user.firstName}');
    // welcome email with onboarding steps
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    print('Sending email to guardian: ${user.guardianName}');
    // email goes to guardian, not the minor
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Sending email to joint holder: $holder');
      // all account holders get notified
    }
  }
}

class SmsNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Sending SMS to existing customer: ${user.firstName}');
  }

  @override
  void visitNewCustomer(NewUser user) {
    // new users are not SMS-verified yet, skip
    print('New customer ${user.firstName} not SMS-eligible yet');
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    print('Sending SMS to guardian ${user.guardianName} for minor ${user.firstName}');
    // SMS goes to guardian's registered number
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Sending SMS to joint holder: $holder');
    }
  }
}

class PushNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Push notification to existing customer: ${user.firstName}');
  }

  @override
  void visitNewCustomer(NewUser user) {
    print('Push notification to new customer: ${user.firstName}');
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    // minors do not have the app installed yet, guardian gets push
    print('Push notification to guardian: ${user.guardianName}');
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Push notification to joint holder: $holder');
    }
  }
}

Each handler knows the specific rules for each user type. SmsNotificationHandler knows that new users aren't SMS-verified yet. PushNotificationHandler knows that minor account notifications go to the guardian. EmailNotificationHandler knows that joint account holders all need to be notified individually.

This business logic lives in exactly one place per notification channel. When the rules change (and they always change), you update one class.

Using the Notification Visitors

void notifyExistingUser() {
  final customer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

void notifyMinorUser() {
  final customer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      guardianName: 'Inioluwa',
    ),
  );

  // all three channels fire, each with minor-specific rules
  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

void notifyJointUser() {
  final customer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

The calling code is identical regardless of the user type or the notification channel. The dispatch is automatic. The rules live inside the visitors.

When WhatsApp notifications become a requirement (and they will), you create one WhatsAppNotificationHandler class with four visit methods. Nothing else changes.

Real World Example Three: Fee Calculation

Again, we have the same four user types and the same pattern. And once again, we have a completely different operation.

Your platform needs to calculate monthly maintenance fees. But each user type has different rules.

Existing customers pay a flat monthly fee based on their account balance. New customers are fee-exempt for their first three months. Minor account holders pay a reduced fee because their accounts have restricted features. Joint account holders have their fee split equally across all account holders.

Without Visitor, this logic ends up as a giant method somewhere with four branches, or worse, it leaks into the user models themselves. With Visitor, it lives in one focused class.

The Fee Visitor Interface

abstract class FeeVisitor {
  double visitExistingCustomer(ExistingUser user);
  double visitNewCustomer(NewUser user);
  double visitMinorCustomer(MinorAccountUser user);
  double visitJointCustomer(JointAccountUser user);
}

This visitor returns a double because fee calculation produces a numeric value.

The Concrete Fee Visitor

class MonthlyFeeCalculator implements FeeVisitor {
  @override
  double visitExistingCustomer(ExistingUser user) {
    // 0.5% of account balance, minimum 500, maximum 5000
    final fee = user.accountBalance * 0.005;
    return fee.clamp(500, 5000).toDouble();
  }

  @override
  double visitNewCustomer(NewUser user) {
    // new customers are fee-exempt for the first 3 months
    return 0.0;
  }

  @override
  double visitMinorCustomer(MinorAccountUser user) {
    // flat reduced fee for minor accounts
    return 150.0;
  }

  @override
  double visitJointCustomer(JointAccountUser user) {
    // standard fee split equally across all holders
    const standardFee = 2000.0;
    return standardFee / user.accountHoldersInfo.length;
  }
}

Every fee rule for every user type lives in this one class. When the fee structure changes for existing customers, you touch one method in one class. When minor account fees are updated, same thing. None of the user models change, and no other visitor changes.

Using the Fee Visitor

void calculateFees() {
  final existingCustomer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  final newCustomer = NewCustomers(
    user: NewUser(
      firstName: 'Aderonke',
      lastName: 'Fatunmole',
    ),
  );

  final minorCustomer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Inioluwa',
      lastName: 'Fatunmole',
      guardianName: 'Oluwaseyi',
    ),
  );

  final jointCustomer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  final calculator = MonthlyFeeCalculator();

  final existingFee = existingCustomer.accept(calculator);
  final newFee = newCustomer.accept(calculator);
  final minorFee = minorCustomer.accept(calculator);
  final jointFee = jointCustomer.accept(calculator);

  print('Existing customer fee: NGN $existingFee');
  print('New customer fee: NGN $newFee');
  print('Minor account fee: NGN $minorFee');
  print('Joint account fee per holder: NGN $jointFee');
}

The output:

Existing customer fee: NGN 5000.0
New customer fee: NGN 0.0
Minor account fee: NGN 150.0
Joint account fee per holder: NGN 500.0

When a PremiumFeeCalculator is needed for a new tier of customers, you create one new class that implements FeeVisitor. The user models stay exactly as they are. The MonthlyFeeCalculator stays exactly as it is. The accept methods on all four consumers stay exactly as they are.

The Power of Combining All Three Operations

Here's what makes the Visitor pattern truly shine in a system like this. You have the same four user types, and you can run any combination of visitors on any of them in the same call chain.

void processUser(UserConsumer customer) {
  final pdf = customer.accept(PdfHandler());
  final csv = customer.accept(CsvHandler());

  customer.accept(EmailNotificationHandler());
  customer.accept(PushNotificationHandler());

  final fee = customer.accept(MonthlyFeeCalculator());

  print('Fee: NGN $fee');
  print('Documents generated and notifications sent');
}

One function, any user type, any combination of operations. The consumer doesn't care which visitors it receives. The visitors don't care which consumers call them. They speak to each other through the interface, and the interface guarantees everything works correctly.

We have three completely different operations (document export, notifications, and fee calculation) all applied to the same object with the same call pattern. None of these operations know about each other. None of them touch the user models. Each one lives in its own focused class with its own single reason to change.

When to Use the Visitor Pattern

Use Visitor when you have a stable set of object types and a growing set of operations on them.

The pattern shines when the object hierarchy is unlikely to change frequently. It's optimized for adding new operations, not new types. Adding a new user type means updating every existing visitor. If your object types change constantly, Visitor creates more work than it saves.

It's also very effective when you need to perform multiple unrelated operations on a family of objects without polluting their classes with that logic. Document export, notification handling, fee calculation, and KYC validation are all unrelated operations. Each belongs in its own visitor, not scattered across the user models.

Visitor also works well when you want clean separation between data and behavior. The models hold data and the visitors define behavior. This makes both easier to understand, easier to test, and easier to maintain independently.

When Not to Use It

Avoid Visitor when the object hierarchy changes frequently. Every time you add a new type, you must update every existing visitor. In a system where new user types appear regularly, this becomes painful quickly.

It's also not helpful when you only have one or two operations. For simple cases, the overhead of creating visitor interfaces, consumer interfaces, and multiple classes is not worth the benefit.

And avoid it when the operations are tightly coupled to the object's internal state in ways that make sense to keep together. Some behavior naturally belongs on the object itself.

Conclusion

The Visitor Design Pattern solves a problem that most developers only recognize after they've already made a mess of it. You have a family of objects with different types and different data. Operations come in one after another. Without a deliberate structure, those operations spread everywhere: into the models, utility classes, and massive switch statements that nobody wants to touch.

Visitor collects each operation into one focused class. The models stay clean and the operations stay isolated. Adding a new operation means creating one new class. The existing code doesn't change.

In the fintech examples above, we have three entirely different concerns: document export, notifications, and fee calculation. All are handled by handled by focused classes, none of which know anything about each other. The user models don't know about PDF or email or fees. The PdfHandler doesn't know about SMS. The MonthlyFeeCalculator doesn't know about push notifications. Each class has exactly one reason to exist and exactly one reason to change.

That s what a well-applied Visitor pattern looks like in practice. Clean, focused, and genuinely extensible.

Happy coding!

The order service handles the checkout, saves the order to its database, and then publishes an order.created event to a message queue so every downstream system can react independently.

This is a common and reasonable design, but it has a reliability problem that's easy to miss until something goes wrong in production.

When a customer places an order and the payment goes through, the application needs to do two things: save the order to the database and publish the event to the queue. These are two separate writes to two separate systems, and there's no way to make them share a single atomic transaction. If the process crashes, the network hiccups, or a deployment rolls out between the two writes, one side commits and the other does not. The order sits confirmed on the customer's screen while the warehouse has no idea it exists.

The transactional outbox pattern is the standard solution to this problem. In this article, we'll build it from scratch in Node.js, using PostgreSQL for the order service database, SQS for the queue, and DynamoDB as the fulfillment service's database. For local development, we'll use floci, a free open-source AWS emulator that runs all three with a single Docker container.

What We'll Cover

• Prerequisites

• The Problem with Two Writes

• The Outbox Pattern

• What We'll Build

• Project Setup

• Database Schema

• The Request Handler

• The Relay Worker

• The Consumer

• Running the Whole Thing

• Going to Production

• Conclusion

Prerequisites

To follow along, you should be comfortable with:

• Node.js and async/await

• Database transactions (BEGIN, COMMIT, ROLLBACK)

• The general concept of a message queue

You don't need prior experience with AWS, SQS, or DynamoDB. We'll be running everything locally.

You will need Node.js 20 or later and Docker installed on your machine.

The Problem with Two Writes

The order service scenario from the intro is one place this problem appears, but the same pattern comes up in many other contexts.

A user registers and the app inserts their account record, then sends a message to trigger the welcome email and the onboarding workflow. A file is uploaded and the API writes the metadata to the database, then publishes a message to kick off a processing worker for virus scanning or thumbnail generation. A payment webhook arrives, the handler records it in the database, then notifies downstream services that the payment is confirmed.

In every case, the application needs two writes to succeed together: one to the database and one to a queue or external system. If the second one is lost, the first one has no way of knowing.

If you want a deeper look at what database transactions actually guarantee and where they stop helping, see Beyond Happy Path Engineering: Databases.

The naïve implementation looks straightforward:

await db.query('INSERT INTO orders (customer_id, amount_cents) VALUES ($1, $2)', [customerId, amountCents]);
await sqs.send(new SendMessageCommand({ QueueUrl: QUEUE_URL, MessageBody: JSON.stringify({ customerId, amountCents }) }));

The database write happens first, then the queue write. Under normal conditions this works fine. The problem is what happens when something goes wrong between the two.

If the process crashes, runs out of memory, or gets killed mid-deployment after the database write but before sqs.send is called, the order record exists in the database but no event is ever published. The warehouse, email service, and fraud checker never find out the order happened. From the customer's perspective the order went through. From every downstream system's perspective it doesn't exist.

The failure can also go the other way. If sqs.send succeeds but the database write is later rolled back due to a constraint violation or an error in a subsequent step, you've published an event for an order that doesn't actually exist. A consumer acting on that event may try to fulfill an order with no corresponding record, or charge a customer for something that was never saved.

There's also a timing window even when both writes eventually succeed. Between the database commit and the successful sqs.send, a consumer that queries the database after receiving the event may not find the order yet, depending on transaction isolation and replication lag. These are two separate systems with no shared transaction boundary, and no amount of careful sequencing fully closes the gap.

These aren't edge cases that only happen under extraordinary circumstances. Deploys restart processes mid-request. Out-of-memory kills happen without warning. Networks drop connections at any point. Any of these can interrupt the two-write sequence, and the result is a system that's silently inconsistent with no error logged and no alert fired.

A variation I've seen a few times that looks safer but is actually worse is wrapping both operations in a database transaction:

// PLEASE DO NOT EVER DO THIS
const client = await pool.connect();
await client.query('BEGIN');
await client.query('INSERT INTO orders (customer_id, amount_cents) VALUES ($1, $2)', [customerId, amountCents]);
await sqs.send(new SendMessageCommand({ QueueUrl: QUEUE_URL, MessageBody: JSON.stringify({ customerId, amountCents }) }));
await client.query('COMMIT');

The intent is to make the two writes feel like a unit, but a database transaction has no authority over SQS. The transaction can only roll back database operations. If sqs.send succeeds and then COMMIT fails, the message is already in the queue and can't be taken back. If the process crashes after COMMIT but before the function returns, the transaction committed and the message was sent, but the caller may retry, potentially inserting a duplicate order.

Beyond the correctness problems, this pattern holds an open database connection and any row locks for the entire duration of the SQS network call. SQS is normally fast, but under load, retries, or a degraded queue, that call can take seconds. Every other request trying to read or write the same rows has to wait. In a busy application, this is a reliable way to exhaust the connection pool and bring down unrelated parts of the service.

The Outbox Pattern

The core idea is to stop treating the queue publish as a second write that happens after the database write, and instead make it part of the same database transaction.

Rather than calling sqs.send directly, the application inserts a row into an outbox table in the same transaction as the business record. A separate relay process reads the outbox table and publishes the messages to SQS. On the other end, a consumer receives the messages and writes to its own data store. In our case that is a fulfillment service writing to DynamoDB, completely separate from the order service's PostgreSQL database.

If the transaction rolls back for any reason, the outbox row disappears with it. There's no orphaned message in the queue because the message was never sent. If the application crashes after committing but before the relay runs, the outbox row is still there with status='pending', and the relay will pick it up on its next iteration.

The only guarantee the pattern relies on is the one the database already provides: atomicity within a single transaction.

The relay worker is responsible for the eventual delivery guarantee. It runs on an interval, selects pending rows, publishes them to SQS, and marks them as sent only after SQS confirms receipt. If the relay crashes mid-run, it will reprocess the same rows on the next iteration, which means SQS may receive some messages more than once.

That's why the consumer needs to be idempotent: it must handle receiving the same message twice without creating duplicate fulfillment records. We'll cover how to implement that when we build the consumer.

This separation of concerns is what makes the pattern practical. The request handler commits one atomic database transaction and returns. The relay handles the network call to SQS asynchronously, at its own pace, with its own retry logic, without holding database connections open or blocking request handling. The consumer is fully decoupled from the order service and owns its own data store.

The diagram below illustrates the flow:

What We'll Build

Now let's see the whole thing in practice. We'll implement a simple order placement API. When a customer sends a request to place an order, the order service saves it to PostgreSQL and inserts a row into the outbox table, all in one atomic transaction. A relay worker wakes up periodically, reads the pending outbox rows, and publishes each one as a message to SQS. A separate fulfillment service receives those messages from the queue and creates fulfillment records in DynamoDB.

By the end, you'll have an HTTP endpoint you can call, and you'll be able to verify that placing an order triggers the creation of a fulfillment record in a completely separate database, owned by a completely separate service, without either service ever talking to the other directly.

You can find the complete working code at github.com/gkoos/article-outbox.

Project Setup

Before you can run any code, you need to get floci running so you have local instances of PostgreSQL, SQS, and DynamoDB. You'll also need Node.js 20 or later and Docker installed.

Start by cloning the repository and installing dependencies:

git clone https://github.com/gkoos/article-outbox
cd article-outbox
npm install

Next, start floci. This command pulls the latest floci image and starts a Docker container that exposes a local AWS API endpoint (make sure Docker is running):

npm run floci:start

On Linux and macOS, this just works. On Windows with Docker Desktop, you need to edit the floci:start script in your package.json to change the Docker socket mount from /var/run/docker.sock to //var/run/docker.sock.

The floci container is now listening on port 4566 and can spin up RDS (PostgreSQL), SQS, and DynamoDB instances on demand.

Now provision the AWS resources with a single setup command:

npm run setup

This script creates an RDS PostgreSQL database instance, an SQS queue named orders, and a DynamoDB table named fulfillments. It waits for RDS to become available and then writes a .env file with the correct connection details. The environment variables PG_PORT, SQS_QUEUE_URL, and DYNAMODB_TABLE_NAME now point to the local emulated services.

Finally, create the PostgreSQL tables:

npm run migrate

This creates the orders table and the outbox table in PostgreSQL. You now have a fully functional local environment ready to build against.

Database Schema

The two tables are simple. orders holds the business records: each order has a customer ID, an amount in cents, and a timestamp. The outbox table is the heart of the pattern: it's where the application writes the event that needs to be published.

CREATE TABLE orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  customer_id TEXT NOT NULL,
  amount_cents INTEGER NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE outbox (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  created_at TIMESTAMPTZ DEFAULT now(),
  sent_at TIMESTAMPTZ
);

CREATE INDEX ON outbox (status, created_at) WHERE status = 'pending';

The orders table needs nothing special. The outbox table stores the event metadata: what type of event it is (event_type), what data it contains (payload as JSON), and whether it has been sent yet (status).

The status starts as pending. When the relay publishes it to SQS, it will mark it as sent and record the timestamp. The index on (status, created_at) WHERE status = 'pending' lets the relay quickly find the next batch of unsent events without scanning the entire table.

The Request Handler

This is where the pattern starts. The request handler receives an HTTP POST, inserts an order into the database, inserts a corresponding row into the outbox table, and commits everything in a single atomic transaction. The key insight is that neither write succeeds unless both succeed.

const client = await pool.connect();
try {
  await client.query('BEGIN');

  // Insert the order record
  const { rows } = await client.query(
    'INSERT INTO orders (customer_id, amount_cents) VALUES ($1, $2) RETURNING *',
    [customerId, amountCents]
  );
  const order = rows[0];

  // Insert the outbox record in the same transaction
  await client.query(
    `INSERT INTO outbox (event_type, payload)
     VALUES ($1, $2)`,
    ['order.created', JSON.stringify({ orderId: order.id, customerId: order.customer_id, amountCents: order.amount_cents, createdAt: order.created_at })],
  );

  await client.query('COMMIT');
  res.status(201).json(order);
} catch (err) {
  await client.query('ROLLBACK');
  next(err);
} finally {
  client.release();
}

The handler gets customerId and amountCents from the request body, starts an explicit transaction with BEGIN, and inserts the order. Then it inserts an outbox row with the order data as the payload.

Everything commits atomically. If anything fails, everything rolls back and the client gets an error. If the process crashes between the commit and the response, the client won't get a 201, but the order and the outbox row are still safely committed to the database and the relay will eventually pick it up. The handler doesn't call SQS at all. That is the relay's job.

The Relay Worker

The relay worker is a separate process that polls the outbox table every second and publishes pending rows to SQS. It runs independently of the HTTP server and has no shared state with it.

async function relay() {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');

    const { rows } = await client.query(`
      SELECT *
      FROM outbox
      WHERE status = 'pending'
      ORDER BY created_at
      LIMIT 10
      FOR UPDATE SKIP LOCKED -- prevents multiple relays from processing the same rows
    `);

    for (const row of rows) {
      await sqsClient.send(new SendMessageCommand({
        QueueUrl: QUEUE_URL,
        MessageBody: JSON.stringify(row.payload),
        MessageAttributes: {
          EventType: { DataType: 'String', StringValue: row.event_type },
        },
      }));

      await client.query(
        `UPDATE outbox SET status = 'sent', sent_at = now() WHERE id = $1`,
        [row.id],
      );
    }

    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    console.error('Relay error:', err.message);
  } finally {
    client.release();
  }
}

setInterval(relay, 1000);

FOR UPDATE SKIP LOCKED is the key to running multiple relay instances safely: when a relay picks up a batch of rows, it locks them. Any other relay instance trying to select the same rows will skip them and move to the next available ones, so you never get two relays publishing the same message from the same run.

The relay marks each row as sent only after sqsClient.send returns. If the relay crashes after sending to SQS but before updating the row, the row stays pending and the relay will resend it on the next iteration.

Note that the UPDATE happens inside the same transaction as the SELECT FOR UPDATE, so if the relay crashes mid-batch, the entire batch rolls back and all rows in it will be retried, including any that were already successfully sent to SQS.

The at-least-once delivery guarantee applies at the batch level, not the individual row level. You can read about this problem in Beyond Happy Path Engineering: the Network: when a response is lost, the caller can't know whether the operation succeeded, so it retries, and the receiver may see the same request twice. This means the consumer may see the same message more than once, which is why idempotency matters on the consumer side.

The Consumer

The consumer is a completely separate service. It knows nothing about the order service's PostgreSQL database. Its only input is the SQS queue, and its only output is the DynamoDB fulfillments table. This is the point of the pattern: the two services are decoupled by the queue, and each owns its own data store.

As we saw earlier, because SQS delivers at least once (meaning a message might be delivered more than once), the consumer must be idempotent. The PutItem call uses a ConditionExpression that makes the write a no-op if a fulfillment record for that order already exists, so redelivered messages are handled safely.

async function consume() {
  const { Messages } = await sqsClient.send(new ReceiveMessageCommand({
    QueueUrl:              QUEUE_URL,
    WaitTimeSeconds:       20,   // long-poll: wait up to 20s for messages
    MaxNumberOfMessages:   10,
    MessageAttributeNames: ['All'],
  }));

  for (const msg of Messages ?? []) {
    const event = JSON.parse(msg.Body);

    try {
      await dynamoClient.send(new PutItemCommand({
        TableName: 'fulfillments',
        Item: {
          orderId:     { S: event.orderId },
          customerId:  { S: event.customerId },
          amountCents: { N: String(event.amountCents) },
          status:      { S: 'received' },
          createdAt:   { S: new Date().toISOString() },
        },
        ConditionExpression: 'attribute_not_exists(orderId)', // idempotency check
      }));
    } catch (err) {
      if (err.name !== 'ConditionalCheckFailedException') throw err;
      // already processed, safe to continue
    }

    // delete the message only after the write succeeds (or was already done)
    await sqsClient.send(new DeleteMessageCommand({
      QueueUrl:      QUEUE_URL,
      ReceiptHandle: msg.ReceiptHandle,
    }));
  }
}

ConditionExpression: 'attribute_not_exists(orderId)' tells DynamoDB to reject the write if a record with that orderId already exists. When that happens, DynamoDB throws a ConditionalCheckFailedException. The consumer catches that specific error and ignores it, then deletes the message from the queue and moves on. Any other error is rethrown and the message stays in the queue to be retried.

The DeleteMessage call happens after the DynamoDB write, not before. If the process crashes between the write and the delete, SQS will redeliver the message and the condition check will handle it. If the process crashes before the write, the message stays in the queue and will be processed normally on the next delivery.

Running the Whole Thing

With floci running and the resources provisioned, open three terminal tabs and start each process:

node src/server.js    # the order API on port 3000
node src/relay.js     # the outbox relay
node src/consumer.js  # the fulfillment consumer

Now place an order:

curl -X POST localhost:3000/orders \
  -H 'Content-Type: application/json' \
  -d '{"customerId":"c1","amountCents":4999}'

You should get back a 201 with the new order record:

{"id":"1768d35b-083d-45f1-adb5-4063d8d7fcab","customer_id":"c1","amount_cents":4999,"created_at":"2026-07-30T20:27:10.628Z"}

Within a second the relay will pick up the outbox row and publish it to SQS. The consumer will receive the message and write a fulfillment record to DynamoDB. The repo includes a convenience script to verify this:

npm run check

You should see a fulfillment record with the orderId from the order you just placed:

{
  orderId: 'c335640e-bc4a-47e4-afed-484c95fbd6d3',
  customerId: 'c1',
  amountCents: '4999',
  status: 'received',
  createdAt: '2026-07-30T19:02:54.929Z'
}

Going to Production

Because the local setup uses floci to emulate AWS, switching to real AWS requires no code changes at all. The AWS SDK reads the endpoint from AWS_ENDPOINT_URL in the environment. In production, you simply don't set that variable and the SDK talks to real AWS using the credentials and region from the standard environment variables (AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or an IAM role if you are running on EC2 or ECS).

Running multiple relay instances is safe out of the box because of FOR UPDATE SKIP LOCKED. You can scale the relay horizontally and each instance will pick up a different set of rows without duplicating messages.

One thing worth adding before going to production is handling permanent failures in the relay. Right now the relay only uses pending and sent. You should add a failed status and a retry counter: after a row has failed N times, mark it failed and stop retrying it. Then configure a dead-letter queue on the orders SQS queue as well, so that messages the consumer can't process after the maximum number of retries land somewhere you can inspect rather than disappearing silently.

For high-throughput systems where polling latency matters, change data capture (CDC) is a common alternative to the polling relay. Tools like Debezium read directly from the PostgreSQL write-ahead log and publish changes to Kafka or SQS without any polling delay. The outbox table and the consumer stay exactly the same, only the relay is replaced.

This is a bigger operational commitment than a polling worker, so polling is the right starting point for most systems.

Conclusion

The dual-write problem is easy to overlook because the naïve implementation works correctly most of the time. It only fails in the gaps between two separate system writes, and those gaps only become visible when something goes wrong at exactly the wrong moment. By the time you notice it in production, data is already inconsistent and there is no clean way to recover.

The transactional outbox pattern closes that gap at the database level. The outbox row is part of the same atomic commit as the business record, so the two are always in sync. The relay handles the network call to SQS independently, with its own retry logic, without touching the request lifecycle. The consumer handles at-least-once delivery with a single condition check on the write.

Each piece is simple on its own, and together they give you reliable, decoupled event delivery without distributed transactions.

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!

This is where the Saga Pattern comes in. Instead of using distributed transactions, a saga coordinates a sequence of local transactions and runs compensation actions when something goes wrong.

In this article, we'll build an orchestrated Saga Pattern using NestJS, gRPC, PostgreSQL, and Sequelize. You'll learn how to coordinate work across services, implement compensation-based rollbacks, handle idempotency, and track workflow progress in a production-style microservice architecture.

Table of Contents

• Prerequisites

• 1. Introduction

• 2. The Problem in One Picture

• 3. Why You Need a Saga

• 4. Choreography vs Orchestration

  • Choreography

  • Orchestration

• 5. The Example Project

• 6. Architecture

• 7. The Saga Flow, Step by Step

• 8. The State Machine

• 9. Implementing the Orchestrator

  • Creating the Saga Record

  • The Main Loop

  • A Single Step in Detail

  • Habits Worth Copying

• 10. Implementing the Participant

• 11. Rollback (Compensation)

  • On the Orchestrator Side

  • On the Participant Side

  • Rules of a Good Compensation

  • What Happens if the Compensation Itself Fails?

• 12. Tracking, Idempotency and Observability

  • Orchestrator Side — agency_onboarding_sagas

  • Participant Side — agency_provision_records

  • Observability for Free

• 13. Testing a Saga

• 14. When NOT to Use a Saga

• 15. Trade-offs and Lessons Learned

• 16. Conclusion

Prerequisites

This article assumes you're already familiar with some backend development concepts. You don't need prior experience with the Saga Pattern, but you should be comfortable with:

• JavaScript, TypeScript, Node.js

• NestJS fundamentals (controllers, services, dependency injection)

• Basic PostgreSQL concepts

• Database transactions

• Docker (recommended for local development)

• Microservice architecture basics

• gRPC fundamentals (helpful but not required)

If you've already built a few backend services with NestJS and PostgreSQL, you'll have everything you need to follow this guide.

1. Introduction

A saga is a sequence of local transactions across multiple services. Each step commits its own database transaction. If a later step fails, the saga runs compensating transactions to semantically undo the work already committed.

The pattern was first described by Hector Garcia-Molina and Kenneth Salem in 1987 for long-lived database transactions. It was rediscovered a decade ago when companies started splitting monoliths into microservices and realised that the database transaction — the single most powerful tool in a backend developer's belt — stops working at the service boundary.

This article walks through an orchestrated saga in Node.js (NestJS + gRPC) for onboarding an agency, where two services must agree on a single business outcome:

• agency-service — owns the agency record.

• auth-service — owns the organization, user and role.

If either side fails, the system must end up as if nothing ever happened. No half-created users, orphan organizations, or 3am Slack threads.

2. The Problem in One Picture

Here's the bug a saga is built to prevent:

Step 1: auth-service     ✅ creates Organization #42
Step 2: auth-service     ✅ creates User #99
Step 3: agency-service   ❌ fails (DB down, validation, network blip…)

Result without a saga:
   Organization #42 and User #99 still exist.
   There is no Agency row.
   The user can log in but has nothing to manage.
   Support gets a ticket. Engineer writes a one-off SQL cleanup.
   Repeat every week.

The saga's job is to detect that step 3 failed and explicitly delete Organization #42 and User #99, so the system is consistent again — even though those rows live in a different service's database.

3. Why You Need a Saga

In a monolith, you wrap everything in one DB transaction and let the database handle atomicity:

await sequelize.transaction(async (tx) => {
  await Organization.create({...}, { transaction: tx });
  await User.create({...}, { transaction: tx });
  await Agency.create({...}, { transaction: tx });
});

In microservices, each service has its own database. You can't wrap two services in one ACID transaction. The classic alternatives all have problems:

The saga gives you eventual consistency with a clear, auditable rollback path — without distributed locks.

4. Choreography vs Orchestration

There are two ways to implement a saga:

Choreography

With Choreography, services emit events and other services subscribe and react.

auth-service → emits "UserCreated"
agency-service → listens, creates agency, emits "AgencyCreated"
billing-service → listens, creates subscription…

It's simple at first, but brittle later. The workflow is scattered across N codebases. Nobody owns it. Debugging means tracing events across logs. Adding a step means changing several services.

Orchestration

With Orchestration, one service is the conductor. It calls the others in order.

orchestrator:
   1. authClient.provisionAccount(...)
   2. agencyRepo.create(...)
   3. authClient.sendWelcomeEmail(...)

There's slightly more coupling here (the orchestrator imports clients), but the entire workflow lives in one file. Onboarding new engineers becomes a one-hour task. Adding a step is a single PR.

Pick orchestration unless you have a strong reason not to. This article — and the reference implementation — uses orchestration.

5. The Example Project

Our goal here is to create an Agency in the system. This is the moment a new B2B customer signs up.

It requires two services to agree on a single outcome:

auth-service must create:

• an Organization row (the tenant)

• a User row (the agency admin who will log in)

• a UserRole row linking the user to the AGENCY_ADMIN role

agency-service must create:

• an Agency row containing business details (size, registration number, website, branches…), linked to the user/organization above

These rows have foreign-key relationships within a service, but not across services — Postgres can't enforce that the user in auth's DB matches the authUserId in agency's DB. The application has to do it.

auth-service DB                    agency-service DB
─────────────────                  ─────────────────
organizations  ◄────────┐
   │                    │
   │ (1:1)              │   foreign reference (no FK)
   ▼                    │           agencies
users  ──────► user_roles                     ─ authUserId
                                              └ authOrganizationId

If step 2 fails after step 1 succeeded, we end up with a user who can authenticate but has no agency — the exact bug from 2. That's what the saga prevents.

6. Architecture

                     ┌───────────────────────────────┐
                     │        API Gateway            │
                     └──────────────┬────────────────┘
                                    │ HTTP
                                    ▼
   ┌──────────────────────────────────────────────────┐
   │              agency-service                      │
   │   ┌─────────────────────────────────────────┐    │
   │   │   AgencyOnboardingOrchestrator (SAGA)   │    │
   │   └───────────────┬─────────────────────────┘    │
   │                   │ writes state                 │
   │                   ▼                              │
   │      agency_onboarding_sagas  (Postgres)         │
   └───────────────┬─────────────────┬────────────────┘
                   │ gRPC            │ gRPC
       provisionAgencyAccount   compensateAgencyAccount
                   │                 │
                   ▼                 ▼
   ┌──────────────────────────────────────────────────┐
   │              auth-service                        │
   │   AgencyProvisioningService  (Participant)       │
   │                                                  │
   │   organizations · users · user_roles             │
   │   agency_provision_records  ← idempotency log    │
   └──────────────────────────────────────────────────┘

Three components do all the work:

1. AgencyOnboardingOrchestrator in agency-service — drives the workflow.

2. agency_onboarding_sagas table in agency-service — the durable log of the saga's progress.

3. AgencyProvisioningService in auth-service — exposes a do operation (provisionAgencyAccount) and an undo operation (compensateAgencyAccount). It's backed by its own agency_provision_records idempotency table.

The orchestrator never reaches into the auth database directly. The boundary is enforced by gRPC.

7. The Saga Flow, Step by Step

This sequence diagram shows the complete lifecycle of the onboarding saga. The workflow begins when a client sends a request to create a new agency. The orchestrator first creates a saga record in its database and marks it as STARTED, giving it a durable record of the workflow before any business action takes place.

At a high level, the orchestrator begins by creating a saga record and then asks auth-service to provision the organization, user, and role. Once that succeeds, the orchestrator creates the agency record in its own database.

If every step succeeds, the saga reaches the COMPLETED state. If the agency creation fails after the auth resources have already been created, the orchestrator triggers a compensation step that instructs auth-service to remove everything it previously provisioned.

The key idea is that each service commits its own local transaction, while the saga coordinates the overall business workflow and ensures the system can return to a consistent state when failures occur.

sequenceDiagram
    autonumber
    participant C as Client
    participant AS as agency-service<br/>Orchestrator
    participant DB1 as saga store
    participant AU as auth-service
    participant DB2 as auth DB

    C->>AS: POST /agencies
    AS->>DB1: INSERT saga (STARTED, payload)
    AS->>AU: provisionAgencyAccount(sagaId, …)
    AU->>DB2: BEGIN TX
    AU->>DB2: create org + user + role + provision_record
    AU->>DB2: COMMIT
    AU-->>AS: { userId, organizationId, roleId }
    AS->>DB1: UPDATE saga (AUTH_PROVISIONED)
    AS->>AS: create Agency row
    alt Agency row OK
        AS->>DB1: UPDATE saga (AGENCY_CREATED → COMPLETED)
        AS->>AU: sendAgencyWelcomeEmail (non-critical)
        AS-->>C: 200 OK + sagaId
    else Agency row fails
        AS->>DB1: UPDATE saga (COMPENSATING)
        AS->>AU: compensateAgencyAccount(sagaId)
        AU->>DB2: BEGIN TX
        AU->>DB2: delete role + token + user + org + record
        AU->>DB2: COMMIT
        AS->>DB1: UPDATE saga (COMPENSATED → FAILED)
        AS-->>C: 5xx + error code
    end

Read this once top to bottom and you'll understand the entire onboarding workflow. That's the value of orchestration — the sequence diagram is the architecture.

8. The State Machine

Every transition is written to agency_onboarding_sagas before the next step runs. That is what makes the saga observable and recoverable.

export enum AgencyOnboardingSagaStatus {
  STARTED            = 'STARTED',            // Row exists, no side effects yet
  AUTH_PROVISIONED   = 'AUTH_PROVISIONED',   // Auth side committed
  AGENCY_CREATED     = 'AGENCY_CREATED',     // Agency row committed
  COMPLETED          = 'COMPLETED',          // Happy-path terminal state
  COMPENSATING       = 'COMPENSATING',       // Rollback in progress
  COMPENSATED        = 'COMPENSATED',        // Rollback finished
  FAILED             = 'FAILED',             // Terminal failure (with or without compensation)
}

Why so many states? Because "what went wrong here?" is a question someone will ask at 2am. A saga that only stores success | failure is useless for forensics.

                ┌── auth fails ──────────► FAILED  (nothing to compensate)
                │
STARTED ──► AUTH_PROVISIONED ──► AGENCY_CREATED ──► COMPLETED  (happy path)
                                       │
                       agency fails ───┘
                                       ▼
                                COMPENSATING
                                       │
                                       ▼
                                COMPENSATED ──► FAILED  (consistent again)

The “point of no return” is AUTH_PROVISIONED. Before it, we can fail fast — there's nothing to undo. After it, every failure path must go through compensation.

9. Implementing the Orchestrator

The orchestrator is the only place that knows the workflow. Each step is a private method, and each step persists its result before returning.

Creating the Saga Record

// agency-onboarding.saga.repository.ts
async createSaga(payload: CreateAgencyOrchestrationInput) {
  return this.sagaModel.create({
    sagaId: randomUUID(),                          // correlation id for everything
    status: AgencyOnboardingSagaStatus.STARTED,
    currentStep: 'STARTED',
    payload,                                       // full input snapshot for replay
  });
}

The sagaId is a UUID generated once and propagated to every downstream call. It's the single identifier that ties the saga log on the orchestrator side to the provision record on the participant side.

The Main Loop

// agency-onboarding.orchestrator.ts (trimmed for the article)
async execute(input: CreateAgencyOrchestrationInput) {
  const saga = await this.sagaRepository.createSaga(input); // STARTED

  try {
    // Step 1 — auth-service work
    const authStep = await this.provisionAuth(saga, input);
    if (!authStep.ok) {
      await this.markFailed(saga, authStep.failure); // nothing to compensate
      return authStep.failure;
    }

    // Step 2 — agency-service work
    let activeSaga = authStep.saga; // status: AUTH_PROVISIONED
    try {
      activeSaga = await this.createAgencyRow(activeSaga, input, authStep.authIds);
    } catch (err) {
      // The expensive case: undo what auth-service did
      await this.compensateAuth(activeSaga, 'SAGA_FAILED');
      const failure = mapSagaFailure(err.message, 'SAGA_FAILED', 'CREATE_AGENCY');
      await this.markFailed(activeSaga, failure);
      return failure;
    }

    // Step 3 — mark done and run non-critical side effects
    activeSaga = await this.sagaRepository.updateSaga(activeSaga, {
      status: AgencyOnboardingSagaStatus.COMPLETED,
    });
    await this.sendWelcomeEmail(input, activeSaga); // best-effort

    return mapSagaSuccess(activeSaga, await this.agencyModel.findByPk(activeSaga.agencyId!));
  } catch (error) {
    // Defensive catch-all (lost DB connection, unexpected throw)
    await this.compensateAuth(saga, 'SAGA_FAILED');
    const failure = mapSagaFailure(error.message, 'SAGA_FAILED', 'SAGA');
    await this.markFailed(saga, failure);
    return failure;
  }
}

A Single Step in Detail

private async provisionAuth(saga: AgencyOnboardingSaga, input: ...) {
  this.logger.log(`[${saga.sagaId}] PROVISION_AUTH`);

  const auth = await firstValueFrom(
    this.authClient.provisionAgencyAccount({
      sagaId: saga.sagaId,                  // <-- correlation
      organizationName: input.agencyName.trim(),
      email: input.email.trim().toLowerCase(),
      // …
    }),
  );

  if (!auth.status || !auth.data) {
    return { ok: false, failure: mapAuthProvisionFailure(auth) };
  }

  // Persist the IDs we will need if we have to compensate later
  const updated = await this.sagaRepository.updateSaga(saga, {
    authOrganizationId: Number(auth.data.organizationId),
    authUserId: Number(auth.data.userId),
    authUserRoleId: Number(auth.data.userRoleId),
    status: AgencyOnboardingSagaStatus.AUTH_PROVISIONED,
  });

  return { ok: true, saga: updated, authIds: auth.data };
}

The line that does most of the work is the updateSaga call. It stores the foreign IDs returned by auth-service on the saga row, so even if the orchestrator process crashes and restarts, a recovery job can read that row and still know what to compensate.

Habits Worth Copying

• Persist after every successful step, including the IDs you'll need to undo it.

• Distinguish critical vs non-critical steps. Welcome emails, audit logs and analytics events are not worth rolling a saga back for. They're best-effort.

• One log line per transition, prefixed with [${sagaId}]. Grep is your debugger.

10. Implementing the Participant

The participant (auth-service) wraps all of its own work in a local DB transaction. Inside that boundary it's still ACID — the saga only handles the cross-service problem.

// agency-provisioning.service.ts (trimmed)
async provisionAgencyAccount(req: ProvisionAgencyAccountInput) {

  // 1. Idempotency — return the previous result if this sagaId already provisioned.
  const existing = await this.provisionRecordModel.findOne({
    where: { sagaId: req.sagaId },
  });
  if (existing) {
    return serviceSuccess('Agency admin already onboarded', {
      userId: Number(existing.userId),
      organizationId: Number(existing.organizationId),
      userRoleId: Number(existing.roleId),
    });
  }

  // 2. Domain validation BEFORE the transaction (fail fast).
  if (await this.emailExists(req.email)) {
    return serviceFailure('Email already exists', { code: 'EMAIL_EXISTS' });
  }
  if (await this.organizationExists(req.organizationName)) {
    return serviceFailure('Organization already exists', { code: 'ORGANIZATION_EXISTS' });
  }

  // 3. The actual work — atomic at the auth-service boundary.
  return withSequelizeTransaction(this.sequelize, async (tx) => {
    const org = await this.organizationModel.create({ ... }, { transaction: tx });
    const user = await this.userModel.create({ ..., organizationId: org.id }, { transaction: tx });
    await this.userRoleModel.create({ userId: user.id, roleId: agencyAdminRole.id }, { transaction: tx });

    // The audit record that makes compensation possible later.
    await this.provisionRecordModel.create(
      { sagaId: req.sagaId, organizationId: org.id, userId: user.id, roleId: agencyAdminRole.id },
      { transaction: tx },
    );

    return serviceSuccess('Provisioned', {
      userId: user.id, organizationId: org.id, userRoleId: agencyAdminRole.id,
    });
  });
}

Three things make this method "saga-safe":

1. Idempotency check first: If the orchestrator retries (network blip, gRPC timeout), the second call is a no-op that returns the same IDs. No duplicate users.

2. Validation outside the transaction: Cheap reads first, expensive writes second.

3. One transaction wraps every write: If any insert fails, the whole thing rolls back automatically. The orchestrator sees a clean failure response and knows nothing was persisted.

The agency_provision_records table is the single most important piece of the participant. It's both the idempotency key and the compensation lookup — keyed by the same sagaId the orchestrator uses.

11. Rollback (Compensation)

Compensation is just another gRPC call. The orchestrator sends the sagaId and the IDs it remembers. The participant deletes everything it created, in reverse dependency order, inside its own DB transaction.

On the Orchestrator Side

private async compensateAuth(saga: AgencyOnboardingSaga, errorCode?: string) {
  if (!saga.authUserId && !saga.authOrganizationId) {
    // Nothing was provisioned — nothing to compensate.
    return;
  }

  // Mark the saga as compensating BEFORE the call, so the row is consistent
  // even if the compensating RPC times out.
  await this.sagaRepository.updateSaga(saga, {
    status: AgencyOnboardingSagaStatus.COMPENSATING,
    currentStep: 'COMPENSATING',
    errorCode,
  });

  try {
    const rollback = await firstValueFrom(this.authClient.compensateAgencyAccount({
      sagaId: saga.sagaId,
      organizationId: saga.authOrganizationId,
      userId: saga.authUserId,
    }));
    if (!rollback.status) {
      this.logger.error(`[\({saga.sagaId}] Auth compensation returned failure: \){rollback.message}`);
    }
  } catch (err) {
    this.logger.error(`[\({saga.sagaId}] Auth compensation RPC failed: \){err.message}`);
  }

  await this.sagaRepository.updateSaga(saga, {
    status: AgencyOnboardingSagaStatus.COMPENSATED,
    currentStep: 'COMPENSATED',
  });
}

On the Participant Side

private async rollbackProvisionedAuth(req, sagaId: string, tx: Transaction) {
  // Use the saga log as the source of truth — even if the caller forgot IDs.
  const record = await this.provisionRecordModel.findOne({
    where: { sagaId }, transaction: tx,
  });
  const userId         = req.userId         ?? record?.userId;
  const organizationId = req.organizationId ?? record?.organizationId;

  if (userId) {
    const user = await this.userModel.findByPk(userId, { transaction: tx, attributes: ['email'] });
    await this.userRoleModel.destroy({ where: { userId }, transaction: tx });
    if (user?.email) {
      await this.passwordResetTokenModel.destroy({ where: { email: user.email }, transaction: tx });
    }
    await this.userModel.destroy({ where: { id: userId }, transaction: tx });
  }
  if (organizationId) {
    await this.organizationModel.destroy({ where: { id: organizationId }, transaction: tx });
  }
  if (record) {
    await record.destroy({ transaction: tx });
  }
}

Rules of a Good Compensation

1. Reverse the order of creation: Children first (user_roles, tokens), then parents (users, organizations). The same rule you follow for DROP TABLE statements.

2. Be idempotent: Receiving the same sagaId twice must be safe — every destroy is a no-op if the row is already gone.

3. Use the saga log, not just the request: If the caller forgets an ID or sends a partial payload, look it up by sagaId. Defence in depth.

4. Wrap it in a local transaction: The rollback must itself be atomic — half-undone is worse than not-undone.

5. Always close the loop on the orchestrator side: Mark COMPENSATED even if the RPC failed. The failure should also be surfaced (log, metric, alert). A stuck COMPENSATING row is an operational landmine.

What Happens if the Compensation Itself Fails?

This is the worst case in any saga design. There are three reasonable strategies:

First, you can retry with exponential backoff. This works for transient failures (network, deadlocks).

Second, you can dead-letter the saga — write it to a "needs human attention" queue and alert.

Third, you can expose a manual rollback endpoint. This reference implementation does that via RollbackAgencyOnboarding gRPC, so an operator can replay compensation with the same sagaId.

A production system should combine all three. The pattern doesn't decide for you. You decide based on your business risk.

12. Tracking, Idempotency and Observability

Two tables, both keyed by the same UUID sagaId, give you full traceability across services.

Orchestrator Side — agency_onboarding_sagas

A real row in COMPLETED state looks roughly like this:

{
  "sagaId": "0a4f3e2c-7b11-4f8d-9a2c-90b6f5f5b8a1",
  "status": "COMPLETED",
  "currentStep": "COMPLETED",
  "agencyId": 17,
  "authOrganizationId": 42,
  "authUserId": 99,
  "authUserRoleId": 3,
  "errorCode": null,
  "errorMessage": null,
  "payload": { "agencyName": "Acme Education", "email": "admin@acme.com", "...": "..." },
  "createdAt": "2026-05-22T10:14:32.118Z",
  "updatedAt": "2026-05-22T10:14:33.412Z"
}

Participant Side — agency_provision_records

Observability for Free

Because every log line is prefixed with [${sagaId}], a single grep across both services gives the full timeline:

[0a4f3e2c…] PROVISION_AUTH                  agency-service
[0a4f3e2c…] provisionAgencyAccount: ok      auth-service
[0a4f3e2c…] CREATE_AGENCY                   agency-service
[0a4f3e2c…] Agency step failed: ...         agency-service
[0a4f3e2c…] Auth compensation completed     auth-service

In a structured-logging setup (Loki, Elasticsearch, Datadog) this becomes a one-click filter. The sagaId is your distributed trace.

13. Testing a Saga

A saga is just a state machine, so the test matrix is finite and small. Cover at least these cases:

Two practical tips for testing:

First, mock the gRPC client at the orchestrator level, not the network. You want to assert that compensateAgencyAccount was called with the right sagaId, not that bytes hit a socket.

Second, spin up a real Postgres in integration tests (Testcontainers, or a Docker Compose postgres service). The saga state machine is too easy to "test" against a mock and too easy to break against a real DB.

14. When NOT to Use a Saga

Sagas are not free. Skip them when:

• One service does all the writes. Use a regular DB transaction. Don't reinvent the wheel.

• The workflow is read-only or analytical. No rollback semantics exist for a SELECT.

• The "rollback" is impossible. You sent a real email. You charged a credit card and the gateway doesn't support refunds. In those cases, design forward: send an apology email, queue a manual refund. Sagas can't unsend physical actions.

• You don't actually have multiple services yet. A saga in a monolith is over-engineering. Wait until the service boundary is real.

A saga adds a state table, a compensation method per step, and an operational habit of grepping by sagaId. That cost is worth paying when the alternative is orphaned data — and not before.

15. Trade-offs and Lessons Learned

Things that worked well in this design:

• Synchronous orchestration is easier to debug than choreography. A new engineer reads one file and understands the whole flow.

• Idempotency at the participant is non-negotiable. Retries from the orchestrator must be safe. Build it in from day one — retro-fitting is painful.

• The saga table replaces tribal knowledge. Ops can answer "what happened to this signup?" with a single SQL query. The payload JSONB is gold during incidents.

• sagaId as the trace key plays nicely with OpenTelemetry / Datadog / Loki — no extra infra to set up.

Things to know before copying this pattern:

• A failing compensation is the worst case. If compensateAgencyAccount itself errors, you have inconsistent state. Plan for retries + dead-letter + a manual rollback endpoint from the start.

• Non-critical steps must be marked explicitly. Here, the welcome email is allowed to fail without rolling back the agency. Don't accidentally compensate over a flaky SMTP provider.

• Sagas aren't a replacement for local transactions. Inside each service, still use a real DB transaction. The saga only handles the cross-service seam.

• Synchronous gRPC is simple but couples availability. If auth-service is down, agency creation fails. Swap the gRPC calls for a durable message bus (RabbitMQ / Kafka) and treat each step as a command + reply when you need higher resilience.

• The orchestrator becomes a critical service. Treat its uptime accordingly — monitor saga durations, alert on stuck COMPENSATING rows, and run more than one replica.

16. Conclusion

The saga pattern isn't magic. It's a disciplined version of what experienced engineers already do by hand: commit locally, record what you did, and know how to undo it.

In Node.js with NestJS, you only need three ingredients:

1. A state table to track the saga.

2. An orchestrator that drives the workflow and writes that state.

3. A participant that exposes a do and an undo operation, both idempotent and keyed by sagaId.

Get those three right and your microservices can offer the same "all-or-nothing" feel as a monolithic transaction — without the operational pain of distributed locks.

Start simple, use orchestration, make every step idempotent, persist before you call, and always know how to undo. That's the whole pattern.

That's the command pattern. Instead of calling a method directly, you package the call – the action, its target, and any arguments – into an object. That object can be stored, passed around, executed later, or undone.

In this tutorial, you'll learn what the command pattern is and how to implement it in Python with a practical text editor example that supports undo.

You can find the code for this tutorial on GitHub.

Prerequisites

Before we start, make sure you have:

• Python 3.10 or higher installed

• Basic understanding of Python classes and methods

• Familiarity with object-oriented programming (OOP) concepts

Let's get started!

Table of Contents

• What Is the Command Pattern?

• Setting Up the Receiver

• Defining Commands

• The Invoker: Running and Undoing Commands

• Putting It All Together

• When to Use the Command Pattern

What Is the Command Pattern?

The command pattern is a behavioral design pattern that encapsulates a request as an object. This lets you:

• Parameterize callers with different operations

• Queue or schedule operations for later execution

• Support undo/redo by keeping a history of executed commands

The pattern has four key participants:

• Command: an interface with an execute() method (and optionally undo())

• Concrete Command: implements execute() and undo() for a specific action

• Receiver: the object that actually does the work (for example, a document)

• Invoker: triggers commands and manages history

Think of a restaurant. The customer (client) tells the waiter (invoker) what they want. The waiter writes it on a ticket (command) and hands it to the kitchen (receiver). The waiter doesn't cook – they only manage tickets. If you change your mind, the waiter can cancel the ticket before it reaches the kitchen.

Setting Up the Receiver

We'll build a simple document editor. The receiver here is the Document class. It knows how to insert and delete text, but it has no idea who's calling it or why.

class Document:
    def __init__(self):
        self.content = ""

    def insert(self, text: str, position: int) -> None:
        self.content = (
            self.content[:position] + text + self.content[position:]
        )

    def delete(self, position: int, length: int) -> None:
        self.content = (
            self.content[:position] + self.content[position + length:]
        )

    def show(self) -> None:
        print(f'Document: "{self.content}"')

insert places text at a given position. delete removes length characters from a given position. Both are plain methods with no history or awareness of commands. And that's intentional.

Defining Commands

Now let's define a base Command interface using an abstract class:

from abc import ABC, abstractmethod

class Command(ABC):
    @abstractmethod
    def execute(self) -> None:
        pass

    @abstractmethod
    def undo(self) -> None:
        pass

Any concrete command must implement both execute and undo. This is what makes a full history possible.

InsertCommand

InsertCommand stores the text and position at creation time:

class InsertCommand(Command):
    def __init__(self, document: Document, text: str, position: int):
        self.document = document
        self.text = text
        self.position = position

    def execute(self) -> None:
        self.document.insert(self.text, self.position)

    def undo(self) -> None:
        self.document.delete(self.position, len(self.text))

When execute() is called, it inserts the text. When undo() is called, it deletes exactly what was inserted. Notice that undo is the inverse of execute – this is the key design requirement.

DeleteCommand

Now let's code the DeleteCommand:

class DeleteCommand(Command):
    def __init__(self, document: Document, position: int, length: int):
        self.document = document
        self.position = position
        self.length = length
        self._deleted_text = ""  # stored on execute, used on undo

    def execute(self) -> None:
        self._deleted_text = self.document.content[
            self.position : self.position + self.length
        ]
        self.document.delete(self.position, self.length)

    def undo(self) -> None:
        self.document.insert(self._deleted_text, self.position)

DeleteCommand has one important detail: it captures the deleted text during execute(), not at creation time. This is because we don't know what text is at that position until the command actually runs. Without this, undo() wouldn't know what to restore.

The Invoker: Running and Undoing Commands

The invoker is the object that executes commands and keeps a history stack. It has no idea what a document is or how text editing works. It just manages command objects.

class EditorInvoker:
    def __init__(self):
        self._history: list[Command] = []

    def run(self, command: Command) -> None:
        command.execute()
        self._history.append(command)

    def undo(self) -> None:
        if not self._history:
            print("Nothing to undo.")
            return
        command = self._history.pop()
        command.undo()
        print("Undo successful.")

run() executes the command and pushes it onto the history stack. undo() pops the last command and calls its undo() method. The stack naturally gives you the right order: last in, first undone.

Putting It All Together

Let's put it all together and walk through a real editing session:

doc = Document()
editor = EditorInvoker()

# Type a title
editor.run(InsertCommand(doc, "Quarterly Report", 0))
doc.show()

# Add a subtitle
editor.run(InsertCommand(doc, " - Finance", 16))
doc.show()

# Oops, wrong subtitle — undo it
editor.undo()
doc.show()

# Delete "Quarterly" and replace with "Annual"
editor.run(DeleteCommand(doc, 0, 9))
doc.show()

editor.run(InsertCommand(doc, "Annual", 0))
doc.show()

# Undo the insert
editor.undo()
doc.show()

# Undo the delete (restores "Quarterly")
editor.undo()
doc.show()

This outputs:

Document: "Quarterly Report"
Document: "Quarterly Report - Finance"
Undo successful.
Document: "Quarterly Report"
Document: " Report"
Document: "Annual Report"
Undo successful.
Document: " Report"
Undo successful.
Document: "Quarterly Report"

Here's the step-by-step breakdown of how (and why) this works:

• Each InsertCommand and DeleteCommand carries its own instructions for both doing and undoing.

• EditorInvoker never looks inside a command. It only calls execute() and undo().

• The document (Document) never thinks about history. It mutates its content when told to.

Each participant has a single, clear responsibility.

Extending with Macros

One of the lesser-known benefits of the command pattern is that commands are just objects. So you can group them. Here's a MacroCommand that batches several commands and undoes them as a unit:

class MacroCommand(Command):
    def __init__(self, commands: list[Command]):
        self.commands = commands

    def execute(self) -> None:
        for cmd in self.commands:
            cmd.execute()

    def undo(self) -> None:
        for cmd in reversed(self.commands):
            cmd.undo()

# Apply a heading format in one shot: clear content, insert formatted title
macro = MacroCommand([
    DeleteCommand(doc, 0, len(doc.content)),
    InsertCommand(doc, "== Annual Report ==", 0),
])

editor.run(macro)
doc.show()

editor.undo()
doc.show()

This gives the following output:

Document: "== Annual Report =="
Undo successful.
Document: "Quarterly Report"

The macro undoes its commands in reverse order. This is correct since the last thing done should be the first thing undone.

When to Use the Command Pattern

The command pattern is a good fit when:

• You need undo/redo: the pattern is practically made for this. Store executed commands in a stack and reverse them.

• You need to queue or schedule operations: commands are objects, so you can put them in a queue, serialize them, or delay execution.

• You want to decouple the caller from the action: the invoker doesn't need to know what the command does. It just runs it.

• You need to support macros or batched operations: group commands into a composite and run them together, as shown above.

Avoid it when:

• The operations are simple and will never need undo or queuing. The pattern adds classes and indirection that may not be worth it for a simple CRUD action.

• Commands would need to share so much state that the "encapsulate the request" idea breaks down.

Conclusion

I hope you found this tutorial useful. To summarize, the command pattern turns actions into objects. And that single idea unlocks a lot: undo/redo, queuing, macros, and clean separation between who triggers an action and what the action does.

We built a document editor from scratch using InsertCommand, DeleteCommand, an EditorInvoker with a history stack, and a MacroCommand for batched edits. Each class knew exactly one thing and did it well.

As a next step, try extending the editor with a RedoCommand. You'll need a second stack alongside the history to bring back undone commands.

Happy coding!

The strategy pattern lets you define a family of algorithms, put each one in its own class, and make them interchangeable at runtime. Instead of writing a giant if/elif chain every time behavior needs to change, you swap in the right strategy for the job.

In this tutorial, you'll learn what the strategy pattern is, why it's useful, and how to implement it in Python with practical examples.

You can get the code on GitHub.

Prerequisites

Before we start, make sure you have:

• Python 3.10 or higher installed

• Basic understanding of Python classes and methods

• Familiarity with object-oriented programming (OOP) concepts

Let's get started!

Table of Contents

• What Is the Strategy Pattern?

• A Simple Strategy Pattern Example

• Swapping Strategies at Runtime

• Using Abstract Base Classes

• When to Use the Strategy Pattern

What Is the Strategy Pattern?

The strategy pattern defines a way to encapsulate a group of related algorithms so they can be used interchangeably. The object that uses the algorithm, called the context, doesn't need to know how it works. It just delegates the work to whichever strategy is currently set.

Think of it like a GPS app. The destination is the same, but you can switch between "avoid highways", "shortest distance", or "least traffic" without changing the destination or the app itself. Each routing option is a separate strategy.

The pattern is useful when:

• You have multiple variations of an algorithm or behavior

• You want to eliminate long if/elif conditionals based on type

• You want to swap behavior at runtime without changing the context class

• Different parts of your app need different variations of the same operation

Now let's look at examples to understand this better.

A Simple Strategy Pattern Example

Let's build a simple e-commerce order system where different discount strategies can be applied at checkout.

First, let's create the three discount strategies:

class RegularDiscount:
    def apply(self, price):
        return price * 0.95  # 5% off

class SeasonalDiscount:
    def apply(self, price):
        return price * 0.80  # 20% off

class NoDiscount:
    def apply(self, price):
        return price  # no change

Each class has a single apply method that takes a price and returns the discounted price. They share the same interface but implement different logic: that's the key concept in the strategy pattern.

Now let's create the Order class that uses one of these strategies:

class Order:
    def __init__(self, product, price, discount_strategy):
        self.product = product
        self.price = price
        self.discount_strategy = discount_strategy

    def final_price(self):
        return self.discount_strategy.apply(self.price)

    def summary(self):
        print(f"Product : {self.product}")
        print(f"Original: ${self.price:.2f}")
        print(f"Final   : ${self.final_price():.2f}")
        print("-" * 30)

The Order class is our context. It doesn't contain any discount logic itself – it delegates that entirely to discount_strategy.apply(). Whichever strategy object you pass in, that's the one that runs.

Now let's place some orders:

order1 = Order("Mechanical Keyboard", 120.00, NoDiscount())
order2 = Order("Laptop Stand", 45.00, RegularDiscount())
order3 = Order("USB-C Hub", 35.00, SeasonalDiscount())

order1.summary()
order2.summary()
order3.summary()

Running the above code should give you the following output:

Product : Mechanical Keyboard
Original: $120.00
Final   : $120.00
------------------------------
Product : Laptop Stand
Original: $45.00
Final   : $42.75
------------------------------
Product : USB-C Hub
Original: $35.00
Final   : $28.00
------------------------------

Notice how Order never checks if discount_type == "seasonal". It just calls apply() and trusts the strategy to handle it. Adding a new discount type in the future means creating one new class and nothing else changes.

Swapping Strategies at Runtime

One of the biggest advantages of the strategy pattern is that you can change the strategy while the program is running. Let's say a user upgrades to a premium membership mid-session:

class ShoppingCart:
    def __init__(self):
        self.items = []
        self.discount_strategy = NoDiscount()  # default

    def add_item(self, name, price):
        self.items.append({"name": name, "price": price})

    def set_discount(self, strategy):
        self.discount_strategy = strategy
        print(f"Discount updated to: {strategy.__class__.__name__}")

    def checkout(self):
        print("\n--- Checkout Summary ---")
        total = 0
        for item in self.items:
            discounted = self.discount_strategy.apply(item["price"])
            print(f"{item['name']}: ${discounted:.2f}")
            total += discounted
        print(f"Total: ${total:.2f}\n")

The set_discount method lets us replace the strategy at any point. Let's see it in action:

cart = ShoppingCart()
cart.add_item("Notebook", 15.00)
cart.add_item("Desk Lamp", 40.00)
cart.add_item("Monitor Riser", 25.00)

# Checkout as a regular customer
cart.checkout()

# User upgrades to seasonal sale membership
cart.set_discount(SeasonalDiscount())
cart.checkout()

This outputs:

--- Checkout Summary ---
Notebook: $15.00
Desk Lamp: $40.00
Monitor Riser: $25.00
Total: $80.00

Discount updated to: SeasonalDiscount

--- Checkout Summary ---
Notebook: $12.00
Desk Lamp: $32.00
Monitor Riser: $20.00
Total: $64.00

The cart itself didn't change – only the strategy did. This is the advantage of keeping behavior separate from the context that uses it.

Using Abstract Base Classes

So far, nothing enforces that every strategy has an apply method. If someone creates a strategy and forgets it, they'll get a cryptic AttributeError at runtime. We can prevent that using Python's Abstract Base Classes.

from abc import ABC, abstractmethod

class DiscountStrategy(ABC):
    @abstractmethod
    def apply(self, price: float) -> float:
        pass

Now let's rewrite our strategies to inherit from it:

class RegularDiscount(DiscountStrategy):
    def apply(self, price):
        return price * 0.95

class SeasonalDiscount(DiscountStrategy):
    def apply(self, price):
        return price * 0.80

class NoDiscount(DiscountStrategy):
    def apply(self, price):
        return price

Now if someone creates a broken strategy without apply, Python will raise a TypeError immediately when they try to instantiate it — before any code runs. That's a much cleaner failure.

class BrokenStrategy(DiscountStrategy):
    pass  # forgot to implement apply()

s = BrokenStrategy()  # raises TypeError right here

Using ABCs is especially helpful on larger teams or in shared codebases, where you want to make the contract explicit: every strategy must implement apply. Else, you run into an error as shown.

      2     pass  # forgot to implement apply()
      3 
----> 4 s = BrokenStrategy()  # raises TypeError right here

TypeError: Can't instantiate abstract class BrokenStrategy without an implementation for abstract method 'apply'

When to Use the Strategy Pattern

The Strategy pattern is a good fit when:

• You have branching logic based on type — long if/elif blocks that check a "mode" or "type" variable are a signal that Strategy might help.

• Behavior needs to change at runtime — when users or config values should be able to switch algorithms without restarting.

• You're building extensible systems — new behavior can be added as a new class without touching existing code.

• You want to test algorithms independently — each strategy is its own class, making unit tests straightforward.

Avoid it when:

• You only have two variations that will never grow — a simple if/else is perfectly fine there.

• The strategies share so much state that separating them into classes adds complexity without benefit.

Conclusion

I hope you found this tutorial useful. To sum up, the strategy pattern gives you a clean way to manage varying behavior without polluting your classes with conditional logic. The context stays simple and stable and the strategies handle the complexity.

We covered the basic pattern, runtime strategy swapping, and enforcing contracts with abstract base classes. As with most design patterns, start simple: even without ABCs, separating your algorithms into their own classes immediately makes your code easier to read, test, and extend.

Happy coding!

The observer pattern is a design pattern where an object (called the subject) maintains a list of dependents (called observers) and notifies them automatically when its state changes. It's like having a newsletter subscription: when new content is published, all subscribers get notified.

In this tutorial, you'll learn what the observer pattern is, why it's useful, and how to implement it in Python with practical examples.

You can find the code on GitHub.

Prerequisites

Before we start, make sure you have:

• Python 3.10 or higher installed

• Understanding of how Python classes and methods work

• Familiarity with object-oriented programming (OOP) concepts

Let's get started!

Table of Contents

• Prerequisites

• What Is the Observer Pattern?

• A Simple Observer Pattern Example

• Handling Unsubscribes

• Different Types of Observers

• Using Abstract Base Classes

• When to Use the Observer Pattern

What Is the Observer Pattern?

The observer pattern defines a one-to-many relationship between objects. When one object changes state, all its dependents are notified and updated automatically.

Think of it like a news agency and reporters. When breaking news happens (the subject), the agency notifies all subscribed reporters (observers) immediately. Each reporter can then handle the news in their own way – some might tweet it, others might write articles, and some might broadcast it on TV.

The pattern is useful when:

• You need to notify multiple objects about state changes

• You want loose coupling between objects

• You don't know how many objects need to be notified in advance

• Objects should be able to subscribe and unsubscribe dynamically

A Simple Observer Pattern Example

Let's start with a basic example: a blog that notifies readers when a new article is published.

We'll create a blog (subject) and email subscribers (observers) who get notified automatically when new content is posted.

First, let's build the Blog class that will manage subscribers and send notifications:

class Blog:
    def __init__(self, name):
        self.name = name
        self._subscribers = []
        self._latest_post = None

    def subscribe(self, subscriber):
        """Add a subscriber to the blog"""
        if subscriber not in self._subscribers:
            self._subscribers.append(subscriber)
            print(f"✓ {subscriber.email} subscribed to {self.name}")

    def unsubscribe(self, subscriber):
        """Remove a subscriber from the blog"""
        if subscriber in self._subscribers:
            self._subscribers.remove(subscriber)
            print(f"✗ {subscriber.email} unsubscribed from {self.name}")

    def notify_all(self):
        """Send notifications to all subscribers"""
        print(f"\nNotifying {len(self._subscribers)} subscribers...")
        for subscriber in self._subscribers:
            subscriber.receive_notification(self.name, self._latest_post)

    def publish_post(self, title):
        """Publish a new post and notify subscribers"""
        print(f"\n📝 {self.name} published: '{title}'")
        self._latest_post = title
        self.notify_all()

The Blog class is our subject. It maintains a list of subscribers in _subscribers and stores the latest post title in _latest_post. The subscribe method adds subscribers to the list, checking for duplicates. The notify_all method loops through all subscribers and calls their receive_notification method. When we call publish_post, it updates the latest post and automatically notifies all subscribers.

Now let's create the observer class that receives notifications:

class EmailSubscriber:
    def __init__(self, email):
        self.email = email

    def receive_notification(self, blog_name, post_title):
        print(f"📧 Email sent to {self.email}: New post on {blog_name} - '{post_title}'")

The EmailSubscriber class is our observer. It has one method, receive_notification, which handles incoming notifications from the blog.

Now let's use these classes together:

# Create a blog
tech_blog = Blog("DevDaily")

# Create subscribers
reader1 = EmailSubscriber("anna@example.com")
reader2 = EmailSubscriber("betty@example.com")
reader3 = EmailSubscriber("cathy@example.com")

# Subscribe to the blog
tech_blog.subscribe(reader1)
tech_blog.subscribe(reader2)
tech_blog.subscribe(reader3)

# Publish posts
tech_blog.publish_post("10 Python Tips for Beginners")
tech_blog.publish_post("Understanding Design Patterns")

Output:

✓ anna@example.com subscribed to DevDaily
✓ betty@example.com subscribed to DevDaily
✓ cathy@example.com subscribed to DevDaily

📝 DevDaily published: '10 Python Tips for Beginners'

Notifying 3 subscribers...
📧 Email sent to anna@example.com: New post on DevDaily - '10 Python Tips for Beginners'
📧 Email sent to betty@example.com: New post on DevDaily - '10 Python Tips for Beginners'
📧 Email sent to cathy@example.com: New post on DevDaily - '10 Python Tips for Beginners'

📝 DevDaily published: 'Understanding Design Patterns'

Notifying 3 subscribers...
📧 Email sent to anna@example.com: New post on DevDaily - 'Understanding Design Patterns'
📧 Email sent to betty@example.com: New post on DevDaily - 'Understanding Design Patterns'
📧 Email sent to cathy@example.com: New post on DevDaily - 'Understanding Design Patterns'

Notice how the Blog class doesn't need to know the details of how each subscriber handles the notification. It just calls their receive_notification method.

Note: Think of all the examples here as placeholder functions that explain how the observer pattern works. In your projects, you’ll have functions that connect to email and other services.

Handling Unsubscribes

In real applications, users need to be able to unsubscribe. Here's how that works:

blog = Blog("CodeMaster")

user1 = EmailSubscriber("john@example.com")
user2 = EmailSubscriber("jane@example.com")

# Subscribe users
blog.subscribe(user1)
blog.subscribe(user2)

# Publish a post
blog.publish_post("Getting Started with Python")

# User1 unsubscribes
blog.unsubscribe(user1)

# Publish another post - only user2 gets notified
blog.publish_post("Advanced Python Techniques")

Output:

✓ john@example.com subscribed to CodeMaster
✓ jane@example.com subscribed to CodeMaster

📝 CodeMaster published: 'Getting Started with Python'

Notifying 2 subscribers...
📧 Email sent to john@example.com: New post on CodeMaster - 'Getting Started with Python'
📧 Email sent to jane@example.com: New post on CodeMaster - 'Getting Started with Python'
✗ john@example.com unsubscribed from CodeMaster

📝 CodeMaster published: 'Advanced Python Techniques'

Notifying 1 subscribers...
📧 Email sent to jane@example.com: New post on CodeMaster - 'Advanced Python Techniques'

After user1 unsubscribes, only user2 receives the notification for the second post. The observer pattern makes it easy to add and remove observers dynamically.

Different Types of Observers

One super useful aspect of the observer pattern is that different observers can react differently to the same event. Let's create a stock price tracker where multiple observer types respond to price changes.

First, let's create the Stock class that will notify observers when the price changes:

class Stock:
    def __init__(self, symbol, price):
        self.symbol = symbol
        self._price = price
        self._observers = []

    def add_observer(self, observer):
        self._observers.append(observer)
        print(f"Observer added: {observer.__class__.__name__}")

    def remove_observer(self, observer):
        self._observers.remove(observer)

    def notify_observers(self):
        for observer in self._observers:
            observer.update(self.symbol, self._price)

    def set_price(self, price):
        print(f"\n {self.symbol} price changed: ${self._price} → ${price}")
        self._price = price
        self.notify_observers()

The Stock class maintains the current price and notifies all observers whenever set_price is called.

Now let's create three different observer types that respond differently to price updates:

class EmailAlert:
    def __init__(self, email):
        self.email = email

    def update(self, symbol, price):
        print(f"📧 Sending email to {self.email}: {symbol} is now ${price}")

class SMSAlert:
    def __init__(self, phone):
        self.phone = phone

    def update(self, symbol, price):
        print(f"📱 Sending SMS to {self.phone}: {symbol} price update ${price}")

class Logger:
    def update(self, symbol, price):
        print(f"📝 Logging: {symbol} = ${price} at system time")

Each observer has a different implementation of the update method. EmailAlert sends emails, SMSAlert sends text messages, and Logger records the change.

Now let's use them together:

# Create a stock
apple_stock = Stock("AAPL", 150.00)

# Create different types of observers
email_notifier = EmailAlert("investor@example.com")
sms_notifier = SMSAlert("+1234567890")
price_logger = Logger()

# Add all observers
apple_stock.add_observer(email_notifier)
apple_stock.add_observer(sms_notifier)
apple_stock.add_observer(price_logger)

# Update the stock price
apple_stock.set_price(155.50)
apple_stock.set_price(152.25)

Output:

Observer added: EmailAlert
Observer added: SMSAlert
Observer added: Logger

 AAPL price changed: $150.0 → $155.5
📧 Sending email to investor@example.com: AAPL is now $155.5
📱 Sending SMS to +1234567890: AAPL price update $155.5
📝 Logging: AAPL = $155.5 at system time

 AAPL price changed: $155.5 → $152.25
📧 Sending email to investor@example.com: AAPL is now $152.25
📱 Sending SMS to +1234567890: AAPL price update $152.25
📝 Logging: AAPL = $152.25 at system time

The Stock class doesn't care what each observer does. It simply calls update on each one and passes the necessary data. You can mix and match observers however you want.

Using Abstract Base Classes

To enforce a consistent interface across all observers, we can use Python's Abstract Base Classes. This guarantees type safety.

First, let's create the base classes that define our interface:

from abc import ABC, abstractmethod

class Subject(ABC):
    def __init__(self):
        self._observers = []

    def attach(self, observer):
        if observer not in self._observers:
            self._observers.append(observer)

    def detach(self, observer):
        self._observers.remove(observer)

    def notify(self, data):
        for observer in self._observers:
            observer.update(data)

class Observer(ABC):
    @abstractmethod
    def update(self, data):
        pass

The Subject class provides standard observer management methods. The Observer class defines the interface with the @abstractmethod decorator ensuring all observers implement update.

Now let's create an order system that uses these base classes:

class OrderSystem(Subject):
    def __init__(self):
        super().__init__()
        self._order_id = None

    def place_order(self, order_id, items):
        print(f"\n🛒 Order #{order_id} placed with {len(items)} items")
        self._order_id = order_id
        self.notify({"order_id": order_id, "items": items})

The OrderSystem inherits from Subject and can manage observers without implementing that logic itself.

Next, let's create concrete observers for different departments:

class InventoryObserver(Observer):
    def update(self, data):
        print(f"📦 Inventory: Updating stock for order #{data['order_id']}")

class ShippingObserver(Observer):
    def update(self, data):
        print(f"🚚 Shipping: Preparing shipment for order #{data['order_id']}")

class BillingObserver(Observer):
    def update(self, data):
        print(f"💳 Billing: Processing payment for order #{data['order_id']}")

Each observer must implement the update method. Now let's put it all together:

# Create the order system
order_system = OrderSystem()

# Create observers
inventory = InventoryObserver()
shipping = ShippingObserver()
billing = BillingObserver()

# Attach observers
order_system.attach(inventory)
order_system.attach(shipping)
order_system.attach(billing)

# Place an order
order_system.place_order("ORD-12345", ["Laptop", "Mouse", "Keyboard"])

Output:

🛒 Order #ORD-12345 placed with 3 items
📦 Inventory: Updating stock for order #ORD-12345
🚚 Shipping: Preparing shipment for order #ORD-12345
💳 Billing: Processing payment for order #ORD-12345

Using abstract base classes provides type safety and ensures all observers follow the same interface.

When to Use the Observer Pattern

The observer pattern is suiatble for:

• Event-driven systems – GUI frameworks, game engines, or any system where actions trigger updates elsewhere.

• Real-time notifications – Chat apps, social media feeds, stock tickers, or push notification systems.

• Decoupled architecture – When you want the subject independent of its observers for flexibility.

• Multiple listeners – When multiple objects need to react to the same event differently.

Avoid the Observer Pattern when you have simple one-to-one relationships, or when performance is critical with many observers (because notification overhead can be significant).

Conclusion

The observer pattern creates a clean separation between objects that produce events and objects that respond to them. It promotes loose coupling – the subject doesn't need to know anything about its observers except that they have an update method.

We've covered the basic implementation, handling subscriptions, using different observer types, and abstract base classes. Start simple with the basic subject-observer relationship and add complexity only when needed.

Happy coding!

In this tutorial, you'll learn what the factory pattern is, why it's useful, and how to implement it in Python. We'll build practical examples that show you when and how to use this pattern in real-world applications.

You can find the code on GitHub.

Prerequisites

Before we start, make sure you have:

• Python 3.10 or higher installed

• Understanding of Python classes and methods

• Familiarity with object-oriented programming (OOP) concepts

Let’s get started!

Table of Contents

• What Is the Factory Pattern?

• A Simple Factory Example

• Using a Dictionary for Cleaner Code

• Factory Pattern with Parameters

• Using Abstract Base Classes

• A More Helpful Example: Database Connection Factory

• When to Use the Factory Pattern

What Is the Factory Pattern?

The factory pattern is a creational design pattern that provides an interface for creating objects without specifying their exact classes. Instead of calling a constructor directly, you call a factory method that decides which class to instantiate.

Think of it like ordering food at a restaurant. You don't go into the kitchen and make the food yourself. You tell the waiter what you want, and the kitchen (the factory) creates it for you. You get your meal without worrying about the recipe or cooking process.

The factory pattern is useful when:

• You have multiple related classes and need to decide which one to instantiate at runtime

• Object creation logic is complex and you want to encapsulate it

• You want to make your code more maintainable and testable

A Simple Factory Example

Let's start with a basic example. Say you're building a notification system that can send messages via email, SMS, or push notifications.

Without a factory, you might write code like this everywhere in your application:

# Bad approach - tight coupling
if notification_type == "email":
    notifier = EmailNotifier()
elif notification_type == "sms":
    notifier = SMSNotifier()
elif notification_type == "push":
    notifier = PushNotifier()

This gets messy quickly. Let's use a factory instead:

class EmailNotifier:
    def send(self, message):
        return f"Sending email: {message}"

class SMSNotifier:
    def send(self, message):
        return f"Sending SMS: {message}"

class PushNotifier:
    def send(self, message):
        return f"Sending push notification: {message}"

class NotificationFactory:
    @staticmethod
    def create_notifier(notifier_type):
        if notifier_type == "email":
            return EmailNotifier()
        elif notifier_type == "sms":
            return SMSNotifier()
        elif notifier_type == "push":
            return PushNotifier()
        else:
            raise ValueError(f"Unknown notifier type: {notifier_type}")

In this code, we define three notifier classes, each with a send method.

Note: In a real application, these would have different implementations for sending notifications.

The NotificationFactory class has a static method called create_notifier. This is our factory method. It takes a string parameter and returns the appropriate notifier object.

The @staticmethod decorator means we can call this method without creating an instance of the factory. We just use NotificationFactory.create_notifier().

# Using the factory
notifier = NotificationFactory.create_notifier("email")
result = notifier.send("Hello, World!")

Now, whenever we need a notifier, we call the factory instead of instantiating classes directly. This centralizes our object creation logic in one place.

Using a Dictionary for Cleaner Code

The if-elif chain in our factory can get unwieldy as we add more notifier types. Let's refactor using a dictionary:

class NotificationFactory:
    notifier_types = {
        "email": EmailNotifier,
        "sms": SMSNotifier,
        "push": PushNotifier
    }

    @staticmethod
    def create_notifier(notifier_type):
        notifier_class = NotificationFactory.notifier_types.get(notifier_type)
        if notifier_class:
            return notifier_class()
        else:
            raise ValueError(f"Unknown notifier type: {notifier_type}")

This approach is much cleaner. We store a dictionary that maps strings to class objects and not instances. The keys are notifier type names, and the values are the actual class references.

The get method retrieves the class from the dictionary. If the key doesn't exist, it returns None. We then instantiate the class by calling it with parentheses: notifier_class().

# Test with different types
email_notifier = NotificationFactory.create_notifier("email")
sms_notifier = NotificationFactory.create_notifier("sms")
push_notifier = NotificationFactory.create_notifier("push")

This makes adding new notifier types easier. You just add another entry to the dictionary.

Factory Pattern with Parameters

Real-world objects often need configuration. Let's extend our factory to handle notifiers that require initialization parameters.

We'll create a document generator that produces different file formats with custom settings:

class PDFDocument:
    def __init__(self, title, author):
        self.title = title
        self.author = author
        self.format = "PDF"

    def generate(self):
        return f"Generating {self.format}: '{self.title}' by {self.author}"

class WordDocument:
    def __init__(self, title, author):
        self.title = title
        self.author = author
        self.format = "DOCX"

    def generate(self):
        return f"Generating {self.format}: '{self.title}' by {self.author}"

class MarkdownDocument:
    def __init__(self, title, author):
        self.title = title
        self.author = author
        self.format = "MD"

    def generate(self):
        return f"Generating {self.format}: '{self.title}' by {self.author}"

class DocumentFactory:
    document_types = {
        "pdf": PDFDocument,
        "word": WordDocument,
        "markdown": MarkdownDocument
    }

    @staticmethod
    def create_document(doc_type, title, author):
        document_class = DocumentFactory.document_types.get(doc_type)
        if document_class:
            return document_class(title, author)
        else:
            raise ValueError(f"Unknown document type: {doc_type}")

The key difference here is that our factory method now accepts additional parameters.

The create_document method takes doc_type, title, and author as arguments. When we instantiate the class, we pass the title and author to the create_document constructor: document_class(title, author).

# Create different documents with parameters
pdf = DocumentFactory.create_document("pdf", "Python Guide", "Tutorial Team")
word = DocumentFactory.create_document("word", "Meeting Notes", "Grace Dev")
markdown = DocumentFactory.create_document("markdown", "README", "DevTeam")

This lets us create fully configured objects through the factory while keeping the creation logic centralized.

Using Abstract Base Classes

To make our factory more robust, we can use Python's Abstract Base Classes (ABC) to enforce a common interface.

Let's create a super simple payment processing system:

from abc import ABC, abstractmethod

class PaymentProcessor(ABC):
    @abstractmethod
    def process_payment(self, amount):
        pass

    @abstractmethod
    def refund(self, transaction_id):
        pass

class CreditCardProcessor(PaymentProcessor):
    def process_payment(self, amount):
        return f"Processing ${amount} via Credit Card"

    def refund(self, transaction_id):
        return f"Refunding credit card transaction {transaction_id}"

class PayPalProcessor(PaymentProcessor):
    def process_payment(self, amount):
        return f"Processing ${amount} via PayPal"

    def refund(self, transaction_id):
        return f"Refunding PayPal transaction {transaction_id}"

class PaymentFactory:
    processors = {
        "credit_card": CreditCardProcessor,
        "paypal": PayPalProcessor
    }

    @staticmethod
    def create_processor(processor_type):
        processor_class = PaymentFactory.processors.get(processor_type)
        if processor_class:
            return processor_class()
        else:
            raise ValueError(f"Unknown processor type: {processor_type}")

Here, the PaymentProcessor class defines an interface that all payment processors must implement. The @abstractmethod decorator marks methods that subclasses must override.

You cannot instantiate PaymentProcessor directly. It only serves as a blueprint. All concrete processors (CreditCardProcessor, PayPalProcessor) must implement both process_payment and refund methods. If they don't, Python will raise an error. This guarantees that any object created by our factory will have the expected methods, making our code more predictable and safer.

You can use the factory like so:

processor = PaymentFactory.create_processor("paypal")

A More Helpful Example: Database Connection Factory

Let's build something practical: a factory that creates different database connection objects based on configuration.

class MySQLConnection:
    def __init__(self, host, database):
        self.host = host
        self.database = database
        self.connection_type = "MySQL"

    def connect(self):
        return f"Connected to {self.connection_type} at {self.host}/{self.database}"

    def execute_query(self, query):
        return f"Executing on MySQL: {query}"

class PostgreSQLConnection:
    def __init__(self, host, database):
        self.host = host
        self.database = database
        self.connection_type = "PostgreSQL"

    def connect(self):
        return f"Connected to {self.connection_type} at {self.host}/{self.database}"

    def execute_query(self, query):
        return f"Executing on PostgreSQL: {query}"

class SQLiteConnection:
    def __init__(self, host, database):
        self.host = host
        self.database = database
        self.connection_type = "SQLite"

    def connect(self):
        return f"Connected to {self.connection_type} at {self.host}/{self.database}"

    def execute_query(self, query):
        return f"Executing on SQLite: {query}"

class DatabaseFactory:
    db_types = {
        "mysql": MySQLConnection,
        "postgresql": PostgreSQLConnection,
        "sqlite": SQLiteConnection
    }

    @staticmethod
    def create_connection(db_type, host, database):
        db_class = DatabaseFactory.db_types.get(db_type)
        if db_class:
            return db_class(host, database)
        else:
            raise ValueError(f"Unknown database type: {db_type}")

    @staticmethod
    def create_from_config(config):
        """Create a database connection from a configuration dictionary"""
        return DatabaseFactory.create_connection(
            config["type"],
            config["host"],
            config["database"]
        )

This example shows a more realistic use case. We have multiple database connection classes, each with the same interface but different implementations.

The factory has two creation methods: create_connection for direct parameters and create_from_config for configuration dictionaries.

The create_from_config method is particularly useful because it lets you load database settings from a config file or environment variables and create the appropriate connection object.

This pattern makes it easy to switch between different databases without changing your application code. You just change the configuration as shown:

# Use with direct parameters
db1 = DatabaseFactory.create_connection("mysql", "localhost", "myapp_db")
print(db1.connect())
print(db1.execute_query("SELECT * FROM users"))

# Use with configuration dictionary
config = {
    "type": "postgresql",
    "host": "db.example.com",
    "database": "production_db"
}
db2 = DatabaseFactory.create_from_config(config)

When to Use the Factory Pattern

The factory pattern is useful when you have the following:

1. Multiple related classes: When you have several classes that share a common interface but have different implementations (like the payment processors or database connections we had in the examples).

2. Runtime decisions: When you need to decide which class to instantiate based on user input, configuration, or other runtime conditions.

3. Complex object creation: When creating an object involves multiple steps or requires specific logic that you want to encapsulate.

However, don't use the factory pattern when:

• You only have one or two simple classes

• Object creation is straightforward with no special logic

• The added abstraction makes your code harder to understand

Wrapping Up

The factory pattern is a useful tool for managing object creation in Python. It helps you write cleaner, more maintainable code by centralizing creation logic and decoupling your code from specific class implementations. We've covered:

• Basic factory implementation with simple examples

• Using dictionaries for cleaner factory code

• Passing parameters to factory-created objects

• Using abstract base classes for cleaner interfaces

The key takeaway is this: whenever you find yourself writing repetitive object creation code or need to decide which class to instantiate at runtime, consider using the factory pattern. Start simple and add complexity only when needed. The basic dictionary-based factory is often all you need for most applications.

Happy coding!

Creational design patterns govern how classes and objects are created in a systematic and scalable way. They provide blueprints for creating objects so you don't repeat code. They also keep your system consistent and makes your app easy to extend.

There are five major Creational Design patterns:

1. Singleton: Ensures a class has only one instance and provides a global point of access to it.

2. Factory Method: Provides an interface for creating objects but lets subclasses decide which class to instantiate.

3. Abstract Factory: Creates families of related objects without specifying their concrete classes.

4. Builder: Allows you to construct complex objects step by step, separating construction from representation.

5. Prototype: Creates new objects by cloning existing ones, rather than creating from scratch.

Each of these patterns solves specific problems around object creation, depending on the complexity and scale of your application.

In this tutorial, I'll explain what Creational Design Patterns are and how they work. We'll focus on two primary patterns: the Factory and Abstract Factory patterns.

Many people mix these two up, so here we'll explore:

1. How each pattern works

2. Practical examples in Flutter

3. Applications, best practices, and usage

By the end, you'll understand when to use Factory, when to switch to Abstract Factory, and how to structure your Flutter apps for scalability and maintainability.

Table of Contents

1. How the Factory Pattern Works in Flutter

   • Step 1: Define the Product and Abstract Creator

   • Step 2: Implement Concrete Products

   • Step 3: Create the Factory

   • Step 4: Use the Factory

2. Factory Pattern for Security Checks

3. How the Abstract Factory Pattern Works in Flutter

   • Step 1: Define Abstract Product Interfaces

   • Step 2: Implement Platform-Specific Products

   • Step 3: Define the Abstract Factory Interface

   • Step 4: Implement Platform Specific Factories

   • Step 5: Client Code Using Abstract Factory

4. Conclusion

Prerequisites

Before diving into this tutorial, you should have:

• a basic understanding of the Dart programming language

• familiarity with Object-Oriented Programming (OOP) concepts (particularly classes, inheritance, and abstract classes)

• basic knowledge of Flutter development (helpful but not required)

• an understanding of interfaces and polymorphism

• and experience creating and instantiating classes in Dart.

How the Factory Pattern Works in Flutter

You'll typically use the Factory Pattern when you want to manage data sets that might be related, but only for a single type of object.

Let's say you want to manage themes for Android and iOS. Using the Factory Pattern allows you to encapsulate object creation and keep your app modular. We'll build this step by step so you can see how the pattern works.

Step 1: Define the Product and Abstract Creator

class AppTheme {
  String? data;
  AppTheme({this.data});
}

abstract class ApplicationThemeData {
  Future<AppTheme> getApplicationTheme();
}

Here, AppTheme is a simple data class that holds theme information. This represents the product our factory will create. ApplicationThemeData serves as an abstract base class. This abstraction is crucial because it defines a contract that all concrete theme implementations must follow.

By requiring a getApplicationTheme() method, we ensure consistency across different platforms.

Step 2: Implement Concrete Products

Now we create platform-specific implementations that provide actual theme data.

class AndroidAppTheme extends ApplicationThemeData {
  @override
  Future<AppTheme> getApplicationTheme() async {
    return AppTheme(data: "Here is android theme");
  }
}

class IOSThemeData extends ApplicationThemeData {
  @override
  Future<AppTheme> getApplicationTheme() async {
    return AppTheme(data: "This is IOS theme data");
  }
}

The concrete implementations, AndroidAppTheme and IOSThemeData, extend the abstract class and provide platform-specific theme data. Each returns an AppTheme object with content tailored to its respective platform.

Step 3: Create the Factory

The factory encapsulates the object creation logic, so client code doesn't need to know which specific theme class it's working with.

class ThemeFactory {
  ThemeFactory({required this.theme});
  ApplicationThemeData theme;

  loadTheme() async {
    return await theme.getApplicationTheme();
  }
}

ThemeFactory acts as the factory itself. It accepts any ApplicationThemeData implementation and provides a unified loadTheme() method. This encapsulates the object creation logic cleanly.

Step 4: Use the Factory

Finally, we use the factory in our application code.

ThemeFactory(
  theme: Platform.isAndroid ? AndroidAppTheme() : IOSThemeData()
).loadTheme();

Here, you choose a theme (Android or iOS) and get the corresponding AppTheme. This approach is simple and effective when you only care about one functionality, like loading a theme.

The beauty of this pattern is that the client code remains clean and doesn't need to change if you add new platforms later.

Factory Pattern for Security Checks

Another excellent use case for the Factory Pattern is when implementing security checks during your application bootstrap.

For instance, Android and iOS require different logic for internal security. Android might check for developer mode or rooted devices, while iOS checks for jailbroken devices. This scenario is a perfect example of when to apply the Factory Pattern, as it allows you to encapsulate platform-specific security logic cleanly and maintainably. Let's implement this step by step.

Step 1: Define Security Check Result and Abstract Checker

First, we need a standardized way to communicate security check outcomes and a contract for performing security checks.

// Base security check result class
class SecurityCheckResult {
  final bool isSecure;
  final String message;

  SecurityCheckResult({required this.isSecure, required this.message});
}

// Abstract security checker
abstract class SecurityChecker {
  Future<SecurityCheckResult> performSecurityCheck();
}

The SecurityCheckResult class provides a standardized way to communicate security check outcomes across platforms.

It contains a boolean flag indicating security status and a descriptive message for the user. The abstract SecurityChecker class defines the contract that all platform-specific security implementations must follow.

This ensures that, regardless of the platform, we can always call performSecurityCheck() and receive a consistent result type.

Step 2: Implement Platform-Specific Security Checkers

Now we create the actual security checking implementations for each platform.

// Android-specific security implementation
class AndroidSecurityChecker extends SecurityChecker {
  @override
  Future<SecurityCheckResult> performSecurityCheck() async {
    bool isRooted = await checkIfDeviceIsRooted();
    if (isRooted) {
      return SecurityCheckResult(
        isSecure: false,
        message: "Device is rooted. App cannot run on rooted devices."
      );
    }

    bool isDeveloperMode = await checkDeveloperMode();
    if (isDeveloperMode) {
      return SecurityCheckResult(
        isSecure: false,
        message: "Developer mode is enabled. Please disable it to continue."
      );
    }

    return SecurityCheckResult(
      isSecure: true,
      message: "Device security check passed."
    );
  }

  Future<bool> checkIfDeviceIsRooted() async {
    return false; 
  }

  Future<bool> checkDeveloperMode() async {
    return false; // Placeholder
  }
}

// iOS-specific security implementation
class IOSSecurityChecker extends SecurityChecker {
  @override
  Future<SecurityCheckResult> performSecurityCheck() async {
    bool isJailbroken = await checkIfDeviceIsJailbroken();

    if (isJailbroken) {
      return SecurityCheckResult(
        isSecure: false,
        message: "Device is jailbroken. App cannot run on jailbroken devices."
      );
    }

    return SecurityCheckResult(
      isSecure: true,
      message: "Device security check passed."
    );
  }

  Future<bool> checkIfDeviceIsJailbroken() async {
    return false; 
  }
}

The Android implementation focuses on detecting rooted devices and developer mode, which are common security concerns on Android.

A rooted device has elevated permissions that could allow malicious apps to access sensitive data, while developer mode can expose debugging interfaces.

The iOS implementation checks for jailbroken devices, which is the iOS equivalent of rooting. Jailbroken devices bypass Apple's security restrictions and can pose similar security risks.

Step 3: Create the Security Factory

The factory wraps the chosen security checker and provides a clean interface for running checks.

// Security Factory
class SecurityCheckFactory {
  SecurityCheckFactory({required this.checker});
  SecurityChecker checker;

  Future<SecurityCheckResult> runSecurityCheck() async {
    return await checker.performSecurityCheck();
  }
}

The SecurityCheckFactory provides a simple interface that accepts any SecurityChecker implementation. This means your app initialization code doesn't need to know about platform-specific security details – it just calls runSecurityCheck() and handles the result.

Step 4: Use the Security Factory in App Bootstrap

Finally, we integrate the security factory into our app's initialization process.

// In your app's bootstrap/initialization
Future<void> initializeApp() async {
  final securityFactory = SecurityCheckFactory(
    checker: Platform.isAndroid 
      ? AndroidSecurityChecker() 
      : IOSSecurityChecker()
  );

  final result = await securityFactory.runSecurityCheck();

  if (!result.isSecure) {
    // Show error dialog and prevent app from continuing
    showSecurityErrorDialog(result.message);
    return;
  }

  // Continue with normal app initialization
  runApp(MyApp());
}

This usage example demonstrates how the Factory Pattern makes your app initialization code clean and maintainable.

The platform detection happens in one place, the factory handles the creation of the appropriate checker, and your code simply deals with the standardized result.

Key takeaway: Factory is great when you need one type of object, but you want to abstract away the creation logic.

How the Abstract Factory Pattern Works in Flutter

The Abstract Factory Pattern comes into play when you have more than two data sets for comparison, and each set includes multiple functionalities.

For example, imagine you now want to manage themes, widgets, and architecture for Android, iOS, and Linux. Managing this with just a Factory becomes messy, so Abstract Factory provides a structured way to handle multiple related objects for different platforms.

So let's see how you can handle this using the abstract factory method.

Step 1: Define Abstract Product Interfaces

Before we dive into this implementation, it's important to understand what abstract product interfaces are. An abstract product interface is essentially a contract that defines what methods a product must implement, without specifying how they're implemented.

Think of it as a blueprint that ensures all related products share a common structure. In our case, we're defining three core functionalities that every platform must provide:

1. Theme management

2. Widget handling

3. Architecture configuration.

By creating these abstract interfaces first, we establish a consistent API that all platform-specific implementations will follow.

abstract class ThemeManager {
  Future<String> getTheme();
}

abstract class WidgetHandler {
  Future<bool> getWidget();
}

abstract class ArchitechtureHandler {
  Future<String> getArchitechture();
}

Here, we’re defining three base functionalities that every platform will implement: theme, widgets, and architecture.

Each interface declares a single method that returns platform-specific information.

The ThemeManager retrieves theme data, WidgetHandler determines widget compatibility, and ArchitechtureHandler provides architecture details.

Step 2: Implement Platform-Specific Products

Now that we have our abstract interfaces defined, we need to create concrete implementations for each platform. This step is where we provide the actual, platform-specific behavior for each product type. Think of this as filling in the blueprint with real details.

While the abstract interfaces told us what methods we need, these concrete classes tell us how those methods behave on each specific platform. Each platform (Android, iOS, Linux) will have its own unique implementation of themes, widgets, and architecture.

Android:

class AndroidThemeManager extends ThemeManager {
  @override
  Future<String> getTheme() async {
    return "Android Theme";
  }
}

class AndroidWidgetHandler extends WidgetHandler {
  @override
  Future<bool> getWidget() async {
    return true;
  }
}

class AndroidArchitechtureHandler extends ArchitechtureHandler {
  @override
  Future<String> getArchitechture() async {
    return "Android Architecture";
  }
}

For Android, we're creating three specific product classes. The AndroidThemeManager returns Material Design theme data, the AndroidWidgetHandler returns true to indicate that Android supports home screen widgets, and the AndroidArchitechtureHandler provides information about Android's architecture (which could include details about ARM, x86, or other processor architectures).

iOS:

class IOSThemeManager extends ThemeManager {
  @override
  Future<String> getTheme() async {
    return "IOS Theme";
  }
}

class IOSWidgetHandler extends WidgetHandler {
  @override
  Future<bool> getWidget() async {
    return false;
  }
}

class IOSArchitechtureHandler extends ArchitechtureHandler {
  @override
  Future<String> getArchitechture() async {
    return "iOS Architecture";
  }
}

The iOS implementations follow the same structure but provide iOS-specific values. Notice that IOSWidgetHandler returns false, this could represent a scenario where certain widget features aren't available or behave differently on iOS compared to Android.

Linux:

class LinuxThemeManager extends ThemeManager {
  @override
  Future<String> getTheme() async {
    return "Linux Theme";
  }
}

class LinuxWidgetHandler extends WidgetHandler {
  @override
  Future<bool> getWidget() async {
    return true;
  }
}

class LinuxArchitechtureHandler extends ArchitechtureHandler {
  @override
  Future<String> getArchitechture() async {
    return "Linux Architecture";
  }
}

Similarly, Linux gets its own set of implementations, providing Linux-specific theme data and architecture information.

Step 3: Define the Abstract Factory Interface

With our product classes ready, we now need to create the factory that will produce them.

The abstract factory interface is the master blueprint that declares which products our factory must be able to create. This interface doesn't create anything itself, it simply declares that any concrete factory must provide methods to create all three product types (theme, widget, and architecture handlers). This ensures that, regardless of which platform factory we use, we can always access all three functionalities.

abstract class AppFactory {
  ThemeManager themeManager();
  WidgetHandler widgetManager();
  ArchitechtureHandler architechtureHandler();
}

Here, we define a factory blueprint. Any platform specific factory will have to implement all three functionalities. This guarantees consistency: every platform will have all three capabilities available.

Step 4: Implement Platform Specific Factories

This is where everything comes together. We're now creating the actual factories that will produce the platform-specific products we defined earlier. Each factory is responsible for creating all the related products for its platform. The key advantage here is encapsulation: the factory knows how to create all the related objects for a platform, and it ensures they're compatible with each other. For example, AndroidFactory creates Android-specific theme managers, widget handlers, and architecture handlers that all work together seamlessly.

class AndroidFactory extends AppFactory {
  @override
  ThemeManager themeManager() => AndroidThemeManager();

  @override
  WidgetHandler widgetManager() => AndroidWidgetHandler();

  @override
  ArchitechtureHandler architechtureHandler() => AndroidArchitechtureHandler();
}

class IOSFactory extends AppFactory {
  @override
  ThemeManager themeManager() => IOSThemeManager();

  @override
  WidgetHandler widgetManager() => IOSWidgetHandler();

  @override
  ArchitechtureHandler architechtureHandler() => IOSArchitechtureHandler();
}

class LinuxFactory extends AppFactory {
  @override
  ThemeManager themeManager() => LinuxThemeManager();

  @override
  WidgetHandler widgetManager() => LinuxWidgetHandler();

  @override
  ArchitechtureHandler architechtureHandler() => LinuxArchitechtureHandler();
}

Each concrete factory (AndroidFactory, IOSFactory, LinuxFactory) implements all three methods from the AppFactory interface. When you call themeManager() on AndroidFactory, you get an AndroidThemeManager. When you call it on IOSFactory, you get an IOSThemeManager. The same pattern applies to all products.

Step 5: Client Code Using Abstract Factory

Finally, we create the client code that uses our abstract factory. This is the layer that your application will actually interact with. The beauty of this pattern is that the client code doesn't need to know anything about the specific platform implementations, it just works with the abstract factory interface.

The AppBaseFactory class accepts any factory that implements AppFactory and provides a simple method to initialize all platform settings. The CheckDevice class determines which factory to use based on the current platform, completely abstracting this decision away from the rest of your application.

class AppBaseFactory {
  AppBaseFactory({required this.factory});
  AppFactory factory;

  getAppSettings() {
    factory
      ..architechtureHandler()
      ..themeManager()
      ..widgetManager();
  }
}

class CheckDevice {
  static get() {
    if (Platform.isAndroid) return AndroidFactory();
    if (Platform.isIOS) return IOSFactory();
    if (Platform.isLinux) return LinuxFactory();
    throw UnsupportedError("Platform not supported");
  }
}

// Usage
AppBaseFactory(factory: CheckDevice.get()).getAppSettings();

Here's what's happening in this code:

The AppBaseFactory class acts as a wrapper around any AppFactory implementation. It provides a convenient getAppSettings() method that initializes all three components (architecture handler, theme manager, and widget manager) using Dart's cascade notation.

The CheckDevice class contains the platform detection logic. Its static get() method checks the current platform and returns the appropriate factory. This centralizes all platform detection in one place. When you call AppBaseFactory(factory: CheckDevice.get()).getAppSettings(), the code automatically detects your platform, creates the right factory, and initializes all platform-specific components, all without the calling code needing to know any platform-specific details.

Each platform factory produces all related products. The client only interacts with AppBaseFactory, remaining unaware of the internal implementation. This ensures your code is scalable, maintainable, and consistent.

Real-World Application: Payment Provider Management

Another good use case for abstract factory is when you need to switch between multiple payment providers in your application and you only want to expose the necessary functionality to the client (presentation layer).

The abstract factory design pattern properly helps you manage this scenario in terms of concrete implementation, encapsulation, clean code, separation of concerns, and proper code structure and management. For example, you might support Stripe, PayPal, and Flutterwave in your application.

Each provider requires different initialization, transaction processing, and webhook handling. By using the Abstract Factory pattern, you can create a consistent interface for all payment operations while keeping provider-specific details encapsulated within their respective factory implementations.

Conclusion

You should now feel more comfortable deciding when to use the Factory design pattern vs the Abstract Factory design pattern.

Understanding the factory and abstract factory patterns and their usages properly will help with object creation based on the particular use case you are trying to implement.

The Factory Pattern is ideal when you need one product and want to encapsulate creation logic while the Abstract Factory Pattern works well when you have multiple related products across platforms, need consistency, and want scalability. Using these patterns will help you write clean, maintainable, and scalable Flutter apps.

They give you a systematic approach to object creation and prevent messy, hard-to-maintain code as your app grows.

The Singleton Design Pattern is a creational design pattern that solves this problem by ensuring that a class has exactly one instance and provides a global point of access to it.

This pattern is widely used in mobile apps, backend systems, and Flutter applications for managing shared resources such as:

• Database connections

• API clients

• Logging services

• Application configuration

• Security checks during app bootstrap

In this article, we'll explore what the Singleton pattern is, how to implement it in Flutter/Dart, its variations (eager, lazy, and factory), and physical examples. By the end, you'll understand the proper way to use this pattern effectively and avoid common pitfalls.

Table of Contents

1. Prerequisites

2. What is the Singleton Pattern?

   • When to Use the Singleton Pattern

3. How to Create a Singleton Class

   • Eager Singleton

   • Lazy Singleton

   • Choosing Between Eager and Lazy

4. Factory Constructors in the Singleton Pattern

   • What Are Factory Constructors?

   • Implementing Singleton with Factory Constructor

5. When Not to Use a Singleton

   • Why Singletons Can Be Problematic

   • Scenarios Where You Should Avoid Singletons

   • General Guidelines

6. Conclusion

Prerequisites

Before diving into this tutorial, you should have:

1. Basic understanding of the Dart programming language

2. Familiarity with Object-Oriented Programming (OOP) concepts, particularly classes and constructors

3. Basic knowledge of Flutter development (helpful but not required)

4. Understanding of static variables and methods in Dart

5. Familiarity with the concept of class instantiation

What is the Singleton Pattern?

The Singleton pattern is a creational design pattern that ensures a class has only one instance and that there is a global point of access to the instance.

Again, this is especially powerful when managing shared resources across an application.

When to Use the Singleton Pattern

You should use a Singleton when you are designing parts of your system that must exist once, such as:

1. Global app state (user session, auth token, app config)

2. Shared services (logger, API client, database connection)

3. Resource heavy logic (encryption handlers, ML models, cache manager)

4. Application boot security (run platform-specific root/jailbreak checks)

For example, in a Flutter app, Android may check developer mode or root status, while iOS checks jailbroken device state. A Singleton security class is a perfect way to enforce that these checks run once globally during app startup.

How to Create a Singleton Class

We have two major ways of creating a singleton class:

1. Eager Instantiation

2. Lazy Instantiation

Eager Singleton

This is where the Singleton is created at load time, whether it's used or not.

In this case, the instance of the singleton class as well as any initialization logic runs at load time, regardless of when this class is actually needed or used. Here's how it works:

class EagerSingleton {
  EagerSingleton._internal();
  static final EagerSingleton _instance = EagerSingleton._internal();

  static EagerSingleton get instance => _instance;

  void sayHello() => print("Hello from Eager Singleton");
}

//usage
void main() {
  // Accessing the singleton globally
  EagerSingleton.instance.sayHello();
}

How the Eager Singleton Works

Let's break down what's happening in this implementation:

First, EagerSingleton._internal() is a private named constructor (notice the underscore prefix). This prevents external code from creating new instances using EagerSingleton(). The only way to get an instance is through the controlled mechanism we're about to define.

Next, static final EagerSingleton _instance = EagerSingleton._internal(); is the key line. This creates the single instance immediately when the class is first loaded into memory. Because it's static final, it belongs to the class itself (not any particular instance) and can only be assigned once. The instance is created right here, at declaration time.

The static EagerSingleton get instance => _instance; getter provides global access to that single instance. Whenever you call EagerSingleton.instance anywhere in your code, you're getting the exact same object that was created when the class loaded.

Finally, sayHello() is just a regular method to demonstrate that the singleton works. You could replace this with any business logic your singleton needs to perform.

When you run the code in main(), the class loads, the instance is created immediately, and EagerSingleton.instance.sayHello() accesses that pre-created instance to call the method.

Pros:

1. This is simple and thread safe, meaning it's not affected by concurrency, especially when your app runs on multithreads.

2. It's ideal if the instance is lightweight and may be accessed frequently.

Cons:

1. If this instance is never used through the runtime, it results in wasted memory and could impact application performance.

Lazy Singleton

In this case, the singleton instance is only created when the class is called or needed in runtime. Here, a trigger needs to happen before the instance is created. Let's see an example:

class LazySingleton {
  LazySingleton._internal(); 
  static LazySingleton? _instance;

  static LazySingleton get instance {
    _instance ??= LazySingleton._internal();
    return _instance!;
  }

  void sayHello() => print("Hello from LazySingleton");
}

//usage 
void main() {
  // Accessing the singleton globally
  LazySingleton.instance.sayHello();
}

How the Lazy Singleton Works

The lazy implementation differs from eager in one crucial way: timing.

Again, LazySingleton._internal() is a private constructor that prevents external instantiation.

But notice that static LazySingleton? _instance; is declared as nullable and not initialized. Unlike the eager version, no instance is created at load time. The variable simply exists as null until it's needed.

The magic happens in the getter: _instance ??= LazySingleton._internal(); uses Dart's null-aware assignment operator. This line says "if _instance is null, create a new instance and assign it. Otherwise, keep the existing one." This is the lazy initialization: the instance is only created the first time someone accesses it.

The first time you call LazySingleton.instance, _instance is null, so a new instance is created. Every subsequent call finds that _instance already exists, so it just returns that same instance.

The return _instance!; uses the null assertion operator because we know _instance will never be null at this point (we just ensured it's not null in the previous line).

This approach saves memory because if you never call LazySingleton.instance in your app, the instance never gets created.

Pros:

1. Saves application memory, as it only creates what is needed in runtime.

2. Avoids memory leaks.

3. Is ideal for resource heavy objects while considering application performance.

Cons:

1. Could be difficult to manage in multithreaded environments, as you have to ensure thread safety while following this pattern.

Choosing Between Eager and Lazy

Now that we've broken down these two major types of singleton instantiation, it's worthy of note that you'll need to be intentional while deciding whether to create a singleton the eager or lazy way. Your use case/context should help you determine what singleton pattern you need to apply during object creation.

As an engineer, you need to ask yourself these questions when using a singleton for object creation:

1. Do I need this class instantiated when the app loads?

2. Based on the user journey, will this class always be needed during every session?

3. Can a user journey be completed without needing to call any logic in this class?

These three questions will determine what pattern (eager or lazy) you should use to fulfill best practices while maintaining scalability and high performance in your application.

Factory Constructors in the Singleton Pattern

Applying factory constructors in the Singleton pattern can be powerful if you use them properly. But first, let's understand what factory constructors are.

What Are Factory Constructors?

A factory constructor in Dart is a special type of constructor that doesn't always create a new instance of its class. Unlike regular constructors that must return a new instance, factory constructors can:

1. Return an existing instance (perfect for singletons)

2. Return a subclass instance

3. Apply logic before deciding what to return

4. Perform validation or initialization before returning an object

The factory keyword tells Dart that this constructor has the flexibility to return any instance of the class (or its subtypes), not necessarily a fresh one.

Implementing Singleton with Factory Constructor

This allows you to apply initialization logic while your class instance is being created before returning the instance.

class FactoryLazySingleton {
  FactoryLazySingleton._internal();
  static final FactoryLazySingleton _instance = FactoryLazySingleton._internal();

  static FactoryLazySingleton get instance => _instance;

  factory FactoryLazySingleton() {
    // Your logic runs here
    print("Factory constructor called");
    return _instance;
  }
}

How the Factory Constructor Singleton Works

This implementation combines aspects of both eager and lazy patterns with additional control.

The FactoryLazySingleton._internal() private constructor and static final _instance create an eager singleton. The instance is created immediately when the class loads.

The static get instance provides the traditional singleton access pattern we've seen before.

But the interesting part is the factory FactoryLazySingleton() constructor. This is a public constructor that looks like a normal constructor call, but behaves differently. When you call FactoryLazySingleton(), instead of creating a new instance, it runs whatever logic you've placed inside (in this case, a print statement), then returns the existing _instance.

This pattern is powerful because:

1. You can log when someone tries to create an instance

2. You can validate conditions before returning the instance

3. You can apply configuration based on parameters passed to the factory

4. You can choose to return different singleton instances based on conditions

For example, you might have different configuration singletons for development vs production:

factory FactoryLazySingleton({bool isProduction = false}) {
  if (isProduction) {
    // Apply production configuration
    _instance.configure(productionSettings);
  } else {
    // Apply development configuration
    _instance.configure(devSettings);
  }
  return _instance;
}

Pros

1. You can add logic before returning an instance

2. You can cache or reuse the same object

3. You can dynamically return a subtype if needed

4. You avoid unnecessary instantiation

5. You can inject configuration or environment logic

Cons

1. Adds slight complexity compared to simple getter access

2. The factory constructor syntax might confuse developers unfamiliar with the pattern

3. If overused with complex logic, it can make debugging harder

4. Can create misleading code where FactoryLazySingleton() looks like it creates a new instance but doesn't

When Not to Use a Singleton

While singletons are powerful, they're not always the right solution. Understanding when to avoid them is just as important as knowing when to use them.

Why Singletons Can Be Problematic

Singletons create global state, which can make your application harder to reason about and test. They introduce tight coupling between components that shouldn't necessarily know about each other, and they can make it difficult to isolate components for unit testing.

Scenarios Where You Should Avoid Singletons

Avoid using the Singleton pattern if:

You need multiple independent instances

If different parts of your app need their own separate configurations or states, singletons force you into a one-size-fits-all approach.

For example, if you're building a multi-tenant application where each tenant needs isolated data, a singleton would cause data to bleed between tenants.

Alternative: Use dependency injection to pass different instances to different parts of your app. Each component receives the specific instance it needs through its constructor or a service locator.

// Instead of singleton
class UserRepository {
  final DatabaseConnection db;
  UserRepository(this.db); 
}

// Usage
final dbForTenantA = DatabaseConnection(tenantId: 'A');
final dbForTenantB = DatabaseConnection(tenantId: 'B');
final repoA = UserRepository(dbForTenantA);
final repoB = UserRepository(dbForTenantB);

Your architecture avoids shared global state

Modern architectural patterns like BLoC, Provider, or Riverpod in Flutter specifically aim to avoid global mutable state. Singletons work against these patterns by reintroducing global state.

Alternative: Use state management solutions designed for Flutter. Provider, Riverpod, BLoC, or GetX offer better ways to share data across your app while maintaining testability and avoiding tight coupling.

// Using Provider instead of singleton
class AppConfig {
  final String apiUrl;
  AppConfig(this.apiUrl);
}

// Provide it at the top level
void main() {
  runApp(
    Provider<AppConfig>(
      create: (_) => AppConfig('https://api.example.com'),
      child: MyApp(),
    ),
  );
}

// Access it anywhere in the widget tree
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final config = Provider.of<AppConfig>(context);

  }
}

It forces tight coupling between unrelated classes

When multiple unrelated classes depend on the same singleton, they become indirectly coupled. Changes to the singleton affect all these classes, making the codebase fragile and hard to refactor.

Alternative: Use interfaces and dependency injection. Define what behavior you need through an interface, then inject implementations. This way, classes depend on abstractions, not concrete singletons.

// Define an interface
abstract class Logger {
  void log(String message);
}

// Implementation
class ConsoleLogger implements Logger {
  @override
  void log(String message) => print(message);
}

// Classes depend on the interface, not a singleton
class PaymentService {
  final Logger logger;
  PaymentService(this.logger);

  void processPayment() {
    logger.log('Processing payment');
  }
}

// Easy to test with mock
class MockLogger implements Logger {
  List<String> logs = [];
  @override
  void log(String message) => logs.add(message);
}

You need clean, isolated testing

Singletons maintain state between tests, causing test pollution where one test affects another. This makes tests unreliable and order-dependent.

Alternative: Use dependency injection and create fresh instances for each test. Most testing frameworks support this pattern, allowing you to inject mocks or fakes easily.

// Testable code
class OrderService {
  final PaymentProcessor processor;
  OrderService(this.processor);
}

// In tests
void main() {
  test('processes order successfully', () {
    final mockProcessor = MockPaymentProcessor();
    final service = OrderService(mockProcessor); 

  });
}

General Guidelines

Use singletons sparingly and only when you truly need exactly one instance of something for the entire application lifecycle. Good candidates include logging systems, application-level configuration, and hardware interface managers.

For most other cases, prefer dependency injection, state management solutions, or simply passing instances where needed. These approaches make your code more flexible, testable, and maintainable.

Conclusion

The Singleton pattern is a powerful creational tool, but like every tool, you should use it strategically.

Overusing singletons can make apps tightly coupled, hard to test, and less maintainable.

But when used correctly, the Singleton pattern helps you save memory, enforce consistency, and control object lifecycle beautifully.

The key is understanding your specific use case and choosing the right implementation approach – whether eager, lazy, or factory-based – that best serves your application's needs while maintaining clean, testable code.

Now imagine you hit the same Like button, but it takes its sweet time in making the server call, performing the DB updates, and getting you the response back to update the state of the Like button.

Which experience would you like the most? You are most likely to select the first scenario. We all love “instant feedback”. The magic of instant feedback is powered by a pattern called the Optimistic UI Pattern.

In this article, we will uncover:

• What does Optimistic UI really mean?

• Why does it massively improve the user experience?

• How does React 19’s new useOptimistic() hook make it easier than ever?

• How to implement a real-world scenario using the Optimistic Pattern

• A bunch of use cases where you will be able to use this pattern.

By the end, you will be proactively thinking of using this design pattern to improve the UX of your project.

This article is also available as a video tutorial as part of the 15 Days of React Design Patterns initiative. Please check it out.

Table of Contents

1. What is Optimistic UI?

2. How Does it Work Under the Hood?

3. How to Build an Optimistic Like Button

4. The Pitfalls and Anti-Patterns

5. 15 Days of React Design Patterns

6. Before We End...

What is Optimistic UI?

Optimistic UI (also known as optimistic updates) is a pattern that helps you update the UI immediately, assuming the server operation will succeed, and if it later fails, you roll back the UI to the correct state.

Instead of waiting for the round-trip of the client request, database write, server response, and then the UI render, the UI just updates instantly. This dramatically increases what’s called the perceived speed. The user of the application perceives the UI update as instant – but the actual operation may take place in the background.

Without an Optimistic Update:

If you’re not using the optimistic pattern, it’s just a traditional client-server mechanism, where:

• At the client side, a user interacts with a UI element.

• An async call (request) is made to the server.

• The server processes the request and may make DB updates.

• On a successful case, the server sends back the response to the client.

• The client updates the relevant UI.

• In an error case, the server sends back the error response to the client.

• The client informs the user about the error.

In this case, the user has to wait for the success/failure of the request to perceive any change after their interaction. This wait is neither uniform nor optimal. It may vary based on the network speed, network latency, and deployment strategies of the application.

With an Optimistic Update:

When you’re using an optimistic update, here’s how things go:

• At the client side, a user interacts with a UI element.

• The UI gets updated instantly, and the user perceives the feedback immediately.

• In parallel, in the background, the client initiates the server call.

• The server processes the request and may make DB updates.

• On a successful case, the server doesn’t do anything else, as the UI has been updated already, assuming this call will succeed.

• In an error case, the server sends back the error response to the client.

• The client rolls back the eager, optimistic UI update it made.

In this case, the user doesn’t wait for the server round-trip to complete before the UI is updated. It’s much faster, assuming that, in most cases, the parallel server call will succeed.

With this comparison, we can now understand why Optimistic Updates matter in modern UI.

• It improves perceived speed

• It keeps users engaged

• It eliminates the awkward feelings like “Did my click work?”

And so on. Optimistic updates are critical for real-time feeling features like chat messages, likes, comments, cart updates, poll votes, collaborative editing, and more. Even AI-driven apps that take time to respond benefit from optimistic placeholders like “Thinking…”, “Sending…” and so on.

How Does it Work Under the Hood?

Under the hood, there are actually two states:

1. The Actual State: This is the actual source of truth. This data should be in sync with the server.

2. The Optimistic State: This is temporary and instantly shown to the user.

When the server request succeeds, do nothing. Your optimistic state is now correct. If the server request fails, perform a rollback, and return UI the actual state.

React 19 introduced a built-in hook to help with this pattern called useOptimistic() . In the next section, we will take a deep dive into it with code and working internals.

The useOptimistic() Hook in React 19

useOptimistic() is a React hook introduced in React 19 to help with optimistic updates. The syntax and usage of the hook go like this:

const [optimisticState, addOptimistic] = useOptimistic(state, updateFn);

When an async action is underway, the useOptimistic() hook allows you to show different states.

It accepts:

1. currentState: your real source of truth (useState, Redux, server state, and so on)

2. updateFn: a pure function that says how to compute the optimistic value

It returns:

1. optimisticState: the temporary UI state

2. addOptimisticUpdate(input): function you call to apply immediate updates

Take a look at the picture below. It shows the relationship between the current state and the optimistic state clearly:

Here’s what’s going on there:

1. We pass the current state and an updater function to the useOptimistic hook.

2. The updater function takes the current state and a user input to compute and return the next optimistic state.

3. The input to the updater function is supplied using the addOptimistic(input) function.

4. Finally, the optimistic state value is used in the component.

Let’s now build something exciting using this hook to understand its internals better.

How to Build an Optimistic Like Button

We will be building the Like button functionality optimistically. The flow will be like this:

• The user clicks on the Like button.

• We update the Like button’s state immediately and optimistically.

• In parallel, we send the server call to persist the value into the DB (we will simulate it)

• Then we handle any error scenarios.

First, let’s simulate a network call to the server using JavaScript’s Promise object and the setTimeout() web API:

// simulate a network call to the Server
async function sendLikeToServer(postId) {
    await new Promise((r) => setTimeout(r, 700));

    if (Math.random() < 0.2) throw new Error("Network failed");
    console.log(`Sent a like for the post id ${postId}`);
    return { success: true };
}

The sendLikeToServer function takes a post ID as a parameter and simulates a fake network call using a Promise and a delay of 700 ms. It pretends to submit a request to the server to persist a post’s likes value.

To make it a bit more realistic, we have created a random error. The function will throw an error randomly so that we can understand the rollback scenario as well.

Next, we will create the real source of truth, the actual state for the Like count:

const [likes, setLikes] = useState(initialLikes);

Then, create the optimistic state value with the useOptimistic() hook:

 const [optimisticLikes, addOptimisticLike] = useOptimistic(
        likes, (currentLikes, delta) => currentLikes + delta);

Let’s understand this declaration well:

• We have passed the actual state value (likes) and the updater function to the useOptimistic() hook.

• Take a look at the updater function, (currentLikes, delta) => currentLikes + delta. It’s an arrow function that gets the current like value and a delta. It returns the sum of the current like value and the delta. The return value logic is your own business logic. For incrementing the like count, it makes sense to increase the current like value by a delta value (of 1).

• Now, the question is, how do we get this delta value? Who passes it? That’s where the return values of useOptimistic() come in handy. The addOptimisticLike is a function through which we can pass that delta value. How? Let’s take a look.

When someone clicks on the Like button, we need to handle the click event and increase the like count value. So here is a handleLike() function which does that:

const handleLike = async () => {
        addOptimisticLike(1);
        try {
            await sendLikeToServer(postId);
            setLikes((prev) => prev + 1);
        } catch (err) {
            console.error("Like failed:", err);
            setLikes((s) => s); 
        }
};

A lot is happening here:

• We call the addOptimisticLike() function with a delta value of 1. This call will ensure that the updater function (currentLikes, delta) => currentLikes + delta of the useOptimistic() will be called. The return value will be set to the optimistic state, that is, optimisticLikes.

• This optimistic state value we use in the JSX. So we can see the increased like count immediately.

• Then we make the fake server call, and also update the actual state, provided the server call was successful.

• In case of an error, the control goes into the catch-block, where we roll back the likes value to the previous one. This will also sync the optimistic state’s value with a rollback.

Here is the complete code of the LikeButton component:

import { startTransition, useOptimistic, useState } from "react";

// simulate a network call to the Server
async function sendLikeToServer(postId) {
    await new Promise((r) => setTimeout(r, 700));

    if (Math.random() < 0.2) throw new Error("Network failed");
    console.log(`Sent a like for the post id ${postId}`);
    return { success: true };
}

// The Like Button Component
export default function LikeButton({ postId, initialLikes = 0 }) {
    // the "real" source of truth for likes (committed)
    const [likes, setLikes] = useState(initialLikes);
    // optimistic state and updater function
    const [optimisticLikes, addOptimisticLike] = useOptimistic(
        likes,
        (currentLikes, delta) => currentLikes + delta
    );

    const handleLike = async () => {
        // 1) Apply optimistic change *immediately*
        addOptimisticLike(1);

        // 2) Start server call in low priority to avoid blocking UI

        try {
            await sendLikeToServer(postId);
            // On success, commit the real state update:
            // IMPORTANT: update the real state so optimistic snapshot eventually matches
            setLikes((prev) => prev + 1);
        } catch (err) {
            // On error, rollback the real state (or trigger a refetch)
            // Because we never incremented likes (real), just leave likes unchanged
            // But we should show an error to user:
            console.error("Like failed:", err);
            // Optionally: show toast or set an error state
            // And — to force the optimistic view to refresh and reflect real state,
            // call setLikes to current value
            setLikes((s) => s); // no-op but will cause optimistic to reflect the
                                // committed value Or you can trigger a re-fetch of the 
                                // post state
        }
    };

    return (
        <div className="flex">
            <button onClick={handleLike}>❤️ {optimisticLikes}</button>
            <button onClick={() => startTransition(async () => handleLike())}>
                ❤️ {optimisticLikes}
            </button>
        </div>
    );
}

Have you noticed that we have wrapped the handleLike() call with the startTransition?

Without this, React gives us a warning:

“An optimistic state update occurred outside a transition or action.”

This is because optimistic updates are low-priority visual updates, not critical ones.

Using startTransition() ensures that:

• React doesn’t block rendering

• We do not get the warning

• We get a smooth, optimistic experience

The transitions are part of React’s concurrency model that helps us improve the performance of React applications. If you are interested in learning various performance optimisation techniques, here is a two-part guide for you.

The Pitfalls and Anti-Patterns

With any design pattern, we need to be aware of possible pitfalls, misuses, and anti-patterns. Here are a few things you should be aware of:

• Don’t assume that the server call will be successful. Network failure will happen, and you need to have a way to roll back. Rollback is the heart of optimistic UI. Omitting the rollback logic will cause adverse consequences.

• Don’t try hiding the bad UX behind optimistic updates. The Optimistic UI is not a fix or replacement for poor designs.

• Don’t perform any expensive work in optimistic updates. Keep the optimistic updater function lean, pure, and fast.

15 Days of React Design Patterns

I have some great news for you: after my 40 days of the JavaScript initiative, I have now started a brand new initiative called 15 Days of React Design Patterns.

If you enjoyed learning from this article, I am sure you will love this series, featuring the 15+ most important React design patterns. Check it out and join for FREE:

Before We End...

That’s all! I hope you found this article insightful. You can find all the source code used in this tutorial on the tapaScript GitHub.

Let’s connect:

• Subscribe to my YouTube Channel.

• Grab the React Hooks Cheatsheet.

• Follow on LinkedIn if you don't want to miss the daily dose of up-skilling tips.

• Join my Discord Server, and let’s learn together.

• Subscribe to my fortnightly newsletter, The Commit Log.

See you soon with my next article. Until then, please take care of yourself and keep learning.

You go in with the calm confidence of a developer who just wants to understand how things work. You open BluetoothAdapter.java and think, “Ah, this looks clean.” Then you click through a few methods. Suddenly, you’re in AdapterService.java, then StateMachine.java, and before you realize it, you’re staring at a JNI bridge leading straight into native C++ code that talks to daemons with names like bluetoothd.

Somewhere between the Binder calls, message queues, and “Unexpected state” logs, your curiosity quietly turns into existential dread.

That, my friend, is the Android Bluetooth experience.

But here’s the twist: it’s not chaos. It’s choreography. Every message, callback, and native call exists for a reason. Android Bluetooth has been built, rebuilt, and evolved over more than a decade to support everything from old-school car kits to cutting-edge LE Audio.

Underneath that ever-expanding complexity lies a remarkably disciplined foundation built on system design patterns. These patterns are the reason Bluetooth can still work across thousands of devices, dozens of chip vendors, and millions of random user interactions that happen every second.

What’s fascinating is how the Bluetooth stack mirrors Android’s entire design philosophy: isolate complexity, define clear roles, and let components communicate through predictable contracts.

The app layer talks to managers. The managers talk to services. The services talk to native daemons. And the daemons finally talk to the hardware. Each layer speaks its own language but follows a shared rhythm –like musicians who have never met but somehow stay in tune.

Without these patterns, the system would collapse under its own ambition. Imagine writing logic for pairing, bonding, discovery, connection, streaming, and low-energy data transfer without structure. Every change would be a minefield.

Design patterns bring sanity to this chaos.

• The Manager-Service split ensures clear boundaries.

• The State Machine keeps connection lifecycles predictable.

• The Handler-Looper mechanism turns concurrency into an orderly queue.

• The Facade hides native messiness behind friendly APIs.

• And the Observer pattern lets everyone stay updated without tripping over each other.

This article is about peeling back those layers and seeing the design ideas that quietly keep Android Bluetooth alive. We won’t just list patterns like a textbook. Instead, we’ll explore how each one appears in real AOSP code, why it exists, and how you can apply the same ideas to your own projects.

If you’ve ever wondered how something as temperamental as Bluetooth manages to stay mostly reliable, this is your backstage pass.

So grab your debugger, open a terminal window, and get ready to look at Bluetooth not as a mysterious black box, but as one of Android’s most elegant examples of long-term system design done right.

Table of Contents

1. The Manager–Service Pattern: Divide and Delegate

2. The Facade Pattern: Making Complexity Look Simple

3. The State Machine Pattern: Keeping Bluetooth Sane

4. The Handler–Looper Pattern: Message-Driven Concurrency

5. The Observer Pattern: When Bluetooth Talks Back

6. The Builder Pattern: Making GATT Bearable

7. The Strategy Pattern: Adapting to Different Devices

8. The Template Method Pattern: Common Flows, Custom Details

9. The Service Locator Pattern: Finding the Right Profile at Runtime

10. The Layered Architecture Pattern: From App to Radio Without Losing the Plot

11. Putting It All Together: Designing Bluetooth-Style Systems

The Manager–Service Pattern: Divide and Delegate

When you start exploring Android’s Bluetooth codebase, one of the first things you’ll notice is how often you come across the words “Manager” and “Service.” There is BluetoothManagerService, AdapterService, GattService, A2dpService, and many more.

At first, it seems repetitive and unnecessarily complicated. Why do we need so many layers just to connect to a pair of earbuds? Wouldn’t one class that says “connect” be enough? The short answer is no. The longer answer involves one of Android’s most reliable architectural habits: the separation of responsibility.

Think of a restaurant. The customers talk to the waiter. The waiter talks to the kitchen. The kitchen talks to suppliers. Everyone has a job. The waiter doesn’t need to know how to cook, and the chef doesn’t need to explain menu prices to customers. That separation is what keeps the whole operation smooth and manageable.

Android’s Bluetooth system works in exactly the same way. The Manager is like the waiter, the public face that interacts with apps, while the Service is like the kitchen, where the actual work happens out of sight.

When you write an app that uses Bluetooth, you might call something like BluetoothAdapter.enable() or BluetoothDevice.connectGatt(). These methods live inside Manager classes in the Android framework. They are deliberately simple, because their only job is to talk to the Bluetooth Service behind the scenes. That Service runs in another process entirely, one that has the necessary system permissions and the ability to interact with the native Bluetooth stack and hardware.

A small example from the Android source code shows this relationship very clearly:

public class BluetoothManagerService extends IBluetoothManager.Stub {
    private AdapterService mAdapterService;

    public boolean enable() {
        if (mAdapterService != null) {
            return mAdapterService.enable();
        }
        return false;
    }
}

At first glance, this looks trivial, but it demonstrates one of the most important ideas in the system. The BluetoothManagerService does not handle radio operations itself. Instead, it delegates to another internal class called AdapterService, which communicates with lower layers. That service will eventually pass instructions down to native C++ code, which then communicates with the Bluetooth controller chip through the Host Controller Interface.

This relay-style design has several advantages. The first is reliability. If the lower-level service crashes, the Manager layer can detect it and restart it, keeping the system stable. Because the Manager and the Service live in separate processes, your app will not crash when the service does. You might see Bluetooth temporarily toggle off and on again, but that recovery is intentional and automatic.

The second advantage is security. Every Bluetooth action goes through permission checks in the Manager layer before it reaches the Service. If an app without proper privileges tries to perform a restricted operation, the Manager stops it immediately. This prevents unsafe or malicious behavior and ensures that only trusted system components can access the hardware.

The third is flexibility. The Service layer can evolve without affecting the public API. That means Google and device manufacturers can modify or replace internal Bluetooth logic say, to support a new chipset or feature, without breaking existing apps. The Manager acts as a contract that remains stable even if the internal wiring changes.

If you trace what happens when you tap the Bluetooth toggle on your phone, you can see this pattern in action. Your tap calls BluetoothAdapter.enable() in the app layer. That call travels to BluetoothManagerService in the system server process. The manager checks permissions, then calls AdapterService.enable(). Inside the service, a JNI bridge triggers a native C++ function called enableNative(), which finally sends a command to the hardware abstraction layer. From there, it reaches the Bluetooth chip itself. Each layer knows its exact role.

This organization also makes debugging easier. If something goes wrong, you can tell whether it’s the Manager that didn’t send a message, the Service that failed to respond, or the native stack that stopped working. Each part logs its own activity in logcat, so you can follow the chain of events without guessing where the problem began.

At its core, the Manager–Service pattern is Android’s way of keeping large systems under control. It divides authority, enforces security, and lets the entire Bluetooth subsystem recover gracefully from errors. It may look complicated at first, but it is this design that makes Bluetooth remarkably resilient. Every time your phone connects to your car or your earbuds, it happens through this carefully choreographed handoff between the Manager and the Service. It’s a quiet partnership that keeps billions of connections running smoothly every single day.

The Facade Pattern: Making Complexity Look Simple

If the Manager–Service pattern is about dividing responsibility, the Facade pattern is about hiding chaos behind elegance. In many ways, this is the reason most Android developers can use Bluetooth without needing to understand what happens inside the stack.

The Facade pattern provides a friendly public face that masks a labyrinth of underlying operations, creating an illusion of simplicity while managing a tremendous amount of behind-the-scenes work.

To understand this, think about the front desk of a large hotel. When you check in, you talk to one receptionist. That person gives you your key, answers questions, and takes requests. You never meet the maintenance crew fixing the air conditioning or the kitchen staff preparing food or the team handling room cleaning schedules. Yet all those systems quietly operate through that one friendly front desk.

That front desk is the Facade. It provides a simple interface to a complex system, ensuring guests never have to deal with the hotel’s internal machinery.

Android’s Bluetooth framework works in the same way. Developers interact with high-level classes such as BluetoothAdapter, BluetoothDevice, and BluetoothGatt. These classes are the front desks of the Bluetooth system. They provide clean, easy-to-use APIs like enable(), getBondedDevices(), and connectGatt().

When a developer calls one of these methods, it looks straightforward. But beneath the surface, that call passes through multiple layers of services, IPC mechanisms, and native components before reaching the Bluetooth controller hardware.

Here is a simplified example to illustrate how this works in practice:

BluetoothGatt gatt = device.connectGatt(context, false, callback);

This single line looks simple. But in reality, it triggers an entire orchestra of operations. The call goes through the BluetoothDevice class, which forwards the request to BluetoothGatt. The BluetoothGatt instance then communicates with the system’s Bluetooth service through Binder IPC. That service eventually invokes native code that sets up an L2CAP channel, negotiates attributes, configures encryption, and starts the Generic Attribute Profile (GATT) procedure. None of that complexity is visible to the developer who wrote the original line.

This is what makes the Facade pattern so powerful. It provides abstraction without removing capability. The Android team knows that very few app developers want to worry about connection intervals, PHY configurations, or attribute protocol responses. They just want to connect to a device and get data. By exposing a Facade, Android lets developers stay productive while the internal layers handle the technical details.

If you look at the Android source tree, you can see this pattern clearly in how Bluetooth is organized. The classes in the android.bluetooth package are intentionally designed to be simple and self-contained. They never reveal how the system service works.

For example, BluetoothAdapter doesn’t know how to send HCI commands, and BluetoothGatt doesn’t know how to open a socket. Instead, they act as representatives, forwarding user requests to the Bluetooth Manager or the corresponding Service, which then interacts with the native stack.

This pattern is what makes the Bluetooth API approachable to beginners. Imagine if Android exposed every detail of the underlying protocols to developers. You would have to manually construct attribute requests, negotiate connection intervals, and handle packet fragmentation. The result would be technically accurate but completely unusable for most app developers. The Facade prevents that by serving as a translation layer between human expectations and machine complexity.

There is also a deeper design reason behind this approach. A Facade protects stability. Because developers only see the outermost layer, Android engineers can modify the internals without breaking existing apps. This allows the system to evolve freely, improving performance and adding new features while keeping the public API consistent.

The Bluetooth internals have changed countless times since the early days of Android, but BluetoothAdapter.startDiscovery() still works the same way it did a decade ago. That consistency is a direct benefit of the Facade pattern.

In a sense, the Facade pattern is about empathy. It respects the developer’s time by not forcing them to learn every Bluetooth nuance. It makes working with a complicated protocol feel human. Whether you are scanning for nearby devices, connecting to a smartwatch, or transferring data, you only need to call a few readable methods and handle a handful of callbacks. Behind those calls, a world of threads, sockets, and packet exchanges whirs silently to life, all hidden behind a calm, minimal interface.

So the next time you call BluetoothAdapter.enable() and your phone’s Bluetooth magically comes to life, remember that you are not flipping a simple switch. You are sending a message through a carefully designed Facade that talks to multiple services, native layers, and hardware interfaces. It is like pressing a single button on a spaceship console while a thousand mechanical parts start moving in perfect synchronization. You don’t see the complexity, and that is precisely the point.

The State Machine Pattern: Keeping Bluetooth Sane

If you have ever debugged Bluetooth connections, you have probably experienced moments of pure confusion. One minute the device says “Connecting,” then suddenly it jumps to “Connected,” then “Disconnected,” then “Connecting” again, and before you know it, you have no idea what the current state actually is.

Bluetooth is, by nature, an unpredictable environment. Devices move in and out of range, radio interference causes delays, and remote devices can behave differently depending on their chipsets. To make sense of all this unpredictability, Android relies on one of the most battle-tested concepts in computer science: the State Machine pattern.

A state machine is like a rulebook that defines how a system behaves depending on its current situation. Instead of reacting randomly to every event, the system maintains a clear notion of “state.”

For Bluetooth, these states might include Disconnected, Connecting, Connected, or Disconnecting. Each state knows exactly what actions are allowed and what transitions are possible.

For example, you can only go from Disconnected to Connecting when a connection attempt starts, and you can only go from Connecting to Connected if the handshake succeeds. If something happens that does not make sense for the current state, the system simply ignores it. This structure prevents chaos.

In Android’s Bluetooth implementation, almost every major profile uses a state machine. You can find them in classes like A2dpStateMachine.java and HeadsetStateMachine.java. Each one extends a generic StateMachine framework that Android provides. The structure is surprisingly elegant. You define individual classes for each state, implement their behaviors, and let the system handle the transitions. Conceptually, it looks like this:

class A2dpStateMachine extends StateMachine {
    private final State mDisconnected = new Disconnected();
    private final State mConnecting = new Connecting();
    private final State mConnected = new Connected();

    A2dpStateMachine() {
        addState(mDisconnected);
        addState(mConnecting);
        addState(mConnected);
        setInitialState(mDisconnected);
    }
}

Although the code may look technical, the idea is simple. Each “State” represents a specific mode of operation, and each one defines how to react to incoming events.

The system starts in Disconnected. When a “connect” command arrives, it moves to Connecting. When the connection completes, it moves to Connected. If the user turns off Bluetooth or the remote device disappears, it transitions back to Disconnected. Every action follows a logical, well-defined path.

This pattern is what keeps Bluetooth stable despite the messy nature of wireless communication. Without it, you would constantly end up with half-open connections, dangling callbacks, and undefined behaviors. Imagine a phone that still thinks it’s connected to your headphones long after you have turned them off. The state machine eliminates that by keeping a single source of truth for connection status.

Beyond correctness, the state machine pattern also improves readability and maintenance. Each state is self-contained, so developers can easily locate the logic that handles a particular situation. If you need to change how Bluetooth behaves when connecting, you only modify the Connecting class, not the entire codebase. This modularity makes the Bluetooth stack easier to evolve as new profiles and features appear.

There is also a subtle psychological benefit to using state machines. When debugging, engineers can trace log messages that indicate transitions, such as “A2dpStateMachine: Transitioning from CONNECTING to CONNECTED.” These logs act like a map of the system’s thought process. Instead of guessing what happened, you can follow a clear narrative of cause and effect. That is invaluable in a system as complex as Bluetooth, where timing issues can hide bugs that are otherwise impossible to reproduce.

State machines also ensure graceful recovery. Suppose a connection fails halfway through. Without structured states, the system might leave resources allocated or callbacks registered. But with a state machine, the Connecting state knows how to clean up before returning to Disconnected. This reduces leaks, power drain, and inconsistent user experiences.

Even at higher levels of Android, you can see the influence of this pattern. For example, when you toggle Bluetooth on or off, the adapter itself transitions through a sequence of states internally: Turning On, On, Turning Off, Off. This ensures that all dependent services, such as GATT and A2DP, are brought up or down in the right order. The pattern guarantees that nothing jumps ahead or lags behind during these transitions.

In everyday terms, the state machine pattern is like traffic lights for Bluetooth. It prevents every component from driving through the intersection at the same time. Each action has a green, yellow, or red light depending on the current situation. This orderliness is what keeps Bluetooth from descending into radio chaos every time multiple devices try to connect or disconnect at once.

So, the next time your phone automatically reconnects to your headphones after a short disconnection, remember that it is not luck. It is a carefully choreographed set of state transitions keeping track of where everything stands. Behind every smooth Bluetooth experience lies a quiet but dependable state machine making sure each event happens exactly when it should and never when it shouldn’t.

The Handler–Looper Pattern: Message-Driven Concurrency

If Bluetooth had a personality, it would be that friend who cannot sit still. It’s constantly juggling tasks: scanning for devices, maintaining connections, handling GATT operations, streaming audio, and sending data to the controller, all at once. Underneath that hustle is one of Android’s most reliable design foundations: the Handler–Looper pattern. This pattern is what keeps Bluetooth responsive, synchronized, and stable even when a dozen things happen at the same time.

To understand why it exists, imagine running a busy coffee shop with only one employee who tries to handle every customer request immediately. One person takes an order, makes the drink, cleans the counter, and washes the cups all in real time. Within minutes, chaos erupts. Customers start yelling, the counter gets sticky, and no one knows who’s being served.

Now, imagine a more organized system: every order goes into a queue, and the barista processes them one by one. That’s essentially how the Handler–Looper system works.

In Android, almost everything that involves background work happens through message queues. The Looper represents a thread that waits for messages, and the Handler is the entity that posts those messages into the queue.

Instead of letting different threads modify shared Bluetooth state directly, which could easily lead to race conditions, Android forces all Bluetooth operations to happen on specific threads managed by loopers. Messages arrive, get handled in order, and the system never loses track of what happened first or last.

Inside the Bluetooth system, this pattern appears everywhere. Each service, such as AdapterService, GattService, or A2dpService, has its own Handler running on a dedicated thread. When a Bluetooth event occurs, like “Device Connected” or “Start Discovery,” the event is wrapped in a Message object and sent to the appropriate Handler. That Handler then decides what to do next. The pattern turns what could have been a tangle of multithreaded chaos into a clear, sequential pipeline.

Here’s a simplified example inspired by Android’s real Bluetooth code:

private class AdapterServiceHandler extends Handler {
    @Override
    public void handleMessage(Message msg) {
        switch (msg.what) {
            case MSG_START_DISCOVERY:
                startDiscoveryNative();
                break;
            case MSG_STOP_DISCOVERY:
                stopDiscoveryNative();
                break;
        }
    }
}

This code might look plain, but it’s quietly doing something brilliant. Instead of running startDiscoveryNative() directly, the system posts a message saying, “Hey, when you get a chance, start discovery.” The Looper thread eventually picks up that message and executes it in the correct order. No two threads ever collide, and the main thread stays free to handle user interactions.

The beauty of this approach lies in its predictability. Bluetooth events often happen in unpredictable sequences: a connection attempt might fail while a scan is still in progress, or a new device might appear while another is being paired. Without strict message ordering, these overlaps could lead to deadlocks or inconsistent states. By channeling every operation through a single message queue, Android ensures that Bluetooth behaves deterministically, no matter how chaotic the radio environment becomes.

It also helps with thread safety. Instead of sprinkling locks everywhere in the code, Android simply guarantees that all critical Bluetooth work happens on the same thread. This means developers can focus on logic instead of worrying about synchronization bugs. It’s one of those design choices that looks simple but saves thousands of hours of debugging across devices and vendors.

There’s another hidden benefit too: graceful recovery. If something goes wrong inside a message handler, say a native call fails or a timeout occurs, the system can isolate that failure to a single message. The rest of the queue continues processing normally. This containment prevents one bad operation from crashing the entire Bluetooth stack.

When you watch logcat during a Bluetooth session, you can often see the Handler–Looper pattern in action. You’ll find lines like “MSG_START_DISCOVERY received” followed by “Starting discovery” and “MSG_STOP_DISCOVERY received.” Those logs are more than just printouts – they are breadcrumbs showing the system’s thought process as it moves through the queue.

In simpler terms, the Handler–Looper pattern is how Android Bluetooth keeps its cool. It takes a storm of asynchronous events, pairing requests, advertisements, data packets, disconnections, and lines them up in a single, calm queue. It ensures that everything happens in order, every time.

So, the next time your phone seamlessly switches from one Bluetooth speaker to another while still streaming music and scanning for your watch in the background, remember what’s quietly at work beneath it all. There’s a dedicated thread looping patiently, reading messages, and keeping order in a world of wireless chaos. It’s the unsung hero of concurrency, one message at a time.

The Observer Pattern: When Bluetooth Talks Back

Bluetooth is a chatterbox. It never works alone, and is always reacting to something. A device connects, another disconnects, a new advertisement appears, a bond is created, or a characteristic changes its value. The system needs to keep dozens of components informed about these changes in real time.

This is where the Observer pattern comes in. This pattern is all about communication, letting different parts of the system stay updated without constantly asking what’s going on.

The basic idea is simple. You have one source of truth that broadcasts updates, and you have multiple listeners that care about those updates. Whenever the source changes, it notifies everyone who subscribed. It’s like a news channel that sends breaking alerts to subscribers instead of waiting for each viewer to call in and ask, “Anything new today?”

In Android Bluetooth, this is how almost all notifications and callbacks are delivered. When your phone connects to a Bluetooth device, the Bluetooth system service sends out an event. The app doesn’t have to keep checking the connection status every second. Instead, it simply registers a listener that reacts whenever the connection state changes. That listener could be a BroadcastReceiver in the app or a callback interface provided by the framework.

For example, when a device connects, Android sends out a broadcast intent like this:

sendBroadcast(new Intent(BluetoothDevice.ACTION_ACL_CONNECTED));

Apps that have registered for this intent receive it automatically. They can then update their user interface, show a notification, or start another operation based on the new state. The same mechanism works for disconnections, bonding events, and discovery results. It’s an elegant way of keeping apps informed without them wasting energy by constantly polling the system.

At the GATT level, the Observer pattern takes a slightly different form. When you connect to a Bluetooth Low Energy device and subscribe to a characteristic, you provide a callback called BluetoothGattCallback. This callback has methods such as onConnectionStateChange() and onCharacteristicChanged(). Whenever the device sends new data, the system automatically invokes the appropriate callback on your behalf. You don’t need to ask for updates repeatedly – you simply react when they arrive.

The real beauty of this pattern is how decoupled it makes the system. The Bluetooth framework can notify multiple apps and services simultaneously without knowing anything about how they use the information. It just broadcasts an event and moves on. Each listener independently decides what to do with it.

This design is crucial for a multitasking operating system like Android, where Bluetooth events may be relevant to different components at the same time. For example, the system settings might need to update the connection icon, the media framework might need to route audio, and an app might need to sync data — all triggered by the same connection event.

The Observer pattern also helps with efficiency. Because updates are sent only when something changes, there is no unnecessary processing or battery drain from constant status checks. This design allows the Bluetooth stack to stay responsive while minimizing overhead, which is especially important for mobile devices that need to preserve both power and performance.

In practical terms, this pattern is what makes Bluetooth feel alive. When you open your Bluetooth settings and instantly see your device name appear or disappear, that’s the result of observers doing their job. They are always listening for broadcasts and updating the interface the moment something changes. Without this mechanism, your Bluetooth menu would lag or require manual refreshing just to stay current.

There is also a subtle reliability benefit. Observers can join or leave at any time without breaking the system. If one app crashes or unregisters its listener, others still receive updates normally. This flexibility ensures that the Bluetooth service remains stable even if individual apps behave unpredictably.

So, the next time your phone pops up a notification that your earbuds have connected or your smartwatch silently syncs in the background, remember that it is not magic. It’s the Observer pattern at work: a polite messaging system that lets Bluetooth quietly talk to everyone who is listening, all without raising its voice.

The Builder Pattern: Making GATT Bearable

If you have ever worked with Bluetooth Low Energy, you already know that the GATT layer can be a maze. The Generic Attribute Profile, or GATT, is how devices expose data to one another. It defines services, characteristics, and descriptors that describe everything from a heart rate monitor’s readings to a light bulb’s brightness. On paper, it’s beautifully organized. In practice, setting it up manually can feel like assembling furniture without instructions, using only an Allen key and pure faith.

When Android engineers designed the Bluetooth GATT APIs, they realized that developers would need a way to build these services and characteristics without losing their minds. That is where the Builder pattern comes in. This pattern is all about constructing complex objects step by step, instead of trying to do everything in one chaotic go.

Think of it like building a sandwich. You start with a base, then add layers: bread, sauce, lettuce, tomato, cheese, and so on. You can add or skip ingredients as needed, and by the end, you have a complete meal that makes sense.

The Builder pattern works the same way. It lets you create a GATT service one piece at a time, adding characteristics and descriptors in a readable, modular fashion.

In Android, a GATT service is represented by the BluetoothGattService class, and each piece of data it exposes is represented by a BluetoothGattCharacteristic. Instead of requiring you to manually wire all of these together in one long, confusing block, Android allows you to build them step by step, like this:

BluetoothGattService service = new BluetoothGattService(SERVICE_UUID,
        BluetoothGattService.SERVICE_TYPE_PRIMARY);

BluetoothGattCharacteristic characteristic =
        new BluetoothGattCharacteristic(CHAR_UUID,
                BluetoothGattCharacteristic.PROPERTY_READ | BluetoothGattCharacteristic.PROPERTY_WRITE,
                BluetoothGattCharacteristic.PERMISSION_READ | BluetoothGattCharacteristic.PERMISSION_WRITE);

service.addCharacteristic(characteristic);

Even though this looks simple, it reflects a powerful design philosophy. Each method call adds a new layer of configuration without breaking readability. You can look at the code and instantly understand what kind of service you’re creating, what characteristics it contains, and what permissions each one has. There are no massive constructors, no messy parameter lists, and no confusion about what goes where.

This pattern does more than make code pretty. It also prevents errors. GATT structures are very sensitive to incorrect configurations, for example if a characteristic lacks the right permission or if a descriptor is missing. By breaking the setup into small, incremental steps, the Builder pattern helps developers validate each part as they go. It’s much easier to debug a missing characteristic when each one is clearly defined, rather than buried inside a giant, monolithic block of code.

The same idea applies internally within the Android Bluetooth stack. When the system builds its own GATT tables or processes client requests, it follows the same step-by-step assembly model. Each stage of the process adds more detail to the overall structure. The result is not only easier to read but also more robust in handling changes.

There is also a psychological benefit to this approach. Developers can focus on one small piece at a time instead of feeling overwhelmed by the entire setup. It feels like progress, and it reduces the cognitive load that often comes with working on protocols like GATT, where small mistakes can cause big headaches.

In a broader sense, the Builder pattern in Android Bluetooth is a lesson in humility. It acknowledges that complex systems are built incrementally, not in one heroic line of code. It invites you to slow down, define what you need clearly, and construct it carefully. Whether you are setting up a health monitor or designing a custom BLE sensor, the Builder pattern ensures that your code remains clear and maintainable as your project grows.

So the next time you define a Bluetooth service in your app and everything just works, take a moment to appreciate the quiet genius of the Builder pattern. It’s the reason you can build an entire wireless data model with a few readable lines instead of a spaghetti of function calls. It turns the intimidating world of GATT into something almost enjoyable, a reminder that even in low-level systems programming, design elegance still matters.

The Strategy Pattern: Adapting to Different Devices

Bluetooth, as anyone who has worked with it knows, is not one single, predictable standard in practice. It’s more like a family reunion where every cousin claims to follow the same rules but each one interprets them differently. One device might handle extended advertising perfectly, another insists on using legacy commands, and yet another behaves strangely when it comes to pairing.

In this unpredictable world, Android cannot rely on one fixed set of behaviors. It needs a system that can adapt depending on what kind of device or chipset it is dealing with. This is where the Strategy pattern quietly saves the day.

The Strategy pattern is all about flexibility. It allows a system to choose between multiple approaches at runtime depending on the situation. Instead of writing huge if-else blocks to handle every possible scenario, developers define a common interface that represents a behavior, and then create different implementations of that behavior. The system can then pick the right strategy dynamically.

Imagine you are a chef who must cook for guests with different dietary preferences. You don’t rewrite the entire recipe each time someone says they are vegan or gluten-free. Instead, you have multiple cooking strategies, one for each diet, and you simply pick the right one when the order comes in. Android does the same thing with Bluetooth.

Inside the Bluetooth stack, different devices and chipsets support different capabilities. Some controllers can handle multiple advertising sets, some cannot. Some prefer extended packet formats, while others only understand the older legacy commands. To manage this diversity without making the code unreadable, Android uses interchangeable strategies.

For example, when the system needs to start Bluetooth advertising, it doesn’t hard-code every possible hardware path. Instead, it defines an abstract interface, something like:

interface AdvertisingStrategy {
    void startAdvertising();
    void stopAdvertising();
}

Then it provides specific implementations for each scenario, such as a LegacyAdvertisingStrategy and an ExtendedAdvertisingStrategy. Depending on the chipset capabilities, the system decides which strategy to use at runtime:

AdvertisingStrategy strategy = controller.supportsExtendedAdvertising()
        ? new ExtendedAdvertisingStrategy()
        : new LegacyAdvertisingStrategy();
strategy.startAdvertising();

This design keeps the code clean and extensible. If a new Bluetooth version introduces a new advertising method, developers can simply implement another strategy class without touching the existing ones. The same approach appears in connection handling, power management, and even encryption policies.

The Strategy pattern also allows for graceful fallback. Suppose a modern device supports extended advertising but something goes wrong, maybe the controller firmware has a bug. Instead of crashing, the system can quietly switch back to the legacy strategy. Users never notice the change, and Bluetooth continues working.

Beyond hardware adaptability, this pattern also simplifies testing. Developers can easily substitute one strategy with another in unit tests to simulate different hardware configurations. It encourages modularity, which is crucial for a system that runs across hundreds of Android devices made by dozens of manufacturers.

You can also see the philosophical elegance in how this pattern aligns with Bluetooth itself. The Bluetooth protocol is inherently designed for negotiation. Devices exchange capabilities, choose compatible settings, and then proceed. Android’s software architecture mirrors that philosophy at the code level. By using strategies, it lets the system negotiate internally too, not between devices, but between code paths.

From a practical standpoint, the Strategy pattern gives Android the superpower of evolution. As new Bluetooth versions emerge with new features like LE Audio, Isochronous Channels, or Periodic Advertising, Android can keep up simply by introducing new strategy classes. There is no need to overhaul the entire system or rewrite large chunks of legacy logic.

So when your phone seamlessly connects to both a five-year-old Bluetooth speaker and a brand-new pair of earbuds using LE Audio, it’s not luck. It is design. Underneath the surface, Android is quietly picking the right strategy for each device, making the whole experience look effortless. It’s one of those cases where smart architecture turns what could have been a compatibility nightmare into a smooth, invisible handshake between hardware generations.

The Template Method Pattern: Common Flows, Custom Details

In large systems like Android Bluetooth, not every part of the code can be entirely unique. Some operations follow the same general flow every time, but with small variations in the details. For example, connecting to a device, discovering services, or streaming audio all share similar high-level steps.

The pattern that allows Android to reuse these general flows while still letting each Bluetooth profile define its own personality is the Template Method pattern.

The essence of this pattern is simple: define the overall process once, but let subclasses decide how specific parts should behave. It’s like giving every chef in a restaurant the same recipe outline – prepare ingredients, cook, and plate – but letting each of them choose their own spices and techniques for flavor. The structure remains constant, but the details can vary.

Bluetooth needs this because different profiles, such as A2DP for audio or GATT for data exchange, often perform similar actions in slightly different ways. They all start connections, maintain states, and handle disconnections, but the way they handle timing, acknowledgments, or retries can differ. The Template Method pattern keeps these flows consistent while allowing room for customization.

Inside Android’s Bluetooth stack, you can see this pattern in how connection management is implemented. The process of connecting to a Bluetooth device typically follows the same structure: initialize the stack, attempt a connection, verify success, and then notify other components. Each profile, however, defines its own way of handling the lower-level details.

In conceptual form, it looks something like this:

abstract class BluetoothProfileConnection {
    public final void connect() {
        prepareConnection();
        performConnection();
        finalizeConnection();
    }

    protected abstract void prepareConnection();
    protected abstract void performConnection();
    protected abstract void finalizeConnection();
}

A class such as A2dpService or GattService would then implement the abstract methods in its own way. One might set up audio channels, while another negotiates attribute protocols. The overall template (prepare, perform, finalize) never changes. This is what keeps the Bluetooth system organized even when dozens of profiles coexist and evolve over time.

This pattern is particularly useful in a codebase as large as Android’s because it enforces discipline without killing flexibility. It ensures that every Bluetooth operation follows the same skeleton, which makes debugging and extending the system far easier. When an engineer wants to add a new feature or fix a connection bug, they already know where to look and which parts are shared or unique.

Another advantage of the Template Method pattern is that it reduces duplication. Without it, each profile might write its own version of “connect,” “disconnect,” and “reconnect,” each slightly different but doing almost the same thing. That would make the code hard to maintain and error-prone. With a template, the core logic lives in one place, and only the necessary variations appear in subclasses.

There is also an important design insight here: Bluetooth, like many communication protocols, is inherently procedural. You must do things in the correct order, initialize before connecting, connect before discovering, and discover before reading data. The Template Method pattern encodes this order directly into the architecture. It prevents accidental mistakes, such as skipping a required step or performing actions out of sequence.

From a broader perspective, this pattern teaches an important engineering lesson about balance. Too much abstraction, and systems become rigid and bureaucratic. Too little structure, and they turn into chaos. The Template Method pattern sits comfortably in the middle. It provides consistency while still leaving space for creativity and variation.

So the next time your phone connects to your car, switches to the right Bluetooth profile, and starts playing music without skipping a beat, you’ll know that there is a quiet choreography happening inside. Each profile follows the same dance steps – prepare, perform, and finalize – but each does it in its own rhythm. That harmony between structure and flexibility is what makes Bluetooth both powerful and adaptable.

The Service Locator Pattern: Finding the Right Profile at Runtime

At this point, we have seen how Android Bluetooth manages complexity through delegation, structure, and controlled flexibility. But there is still a practical question to answer: with so many Bluetooth services and profiles running in the system (like A2DP, GATT, HFP, MAP, HID, and more), how does the framework know which one to talk to at any given moment? When you stream audio, it needs A2DP. When you sync contacts, it needs PBAP. When you connect a keyboard, it needs HID. Android’s answer to this problem is the Service Locator pattern.

In the simplest terms, the Service Locator is a central registry that helps different parts of a system find the service or component they need without having to know where it lives. It’s like the information desk at a large airport. You don’t need to memorize the location of every gate or airline office – you just ask the information desk, and they point you to the right place.

Inside the Android Bluetooth system, this pattern appears everywhere, especially within the AdapterService and BluetoothManagerService classes. These services manage a variety of Bluetooth profiles, and each profile is responsible for its own behavior. Instead of hard-coding every possible profile into every part of the stack, Android maintains a registry where each service can be looked up dynamically.

Here is a simplified version of what this looks like conceptually:

public class AdapterService {
    private Map<Integer, ProfileService> mProfileServices = new HashMap<>();

    public void registerProfile(int profileId, ProfileService service) {
        mProfileServices.put(profileId, service);
    }

    public ProfileService getProfileService(int profileId) {
        return mProfileServices.get(profileId);
    }
}

When a Bluetooth operation occurs, such as starting audio streaming or initiating a data transfer, the system asks the AdapterService for the correct profile implementation. The Service Locator then returns the matching service instance, such as the A2DP service for audio or the GATT service for BLE data. Each profile operates independently, but the Service Locator acts as the phonebook that ties them all together.

This pattern solves several key problems. First, it removes the need for every part of the system to know about every other part. Without it, each class would have to keep track of dozens of others, creating a tangled web of dependencies. With a Service Locator, everything becomes more modular. Each component can register itself once and be discovered whenever needed.

Second, it makes the system flexible. Android devices can enable or disable certain Bluetooth profiles depending on hardware support or user configuration. For example, a smartwatch might only need GATT, while a car infotainment system needs A2DP, HFP, and MAP. The Service Locator allows Android to load only the relevant profiles at runtime instead of baking them all in permanently.

Third, it helps with scalability. As new Bluetooth profiles are introduced, such as LE Audio or Broadcast Audio, they can be added without rewriting existing code. The Service Locator acts as the central meeting point that stays the same even as new services join the system. It’s like a well-organized switchboard that never needs rewiring, no matter how many new phones, watches, or speakers show up.

From a debugging standpoint, this design also makes life easier. Developers can trace which service is currently active or verify that a profile is registered correctly simply by inspecting the registry. It provides a single source of truth that reflects the system’s state at any moment.

On a philosophical level, the Service Locator pattern represents Android’s pragmatic approach to complexity. Instead of trying to make every module aware of the entire Bluetooth world, it centralizes coordination in a controlled, predictable way. It acknowledges that Bluetooth is not a single, monolithic feature but an ecosystem of cooperating components that need a shared directory to find each other efficiently.

So when your phone automatically switches from streaming audio over A2DP to transferring a file over OBEX or syncing notifications with your smartwatch, it happens seamlessly because the system always knows exactly which profile to use. That knowledge comes from the quiet work of the Service Locator pattern, acting like a backstage coordinator ensuring that the right performer walks on stage at the right time.

The Layered Architecture Pattern: From App to Radio Without Losing the Plot

If there is one pattern that truly defines Android’s Bluetooth design philosophy, it is Layered Architecture. This is the invisible backbone that keeps the entire system structured, predictable, and scalable. In a world where Bluetooth involves everything from mobile apps to kernel drivers, layering is not just a matter of organization, but one of survival.

At first glance, Bluetooth might seem like a single feature. You turn it on, pair a device, and it works. But in reality, it’s a long, intricate journey that starts at the app layer, where you press “Connect”, and travels all the way down to the radio hardware, which emits electromagnetic signals into the air. Between those two points lies an entire vertical stack of software layers, each playing a distinct role, each isolated from the others by well-defined interfaces.

Think of it as a city with multiple levels. The top layer is where people live and work: that’s your app. Below that are roads and traffic systems, which are your Android framework services. Beneath that, you have subways and utilities, the native daemons written in C and C++ that handle protocol specifics. At the very bottom is the foundation, the hardware abstraction layer and the Bluetooth controller chip itself. Every level has a clear boundary. You can remodel one floor without collapsing the whole building.

Here is how those layers roughly line up in Android’s Bluetooth stack.

At the top layer, app developers interact with classes such as BluetoothAdapter, BluetoothDevice, and BluetoothGatt. These are part of the Android framework, written in Java or Kotlin, and serve as the public interface. They provide clean, stable methods like startDiscovery() and connectGatt(), hiding the technical chaos below.

The next layer down is the system service layer. This includes classes such as BluetoothManagerService and AdapterService. These are responsible for managing Bluetooth as a system feature, enforcing permissions, and coordinating multiple profiles. They act as the brain of the operation, processing commands, routing messages, and maintaining global state.

Below that is the JNI and native layer, written primarily in C and C++. This is where the logic gets closer to the metal. JNI (Java Native Interface) acts as a translator between the Java world and the native code. When a Java method like enable() is called, JNI forwards it to the native daemon that actually speaks Bluetooth protocol commands. This bridge keeps performance high while maintaining safety through strict boundaries.

Finally, we reach the hardware abstraction layer (HAL) and the Bluetooth controller. The HAL defines how the operating system interacts with the underlying hardware. It sends and receives HCI (Host Controller Interface) packets, the low-level binary messages that control the Bluetooth chip. From there, the controller takes over, turning digital instructions into radio signals that travel invisibly through the air to another device.

The brilliance of this design is in how each layer only needs to know about the one directly below it. The app layer never worries about the hardware, and the hardware never needs to know about the app. This clear separation makes it possible for Android to run across thousands of devices built by different manufacturers using different chipsets. It is a pattern that enforces order through boundaries.

There are practical benefits, too. The layered architecture makes the system modular. For instance, when new Bluetooth features arrive, like LE Audio or Bluetooth 5.4, Android engineers can modify only the relevant layers. The app APIs at the top can remain stable while the lower layers evolve to support the new specifications. This is how Android manages to maintain backward compatibility while still introducing new capabilities with every release.

The layering also helps with debugging and reliability. When something breaks, engineers can trace the issue by moving down through the layers like a detective. If an app crashes, the problem is likely near the top. If packets are missing, the issue may be in the native layer or HAL. Each layer leaves its own signature in the logs, helping developers pinpoint where things went wrong.

This pattern also teaches a timeless software design lesson: complexity becomes manageable only when divided. The layered architecture prevents the Bluetooth stack from turning into a tangled mess of cross-dependencies. It lets Android evolve gracefully rather than collapse under the weight of its own history.

So when you tap “Pair new device” on your phone and watch your earbuds connect, remember that your request travels down a carefully organized highway of software, from the app you see, through the framework, into native code, across the hardware abstraction, and finally out into the air as a radio signal. Every piece knows its role, every layer does its part, and together they make Bluetooth feel effortless. The magic of wireless connection is not just in the radio waves, but in the architecture that makes those waves behave.

Putting It All Together: Designing Bluetooth-Style Systems

By now, it’s easy to see that Android’s Bluetooth stack is not just a pile of random services and classes. It’s a carefully choreographed system built on timeless design principles that keep it reliable, flexible, and surprisingly elegant despite its complexity.

Each pattern – the Manager–Service split, the Facade, the State Machine, the Handler–Looper, the Observer, the Builder, the Strategy, the Template Method, the Service Locator, and the Layered Architecture – exists for a reason. Together, they form the invisible scaffolding that allows Bluetooth to connect billions of devices every day without falling apart.

The magic of these patterns is not that they make Bluetooth simple. Bluetooth will never be simple, as it’s an enormous specification with quirks, edge cases, and competing priorities. What these patterns do instead is make the system manageable. They turn unpredictability into structure, they replace chaos with order, and they make it possible for teams of engineers around the world to work on the same stack without tripping over each other.

If you step back, you’ll notice that every pattern in the Bluetooth system reflects a deeper philosophy:

• The Manager–Service pattern teaches the value of separation.

• The Facade reminds us that good design hides unnecessary complexity.

• The State Machine shows the power of predictability.

• The Handler–Looper demonstrates the beauty of serialized concurrency.

• The Observer proves that communication doesn’t require coupling.

• The Builder celebrates incremental construction.

• The Strategy encourages adaptability.

• The Template Method enforces discipline without rigidity.

• The Service Locator maintains organization in a crowded ecosystem.

• And the Layered Architecture ties it all together, ensuring that every piece fits logically into the whole.

These same ideas extend far beyond Bluetooth. You can apply them to almost any software system, a web service, a game engine, or even a simple mobile app. The principles remain the same: divide responsibilities, enforce clear boundaries, keep your interfaces stable, and design for change rather than permanence.

Systems that last are not the ones that are perfect on day one. They are the ones that can grow without collapsing under their own weight.

Android Bluetooth has been evolving for more than a decade. It has absorbed new technologies like LE Audio, Fast Pair, and broadcast audio. It has adapted to new hardware, new chipsets, and new use cases. Yet, at its core, the same patterns continue to guide it. That consistency is the reason Bluetooth on Android, despite its quirks, works as well as it does. It’s not just a story of wireless communication, it’s a story of good architecture.

So the next time you tap “Connect” on your phone and your earbuds instantly respond, pause for a moment. Beneath that single tap lies an orchestra of design patterns working in perfect harmony: managers delegating to services, handlers processing messages, observers reacting to broadcasts, and strategies choosing the right behavior for your hardware. It’s a quiet miracle of software design, a reminder that even the most invisible features on your device are built with care, patience, and an eye for long-term evolution.

And if you ever find yourself building a complex system that seems impossible to manage, take a cue from Android Bluetooth. Start small, define your layers, choose the right patterns, and let structure do the heavy lifting. The real magic in engineering isn’t in writing clever code. It’s in designing systems that stay calm, even when the world around them isn’t.

If you happen to shout out “Yes!” to the above, you’re not alone. It’s a common feeling among many React developers across the globe. But React itself is not responsible for any of these issues. These situations arise because of code smells like:

• Props drilled six levels down.

• A single bloated component doing everything.

• Logic that’s duplicated across different components.

• Careless rendering (and re-rendering) causing performance issues.

A Code Smell doesn’t mean broken code. Rather, it’s an indication that the code may work now, but is difficult to maintain, reuse, scale, and much harder to debug.

And that’s exactly where we need to use Design Patterns. They’re well-tested solutions to the various code smell problems that developers have been encountering for decades. When you know how to use them well, you achieve a clean, maintainable codebase that is easy to enhance, debug, and scale.

Today, we will take a deep dive into one of the most prominent design patterns in React called the Compound Components Pattern. This pattern saves React developers from passing a long list of props and helps build composable user interface components.

This is going to be a complete hands-on tutorial. So get your favourite code editor ready, and let’s get started. This article is also available as a video tutorial as part of the 15 Days of React Design Patterns initiative. Please check it out.

Table of Contents

1. React 19 Code Set Up

2. A Messy Modal Component

3. The Problems with this messy Modal Component

4. The Compound Components Pattern

5. How to Build a Modal Component using the Compound Components Pattern

   • Why Didn’t We Create Separate Files for the SubComponents?

   • How to Use the Modal Component

   • How to build an Accordion Component using the Compound Components Pattern

   • Add the Accordion to the Modal

6. The Use Cases

7. The Pitfalls and Anti-Patterns

8. 15 Days of React Design Patterns

9. Before We End...

React 19 Code Set Up

The best way to understand how to apply a design pattern is by refactoring messy code with code smells to improve it to cleaner code. So let’s set up a coding ground so that we can start putting in our messy code first, and then go about applying the design pattern to it.

Note: you can find all the source code used in this tutorial on the tapaScript GitHub. Feel free to follow along with it side by side.

Also, make sure you have Node.js installed (preferably v18+). You can check it out by typing this command on your terminal/command prompt:

node -v

If you get an output with the installed Node.js version, you are all set. Otherwise, just download and install Node.js from here.

Now, run this command in your terminal to create a React 19 project scaffolding:

npx degit atapas/code-in-react-19#main compound-components-pattern

It will create a folder called compound-components-pattern with the Vite-based React project files under it. Now, change the directory using this command:

cd compound-components-pattern

Then install the dependencies using this command:

npm install ## Or, yarn install, or pnpm install, etc,

Now, you can import the project folder into your favourite code editor (I use VS Code).

Finally, to start the project locally, use the following command:

npm run dev ## Or, yarn dev, or pnpm dev

Now the project should be running locally and should be accessible on the default URL, http://localhost:5173. You can access the URL in your browser. Now we’re all set to start coding.

A Messy Modal Component

Let’s get started by creating a Modal component. Start by creating a directory called messy under the src/ directory. Now, create a file called Modal.jsx under src/messy/ with the following code snippet:

function Modal({ title, body, primaryAction, secondaryAction }) {
    return (
        <div className="modal-backdrop">
            <div className="modal-container">
                <h2 className="modal-header">{title}</h2>
                <p className="modal-body">{body}</p>
                <div className="modal-footer">
                    {secondaryAction}
                    {primaryAction}
                </div>
            </div>
        </div>
    );
}

export default Modal;

This is a simple React implementation of a modal component that accepts a title, body, and a couple of actions as props to render them as a modal.

• The title: The header title of the modal.

• The body: The modal content.

• The primaryAction: An action button like delete, create, save, and so on to place in the footer section of the modal.

• The secondaryAction: An action button like cancel, close, and so on to place in the footer section of the modal.

Next, open the App.jsx file and replace the existing code with the following code snippet:

import Modal from "./messy/Modal";

import "./App.css";

function App() {
    return (
        <div className="flex flex-col items-center">
            <Modal
                title="Delete Account"
                body="Are you sure you want to delete your account?"
                primaryAction={<button>Delete</button>}
                secondaryAction={<button>Cancel</button>} />
        </div>
    );
}

export default App;

Here, we have imported the Modal component and used it by passing its props values. Go to the browser tab and access the app’s URL. You should see the modal appearing like this:

Well, as it doesn’t look like a traditional modal with a backdrop and all, so let’s fix that using CSS. Open the App.css and paste the following CSS styles into it and save it:

.modal-backdrop {
    position: fixed;
    inset: 0;
    background: rgba(0, 0, 0, 0.5);
    display: flex;
    justify-content: center;
    align-items: center;
}
.modal-container {
    background: white;
    border-radius: 8px;
    padding: 1rem;
    width: 400px;
    position: relative;
}
.modal-header {
    font-weight: bold;
    margin-bottom: 1rem;
}
.modal-footer {
    display: flex;
    justify-content: flex-end;
    gap: 0.5rem;
    margin-top: 1rem;
}
.modal-close {
    position: absolute;
    top: 8px;
    right: 8px;
    background: none;
    border: none;
    font-size: 1.2rem;
}

Great! Now you have a cool-looking modal dialog asking for your confirmation to delete your account.

The Problems with This Messy Modal Component

Question for you: What problems do you think this modal implementation might have?

Let’s find the answers:

1. Lack of Flexibility: The modal has a rigid structure that dictates exactly what it renders. What if you want a modal without a title? Or a modal with a custom layout? Or more than two action buttons? You need to write additional logic and pass additional props every time you think of enhancing the modal for another use case. These changes in the component will bring maintainability issues and increase code smell.

2. Mixed Responsibilities: The modal tries to do multiple things. It handles both layout and content. This violates the separation of concerns principle that we learn from other design patterns, such as the Container-Presenter Pattern.

3. Hard Reusability: The modal lacks reusability due to its rigidness. Right now, if you want a modal with this:

    <h2>Something Wrong!</h2>
    <img src="warning.png" />
    <p>Something went wrong. please see the logs for more details.</p>
   

   You can not reuse this component, and you will end up creating a new one.

4. Poor Scalability: The modal component is not scalable. Think, for example, if you’re creating a component library and you end up creating multiple modal instances like ConfirmationModal, InfoModal, FormModal, ImageModal, and so on. It would be a huge ding on the scalability of that component library to create and maintain every new version of the modal.

5. Hard to Test: This modal implementation is hard to test due to its tight coupling with props.

With these issues in mind, let’s welcome the compound components pattern and see how it can help us solve them.

The Compound Components Pattern

Compound Components Pattern in React is a design pattern where a parent component works together with its child components to share an implicit state and behaviour. Instead of passing a long list of props, the parent manages the state and exposes flexible child components (<Modal.Header>, <Modal.Body>, <Modal.Footer>, and so on) so that consumers can compose the UI naturally, just like using native HTML elements.

Think of Compound Composition Pattern like LEGO blocks.

• The parent component is like the LEGO base plate.

• The child components are the LEGO blocks (door, window, roof, and so on).

• You don’t pass any props to the base plate, saying, “add a door here, add a window there.” Instead, you simply place the pieces where you want them.

• The base plate (parent) still provides the rules and structure (studs, alignment, stability), but you get the flexibility to assemble your model however you like.

Got it? That’s the power of compound components. It’s a flexible composition with a shared state/behaviour underneath.

Let’s now refactor our messy (and smelly) modal component by applying the compound components pattern.

How to Build a Modal Component Using the Compound Components Pattern

Create a folder called with-pattern under the src/ folder. We will arrange and maintain the modal component, and in the future, an accordion component under this new folder.

Next, create a folder called modal under the src/with-pattern. Finally, create a file called Modal.jsx with the following code snippet:

// File Location: src/with-pattern/modal/Modal.jsx

const Modal = ({ children, isOpen, onClose }) => {
    if(!isOpen) return null;
    return (
        <div className="modal-backdrop">
            <div className="modal-container">
                {children}
                <button className="modal-close" onClick={onClose}>
                    ✖
                </button>
            </div>

        </div>
    );
};

function ModalHeader({ children }) {
    return <div className="modal-header">{children}</div>;
}

function ModalBody({ children }) {
    return <div className="modal-body">{children}</div>;
}

function ModalFooter({ children }) {
    return <div className="modal-footer">{children}</div>;
}

Modal.Header = ModalHeader;
Modal.Body = ModalBody;
Modal.Footer = ModalFooter;

export default Modal;

Let me break it down for you:

• First, focus on the Modal component above. It doesn’t take title, body, and so on as props anymore. Rather, it accepts children, a special prop in React to pass any HTML elements, a group of HTMLs, JSX, or even a React component. It brings flexibility that we are no longer fixed to any particular structure to pass to the Modal component.

• The JSX of the Modal component just renders the children prop as is, giving the entire power to the consumer of the Modal component to pass any structure it’s willing to. The Modal component uses the backdrop and container style to dictate the basic look and feel of a modal.

• The Modal’s JSX also has a button to close the modal by clicking on an x. To open and close the modal, we have passed two additional props, isOpen and onClose. You can imagine isOpen is a state value that the consumer of this modal uses to open the modal, and the onClose is a function that sets the value of the isOpen to false to close the modal.

• Then, we have defined three more components, ModalHeader, ModalBody, and ModalFooter which are equally flexible to accept any legit HTML structure or React component through the children prop. Now you can pass anything to render to the modal header. The same goes for the body and footer as well.

• Next, we add the header, body, and footer as the subcomponents to the Modal component.

    Modal.Header = ModalHeader;
    Modal.Body = ModalBody;
    Modal.Footer = ModalFooter;
  

• Finally, we exported the Modal component.

Why Didn’t We Create Separate Files for the SubComponents?

This question is quite natural. In general, we follow the standard practice of one component in one source file(.jsx/.tsx). Here, we seem to be breaking that rule…so are we? Actually not.

The golden rules are:

• The subcomponents (ModalHeader, ModalBody, and ModalFooter) are only meaningful in the context of Modal. They don’t have (or need) any existence beyond the modal.

• They are small helper components that you don’t expect to reuse anywhere else.

• Keeping them together is good for discoverability and is safe from potential misuse that we’ll discuss in the pitfalls section later.

How to Use the Modal Component

So we’re sorted. Let’s now learn how to use this Modal component and see how it can bring flexibility, reusability, scalability, and testability.

Open the App.jsx file and replace the content of it with the following code snippet:

import { useState } from "react";
// import Modal from "./messy/Modal";
import Modal from "./with-pattern/modal/Modal";

import "./App.css";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="flex flex-col items-center">

      <button onClick={() => setIsOpen(true)}>Open Modal</button>

      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>

        <Modal.Header>
          <h2>Welcome!</h2>
        </Modal.Header>

        <Modal.Body>
          <p>
              This is a modal built with the Compound Component
              pattern.
          </p>
        </Modal.Body>

        <Modal.Footer>
          <button>Help!</button>
          <button onClick={() => setIsOpen(false)}>Close</button>
          <button onClick={() => alert("Action Performed!")}>Do Action</button>
        </Modal.Footer>

      </Modal>

    </div>
  );
}

export default App;

Check out how we have passed a bunch of JSX inside <Modal>…</Modal> as the children. It’s so powerful. We’re passing the subcomponents header, body, and footer in the sequence we want them to appear in the modal.

Next, if we look into the <ModalHeader>, <ModalBody>, or <ModalFooter> components, we can again pass anything as children to them. For example, the <ModalFooter /> can now take three buttons (in fact, anything else) based on the needs.

We can compose the components like Lego blocks to build the kind of Modal that we wish to. You don't need to have different components to represent different kinds of modals now. This single component can cater to all your modal needs without introducing any props soup drama.

We have a button to open the modal, and the App.jsx component manages a state called isOpen to tackle the opening and closing of the modal.

You should be able to see these changes now in the browser. Click on the open modal button.

The modal dialog opens up with all the content we have passed to it.

It’s a big leap towards achieving clean code to use the compound components design pattern. Now that you’re familiar with the basics, let’s quickly do another classic implementation of this pattern by building an Accordion component.

How to Build an Accordion Component Using the Compound Components Pattern

An accordion component is an array of Accordion Items. It’s a combination of a header and body that shows and hides the content when users click on the header.

Create a folder called accordion under src/with-pattern folder. Now, create a file called Accordion.jsx inside the src/with-pattern/accordion with the following code snippet:

import { useState } from "react";

function Accordion({ children }) {
  return <div className="accordion">{children}</div>;
}

function AccordionItem({ title, children }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="accordion-item">
      <button className="accordion-title" onClick={() => setIsOpen(!isOpen)}>
        {title}
      </button>
      {isOpen && <div className="accordion-content">{children}</div>}
    </div>
  );
}

// Attach subcomponents
Accordion.Item = AccordionItem;

export default Accordion;

Here,

• We have followed the same pattern as we did for the modal previously. We have an Accordion component that takes a special prop called children, enabling the Accordion to accept any HTML/JSX/React component and render it.

• Then we defined the AccordionItem. It takes two props: the title to create the header, and the special prop called children to form the accordion content flexibly.

• The header is formed using the button that is driven by a state called isOpen to show/hide the content area.

• The content area of an AccordionItem could be anything: a paragraph, a table, an image, or even a JSX combining them.

• Finally, we have added the AccordionItem as the subcomponent to the Accordion component.

To make the accordion look better, let’s add a few styles. Open the App.css file and add these styles at the end of the file:

.accordion-item {
    margin-bottom: 0.5rem;
    border: 1px solid #ddd;
    border-radius: 4px;
}
.accordion-title {
    width: 100%;
    text-align: left;
    padding: 0.5rem;
    font-weight: bold;
    cursor: pointer;
    background: #f9f9f9;
    border: none;
}
.accordion-content {
    padding: 0.5rem;
    background: #fff;
}

Great, let’s now use the Accordion component. Create a new file called AccordionDemo.jsx under the folder src/with-pattern/accordion with the following code snippet:

import Accordion from "./Accordion";

export default function AccordionDemo() {
  return (
    <Accordion>
      <Accordion.Item title="What is Compound Component Pattern?">
        It’s a React pattern that allows parent and child components to work
        together seamlessly while giving developers flexible composition.
      </Accordion.Item>

      <Accordion.Item title="Why use it?">
        It makes UI libraries like modals, tabs, accordions, menus, etc. easier
        to build and use.
      </Accordion.Item>

      <Accordion.Item title="Pitfalls?">
        Overusing it can lead to deeply nested structures or make things harder
        to debug if not documented well.
      </Accordion.Item>
    </Accordion>
  );
}

Check out how the Accordion component can accept a bunch of AccordionItem components. You can also create an array of AccordionItem components and pass them dynamically to the Accordion component.

Each of the AccordionItem components accepts the title prop value, and we passed the text as the children. If needed, you can pass any other valid JSX as a child. That’s amazing!

Add the Accordion to the Modal

Now, let’s take the usage of this pattern to the next level. How about using the AccordionDemo inside the Modal component? Can we do it without changing the Modal component?

Oh yes! Remember, the Modal component accepts any JSX as children, and so does the ModalBody component. So we can just import the AccordionDemo component into the App.jsx file and use it inside the <Modal.Body>…</Modal.Body> as shown below, right?

import { useState } from "react";
// import Modal from "./messy/Modal";
import Modal from "./with-pattern/modal/Modal";

import AccordionDemo from "./with-pattern/accordion/AccordionDemo";

import "./App.css";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="flex flex-col items-center">

      <button onClick={() => setIsOpen(true)}>Open Modal</button>

      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>

        <Modal.Header>
          <h2>Welcome!</h2>
        </Modal.Header>

        <Modal.Body>
          <p>
              This is a modal built with the Compound Component
              pattern.
          </p>
          <AccordionDemo />
        </Modal.Body>

        <Modal.Footer>
          <button>Help!</button>
          <button onClick={() => setIsOpen(false)}>Close</button>
          <button onClick={() => alert("Action Performed!")}>Do Action</button>
        </Modal.Footer>
      </Modal>

    </div>
  );
}

export default App;

Now, if you run the app with these code changes, you should see the accordion appearing inside the modal. You will also be able to show/hide the accordion content and open/close the modal. This means their individual states are intact as expected.

The Use Cases

So far, we have seen a couple of important usages of the Compound Components pattern with modal and accordion. Similarly, you can use this pattern to build reusable components like:

• Tables (Table.Head, Table.Body, Table.Row).

• Any component where layout and nesting matter.

Also, if you’re ever writing your own component library or design system, this pattern is a must. If you need some inspiration, look at ShadCN, Material UI, or Radix UI. They all do this.

The Pitfalls and Anti-Patterns

As you know, with great power comes great responsibility. And with patterns comes the pitfalls and anti-patterns you’ll need to be aware of. When you’re using the compound components pattern, just make sure that you:

• Don’t attach subcomponents randomly. They should belong to the parent semantically.

• Avoid re-exporting subcomponents separately. It will be a disaster if someone uses the ModalFooter without a Modal. What if the ModalFooter changes tomorrow in the context of the Modal, and the other consumers are not in need/aware of that change?

• Don’t attempt to make everything in the compound components pattern. The rule of thumb is, only use it when the children's structure matters, and you want to keep it flexible.

15 Days of React Design Patterns

I have some great news for you! After the 40 days of the JavaScript initiative, I have now started a brand new initiative called 15 Days of React Design Patterns.

If you enjoyed learning from this article, I am sure you will love this series, featuring the 15 most important React design patterns. Check it out and join.

Before We End...

That’s all! I hope you found this article insightful.

Let’s connect:

• Subscribe to my YouTube Channel.

• Subscribe to my fortnightly newsletter, The Commit Log.

• Follow on LinkedIn if you don't want to miss the daily dose of up-skilling tips.

• Join my Discord Server, and let’s learn together.

See you soon with my next article. Until then, please take care of yourself and keep learning.

A design pattern attempts to describe an effective solution to the problem in a generic way so that it can be applied to a specific set of circumstances.

I will use Java to build an example of each pattern. I’m assuming that you have some programming experience in Java. In particular, you should be (at least somewhat) familiar with the concepts of inheritance and polymorphism. These design patterns really show the power of inheritance and polymorphism, so if you are just learning about these topics this is a great opportunity to dig deeper.

What if you not a Java programmer? If you are familiar with any Object-Oriented language you will probably still get a lot out of the examples. Give it a shot!

Code Playbacks

To make design patterns more approachable, I developed an interactive tutorial that uses annotated code playbacks to walk through key design pattern features step-by-step.

Each design pattern is presented as a code playback that shows how a program changes over time along with my explanation about what's happening. This format helps you focus on the reasoning behind the code changes.

You can access the free 'book' of code playbacks here:

OO Design Patterns with Java, by Mark Mahoney (that’s me)

To view a code playback, click on the comments in the left panel. Each comment updates the code in the editor and highlights any changes. Read the explanation and study the code. If you get stuck, use the AI assistant like a tutor to help explain what is happening in the code.

For more information about code playbacks, you can watch a short demo here.

Key Design Patterns You Should Know

Strategy Pattern

The Strategy Pattern is used to define a 'family' of algorithms, encapsulate each one, and make them interchangeable. Software developers use the Strategy pattern when they know there are many different ways of accomplishing some behavior. Rather than include all the different ways in a single class, they separate them out into individual classes and plug them in when necessary.

This program creates some classes to hold student grades. Some instructors like to adjust the entire course’s grades to make them higher. Some instructors do this by dropping every student's lowest grade. Other instructors 'curve' each assignment. Since there are several different options, I will use the Strategy Pattern to isolate them and let the client choose which one they prefer.

Start by looking at the Assignment, Student, and Course classes. Once you are familiar with the core classes, watch as I change the code to implement two different approaches to curving the grades using the Strategy Pattern:

Strategy Pattern Adjusting Grades in a Course

Singleton Pattern

There are times when you need to make sure there is only one instance of a class and it is accessible everywhere in your code. This is the problem that the Singleton Pattern solves.

In this program, I will create a class that generates random numbers. I will rely on Java's built-in Random class but will be able to reproduce the exact same sequence of random numbers when in 'test mode'. I'll make sure that there is only one instance of this random number generator using the Singleton Pattern:

Singleton Pattern A Testable Random Number Class

Composite Pattern

Often, we’ll create whole/part containment tree structures. For example, in a file system there are simple files. I call these simple elements, primitives. We can group primitives together to form larger composites. Files can be grouped into directories. These composites (directories) can be grouped into still larger composites, and so on.

We could treat composites and primitives differently. But it often makes sense to treat them the same. Having to distinguish between the object types makes the application more complex.

The Composite Pattern describes how to use recursive composition so that clients don't need to make this distinction.

This program creates classes for printing a hierarchical collection of files and directories using the Composite Pattern:

Composite Pattern Displaying a Hierarchical File System

Decorator Pattern

Sometimes we want to add responsibilities to individual objects, not an entire class. The Decorator Pattern allows us to create decorators to provide a flexible alternative to inheritance for extending a class.

In this program, I create an interface for logging messages while a program is running. I use the interface to create a ConsoleLogger that prints the log messages to the screen. Then I start to add decorator objects that surround, or wrap, the ConsoleLogger. I add decorators to attach the date, author name, and time to the log messages using the Decorator Pattern:

Decorator Pattern Logging with Decorators

State Pattern

Sometimes there are systems that react differently based on the 'state' that they are in. A state is a period of time during which a system will react to events according to certain rules. This state-based behavior is implemented using the State Pattern.

I’ll show you how to move through the characters in a string and parse it to account for quotes within it. For example, the following string:

"hamburgers chips 'hot dogs' pickles 'french fries'"

can be split into a collection like this:

["hamburgers", "chips", "hot dogs", "pickles", "french fries"]

There are may ways to accomplish this in Java, but I’ll show a state-based approach. When a single quote is encountered within a string I will use that as an event and move between different states using the State Pattern:

State Pattern String Splitting for Search Bars

Observer Pattern

The Observer Pattern is used when the update of a single piece of data in one object needs to be propagated to a collection of other objects.

For example, when the value of a cell in a spreadsheet changes, several other cells may need to be notified of that change so that they can update themselves. Similarly, in a social network application when a user makes a post, all of their friends need to be notified so that their feeds can be updated. Both of these are essentially the same problem that the Observer Pattern solves.

This program creates a class to hold a time in a day called MyTime. Then I create two different types of Observers that will be notified when the time changes. The two observers will re-display the time every time it changes using the Observer Pattern:

Observer Pattern Observing the Time Change

Proxy Pattern

Sometimes we design a set of objects that have a client/server relationship but later decide that the two objects should not interact directly. This program shows how to use the Proxy Pattern to place some new functionality in between two previously cooperating classes.

I create a Card and Deck class for card games. The Deck starts out being hosted on the same machine as the Driver. Then I split the Driver and the Deck class so that they can be run on different machines using the Proxy Pattern:

Proxy Pattern Dealing Cards from a Remote Deck

Factory Pattern

The Factory Pattern provides a mechanism for creating 'families' of related objects without specifying their concrete classes. Instantiating concrete objects in an application makes it hard to change those objects later.

In this program, I will create two different families of classes for a help system for two different computing platforms using the Factory Pattern:

Factory Pattern Getting Help in Mac and Windows

Visitor Pattern

The Visitor Pattern lets you add functionality to a hierarchy of classes without changing its interface.

The reason why this is important is that there are times when we cannot change an existing hierarchy of classes. Perhaps I am using a hierarchy of classes that I am not in control of but I want to add some new functionality to it anyway. This is where the Visitor Pattern comes in.

In this program, I’ll add functionality to the File and Directory classes from the Composite program that I wrote earlier with minimal changes to those classes.

I create a visitor to count the number of files and directories in a topmost directory. Then I write a visitor to collect only the filenames in a directory including its sub-directories using the Visitor Pattern:

Visitor Pattern Adding Functionality to a Hierarchy of Classes (File and Directory)

Conclusion

I hope you enjoyed learning about object-oriented design patterns. If you are interested in other programming paradigms, you can check out some of my other 'books' here.

Questions and feedback are always welcome here: mark@playbackpress.com

If you'd like to support my work and help keep Playback Press free for all, consider donating using GitHub Sponsors. I use all of the donations for hosting costs. Your support helps me continue creating educational content like this. Thank you!

What is Polymorphism?

The word polymorphism is derived from Greek, and means "having multiple forms":

• Poly = many

• Morph = forms

In programming, polymorphism is the ability of an object to take many forms.

The key advantage of polymorphism is that it allows us to write more generic and reusable code. Instead of writing separate logic for different classes, we define common behaviours in a parent class and let child classes override them as needed. This eliminates the need for excessive if-else checks, making the code more maintainable and extensible.

MVC frameworks like Django use polymorphism to make code more flexible. For example, Django supports different databases like SQLite, MySQL, and PostgreSQL. Normally, each database requires different code to interact with it, but Django provides a single database API that works with all of them. This means you can write the same code for database operations, no matter which database you use. So, if you start a project with SQLite and later switch to PostgreSQL, you won’t need to rewrite much of your code, thanks to polymorphism.

In this article, to make things easy to understand, I’ll show you a bad code example with no polymorphism. We’ll discuss the issues that this bad code causes, and then solve the issues by refactoring the code to use polymorphism.

(Btw, if you learn better by video, checkout my Polymorphism in Python YouTube video.)

First, an example with no polymorphism:

class Car:
    def __init__(self, brand, model, year, number_of_doors):
        self.brand = brand
        self.model = model
        self.year = year
        self.number_of_doors = number_of_doors

    def start(self):
        print("Car is starting.")

    def stop(self):
        print("Car is stopping.")

class Motorcycle:
    def __init__(self, brand, model, year):
        self.brand = brand
        self.model = model
        self.year = year

    def start_bike(self):
        print("Motorcycle is starting.")

    def stop_bike(self):
        print("Motorcycle is stopping.")

Let’s say that we want to create a list of vehicles, then loop through it and perform an inspection on each vehicle:

# Create list of vehicles to inspect
vehicles = [
    Car("Ford", "Focus", 2008, 5),
    Motorcycle("Honda", "Scoopy", 2018),
]

# Loop through list of vehicles and inspect them
for vehicle in vehicles:
    if isinstance(vehicle, Car):
        print(f"Inspecting {vehicle.brand} {vehicle.model} ({type(vehicle).__name__})")
        vehicle.start()
        vehicle.stop()
    elif isinstance(vehicle, Motorcycle):
        print(f"Inspecting {vehicle.brand} {vehicle.model} ({type(vehicle).__name__})")
        vehicle.start_bike()
        vehicle.stop_bike()
    else:
        raise Exception("Object is not a valid vehicle")

Notice the ugly code inside the for loop! Because vehicles is a list of any type of object, we have to figure out what type of object we are dealing with inside each loop before we can access any information on the object.

This code will continue to get uglier as we add more vehicle types. For example, if we extended our codebase to include a new Plane class, then we’d need to modify (and potentially break) existing code – we’d have to add another conditional check in the for loop for planes.

Introducing: Polymorphism…

Cars and motorcycles are both vehicles. They both share some common properties and methods. So, let’s create a parent class that contains these shared properties and methods:

Parent class (or "superclass"):

class Vehicle:
    def __init__(self, brand, model, year):
        self.brand = brand
        self.model = model
        self.year = year

    def start(self):
        print("Vehicle is starting.")

    def stop(self):
        print("Vehicle is stopping.")

Car and Motorcycle can now inherit from Vehicle. Let’s create the child classes (or "subclasses") of the Vehicle superclass:

class Car(Vehicle):
    def __init__(self, brand, model, year, number_of_doors):
        super().__init__(brand, model, year)
        self.number_of_doors = number_of_doors

    # Below, we "override" the start and stop methods, inherited from Vehicle, to provide car-specific behaviour

    def start(self):
        print("Car is starting.")

    def stop(self):
        print("Car is stopping.")

class Motorcycle(Vehicle):
    def __init__(self, brand, model, year):
        super().__init__(brand, model, year)

    # Below, we "override" the start and stop methods, inherited from Vehicle, to provide bike-specific behaviour

    def start(self):
        print("Motorcycle is starting.")

    def stop(self):
        print("Motorcycle is stopping.")

Car and Motorcycle both extend Vehicle, as they are vehicles. But what’s the point in Car and Motorcycle both extending Vehicle if they are going to implement their own versions of the start() and stop() methods? Look at the code below:

# Create list of vehicles to inspect
vehicles = [Car("Ford", "Focus", 2008, 5), Motorcycle("Honda", "Scoopy", 2018)]

# Loop through list of vehicles and inspect them
for vehicle in vehicles:
    if isinstance(vehicle, Vehicle):
        print(f"Inspecting {vehicle.brand} {vehicle.model} ({type(vehicle).__name__})")
        vehicle.start()
        vehicle.stop()
    else:
        raise Exception("Object is not a valid vehicle")

In this example:

• We have a list, vehicles, containing instances of both Car and Motorcycle.

• We iterate through each vehicle in the list and perform a general inspection on each one.

• The inspection process involves starting the vehicle, checking its brand and model, and stopping it afterwards.

• Despite the vehicles being of different types, polymorphism allows us to treat them all as instances of the base Vehicle class. The specific implementations of the start() and stop() methods for each vehicle type are invoked dynamically at runtime, based on the actual type of each vehicle.

Because the list can only contain objects that extend the Vehicle class, we know that every object will share some common fields and methods. This means that we can safely call them, without having to worry about whether each specific vehicle has these fields or methods.

This demonstrates how polymorphism enables code to be written in a more generic and flexible manner, allowing for easy extension and maintenance as new types of vehicles are added to the system.

For example, if we wanted to add another vehicle to the list, we don’t have to modify the code used to inspect vehicles (“the client code”). Instead, we can just extend our code base (that is, create a new class), without modifying existing code:

class Plane(Vehicle):
    def __init__(self, brand, model, year, number_of_doors):
        super().__init__(brand, model, year)
        self.number_of_doors = number_of_doors

    def start(self):
        print("Plane is starting.")

    def stop(self):
        print("Plane is stopping.")

# Create list of vehicles to inspect
vehicles = [
    Car("Ford", "Focus", 2008, 5),
    Motorcycle("Honda", "Scoopy", 2018),

    ########## ADD A PLANE TO THE LIST: #########

    Plane("Boeing", "747", 2015, 16),

    ############################################
]

The code to perform the vehicle inspections doesn’t have to change to account for a plane. Everything still works, without having to modify our inspection logic.

Conclusion

Polymorphism allows clients to treat different types of objects in the same way. This greatly improves the flexibility of software and maintainability of software, as new classes can be created without you having to modify (often by adding extra if/else if blocks) existing working and tested code.

Further Learning

Polymorphism is related to many other object-oriented programming principles, such as dependency injection and the open-closed SOLID principle. If you’d like to master OOP, then check out my Udemy course:

• Python OOP: Object Oriented Programming From Beginner to Pro 🎥

If you prefer book to video, check out my books:

• Amazon Kindle and paperback 📖

• Gumroad PDF 📖

Thanks for reading :)