One of the patterns that explicitly helps you manage complex hierarchical scenarios is the Composite Design Pattern.

So what does this pattern really do?

Let me give you an example. You have a dataset and you want a common interface to be responsible for managing that dataset, ensuring one method is used for everything. You also want to allow a blueprint to manage this data and allow the data to grow as much as it can. This is a great fit for the Composite Design Pattern in object composition.

Here are some other clear use cases:

• A shopping cart contains individual items. It also has bundles of items sold together. Both need a price.

• A tax system has individual taxpayers. It also has family groups and corporate groups. All of them need tax calculated, discounts applied, and year-to-date totals computed.

• A file system has individual files. It also has folders that contain files or other folders. Both need a size.

The naïve approach is to write separate logic for individuals and groups, then add a type check wherever you need to handle both. But the logic diverges. The type checks multiply. And every new operation means updating both branches. The code becomes harder to extend and harder to trust.

The Composite Design Pattern eliminates this entirely. It defines a common interface that both individual objects and groups implement. The calling code never checks types. It calls the same method on a leaf or a composite and gets the correct result either way.

Table of Contents

• Prerequisites

• What is the Composite Design Pattern?

• The Three Layers

• Real World Example One: Shopping Cart Pricing

• Real World Example Two: Tax Management

• The Power of Nested Composites

• The Composite Pattern in C#

• When to Use the Composite Pattern

• When Not to Use It

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Object-oriented programming: abstract classes, interfaces, and inheritance

• What a design pattern is at a conceptual level

• Basic Dart or C# syntax

You don't need prior experience with structural design patterns. This article introduces the Composite pattern from first principles with real production examples.

What is the Composite Design Pattern?

The Composite Design Pattern is a structural design pattern. Where creational patterns deal with how objects are created and behavioral patterns deal with how objects communicate, structural patterns deal with how objects are composed and related to each other.

The Composite pattern specifically deals with part-whole hierarchies. It lets you compose objects into tree structures and then work with those trees as if every node in the tree is the same type of thing.

The core idea is deceptively simple: define a common interface, make individual objects implement it, and make groups of objects implement it too. Now everything in the hierarchy responds to the same methods and the calling code never needs to distinguish between a leaf and a composite.

This is what "treating individual objects and groups through a unified interface" means in practice. One method call, any object in the hierarchy, correct result regardless of whether you are calling it on a single item or a nested group containing hundreds of items.

The Three Layers

The Composite pattern has three distinct layers. Understanding each one before looking at code makes the implementation much clearer.

The Component Layer

This is the abstract class or interface that defines the contract for every object in the hierarchy. It declares the methods that both individual objects and groups must implement.

The Component is what makes uniform treatment possible: because everything in the hierarchy implements this interface, everything responds to the same method calls.

The Leaf Layer

A Leaf is a concrete implementation of the Component. It represents an individual object with no children, like a single item in a shopping cart, a single taxpayer, or a single file. The Leaf implements the Component methods with its own specific logic.

The Composite Layer

A Composite is also a concrete implementation of the Component. But unlike a Leaf, it holds a collection of children. Each child is a Component, which means each child can be either a Leaf or another Composite.

The Composite implements the Component methods by delegating to its children and aggregating the results.

The relationship between these layers is what enables the tree structure and the uniform interface simultaneously.

Real World Example One: Shopping Cart Pricing

A shopping cart needs to calculate prices. Individual items have their own prices. Bundles group multiple items and their price is the sum of their contents. Both need to respond to getPrice().

The Component

abstract class PriceComponent {
  double getPrice();
}

PriceComponent is the contract. Every object in the cart hierarchy must implement getPrice(). That is the entire interface: one method that's uniform across all objects.

The Leaf

class CartItem extends PriceComponent {
  final int id;
  final String name;
  final double price;

  CartItem({required this.id, required this.name, required this.price});

  @override
  double getPrice() {
    return price;
  }
}

CartItem is the Leaf. It represents a single item in the cart. Its getPrice() returns its own price directly. There's no delegation or children. Just its own value.

The Composite

class ItemBundle extends PriceComponent {
  final int bundleId;
  final String bundleName;
  final List<PriceComponent> _items = [];

  ItemBundle({required this.bundleId, required this.bundleName});

  void add(PriceComponent component) {
    _items.add(component);
  }

  void remove(PriceComponent component) {
    _items.remove(component);
  }

  @override
  double getPrice() {
    return _items.fold(0, (total, item) => total + item.getPrice());
  }
}

ItemBundle is the Composite. It holds a list of PriceComponent children. Its getPrice() delegates to its children using fold, summing up whatever each child returns.

The critical detail: _items is a List<PriceComponent>, not a List<CartItem>. This means an ItemBundle can contain both CartItem leaves and other ItemBundle composites. The hierarchy can nest as deeply as needed.

Using It

void main() {
  
  final burger = CartItem(id: 1, name: 'Burger', price: 5.99);
  final fries = CartItem(id: 2, name: 'Fries', price: 2.99);
  final drink = CartItem(id: 3, name: 'Drink', price: 1.99);
  final apple = CartItem(id: 4, name: 'Apple', price: 0.99);

 
  final comboMeal = ItemBundle(bundleId: 1, bundleName: 'Combo Meal');
  comboMeal
    ..add(burger)
    ..add(fries)
    ..add(drink);


  final cart = ItemBundle(bundleId: 0, bundleName: 'My Cart');
  cart
    ..add(comboMeal) 
    ..add(apple);    

  // same method call on everything
  print('Burger: \$${burger.getPrice()}');           
  print('Combo Meal: \$${comboMeal.getPrice()}');    
  print('Full Cart: \$${cart.getPrice()}');          
}

burger.getPrice() calls the Leaf implementation directly. comboMeal.getPrice() calls the Composite implementation which delegates to its three children. cart.getPrice() calls the Composite implementation which delegates to the combo meal composite and the apple leaf.

The calling code treats all of them identically: getPrice(), result, done.

Real World Example Two: Tax Management

This example shows the Composite pattern applied to a more complex domain. A tax management system needs to calculate tax amounts, apply discounts, and compute year-to-date totals. These calculations need to work for individual taxpayers and for groups of taxpayers through exactly the same interface.

The Component

abstract class TaxManager {
  num getTaxAmount();
  num getTaxDiscount();
  num getTotalTaxYTD();
}

TaxManager defines three methods. Every object in the tax hierarchy must implement all three. A single taxpayer implements them with their own data. A group implements them by aggregating across all members. The calling code calls any of these methods on any object and gets the correct result.

The Leaf

class SingleUser extends TaxManager {
  final num _amount;
  final List<num> _allTaxes;

  SingleUser(this._amount, this._allTaxes);

  @override
  num getTaxAmount() {
    return _amount;
  }

  @override
  num getTaxDiscount() {
   
    return _amount % 2 == 0 ? _amount : (_amount / 2);
  }

  @override
  num getTotalTaxYTD() {
    num total = 0;
    for (final tax in _allTaxes) {
      total += tax;
    }
    return total;
  }
}

SingleUser is the Leaf. It represents one individual taxpayer. _amount is their current tax amount. _allTaxes is a list of their tax payments over the year. Each method operates on this person's data only.

getTaxDiscount() applies a simple discount rule: even amounts receive the full amount, odd amounts receive half. This rule lives on the individual and is automatically propagated through any group that contains this user.

getTotalTaxYTD() sums the user's historical tax payments to produce their year-to-date total.

The Composite

class UserGroup extends TaxManager {
  final String groupName;
  final List<TaxManager> _members = [];

  UserGroup(this.groupName);

  void add(TaxManager member) {
    _members.add(member);
  }

  void remove(TaxManager member) {
    _members.remove(member);
  }

  @override
  num getTaxAmount() {
    return _members.fold(0, (total, member) => total + member.getTaxAmount());
  }

  @override
  num getTaxDiscount() {
    return _members.fold(0, (total, member) => total + member.getTaxDiscount());
  }

  @override
  num getTotalTaxYTD() {
    return _members.fold(0, (total, member) => total + member.getTotalTaxYTD());
  }
}

UserGroup is the Composite. It holds a list of TaxManager members. Each method delegates to every member and folds the results.

Notice that _members is typed as List<TaxManager>, not List<SingleUser>. This means a UserGroup can contain individual SingleUser leaves or other UserGroup composites. A family group can contain individual members. A corporate group can contain family groups. The hierarchy can grow as needed and the interface never changes.

Using It

void main() {
  
  final seyisTax = SingleUser(100000, List.generate(12, (_) => 20000));
  final ronkesTax = SingleUser(5000, List.generate(12, (_) => 50000));
  final inisTax = SingleUser(20000, List.generate(12, (_) => 20000));
  final tiwasTax = SingleUser(10000, List.generate(12, (_) => 10000));

 
  print('Seyi tax amount: ${seyisTax.getTaxAmount()}');       
  print('Ronke tax amount: ${ronkesTax.getTaxAmount()}');     
  print('Seyi discount: ${seyisTax.getTaxDiscount()}');        
  print('Seyi YTD: ${seyisTax.getTotalTaxYTD()}');            

  // build a family group
  final fatunmoles = UserGroup('Fatunmoles');
  fatunmoles
    ..add(seyisTax)
    ..add(ronkesTax)
    ..add(inisTax)
    ..add(tiwasTax);

 
  
  print('Total tax: ${fatunmoles.getTaxAmount()}');      
  print('Total discount: ${fatunmoles.getTaxDiscount()}'); 
  print('Total YTD: ${fatunmoles.getTotalTaxYTD()}');    

  // a second family group
  final child1 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child2 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child3 = SingleUser(100000, List.generate(12, (_) => 20000));

  final unknownFamily = UserGroup('UnknownFamily');
  unknownFamily
    ..add(child1)
    ..add(child2)
    ..add(child3);


  print('Tax: ${unknownFamily.getTaxAmount()}');
  print('Discount: ${unknownFamily.getTaxDiscount()}');
  print('YTD: ${unknownFamily.getTotalTaxYTD()}');
}

The same three method calls work on seyisTax (one person), fatunmoles (four people), and unknownFamily (three people). The calling code is identical. The results are correct for each level of the hierarchy.

The Power of Nested Composites

The most powerful aspect of the Composite pattern is that a Composite can contain other Composites. A UserGroup can contain other UserGroup objects. This enables deep hierarchies while maintaining the same uniform interface at every level.

void demonstrateNesting() {
  
  final seyi = SingleUser(100000, List.generate(12, (_) => 20000));
  final ronke = SingleUser(5000, List.generate(12, (_) => 50000));
  final ini = SingleUser(20000, List.generate(12, (_) => 20000));
  final tiwa = SingleUser(10000, List.generate(12, (_) => 10000));

  final child1 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child2 = SingleUser(100000, List.generate(12, (_) => 20000));
  final child3 = SingleUser(100000, List.generate(12, (_) => 20000));

  // family groups
  final fatunmoles = UserGroup('Fatunmoles');
  fatunmoles
    ..add(seyi)
    ..add(ronke)
    ..add(ini)
    ..add(tiwa);

  final unknownFamily = UserGroup('UnknownFamily');
  unknownFamily
    ..add(child1)
    ..add(child2)
    ..add(child3);

  // a composite that contains other composites
  // both families treated as one unit
  final allFamilies = UserGroup('AllFamilies');
  allFamilies
    ..add(fatunmoles)    
    ..add(unknownFamily); 

  // same interface, now covers all 7 people across both families
  print('All families combined:');
  print('Total tax: ${allFamilies.getTaxAmount()}');
  print('Total discount: ${allFamilies.getTaxDiscount()}');
  print('Total YTD: ${allFamilies.getTotalTaxYTD()}');
}

allFamilies.getTaxAmount() traverses the entire tree: it asks fatunmoles for its total, which asks each of its four members, and asks unknownFamily for its total, which asks each of its three members. Seven people, one method call. The caller doesn't know the depth of the tree or how many members exist at any level.

This is where the pattern demonstrates its full value. You can build an organization with divisions, departments, teams, and individuals, all implementing the same TaxManager interface, and call getTaxAmount() on the organization to get the total for every single person in it. Or call it on a single department. Or call it on a single person. The interface is always the same.

The Composite Pattern in C#

The same pattern in C# shows that this is a universal structural principle. Here is the tax management system replicated in C# for a corporate payroll context.

The Component

public interface ITaxManager
{
    decimal GetTaxAmount();
    decimal GetTaxDiscount();
    decimal GetTotalTaxYTD();
}

The Leaf

public class Employee : ITaxManager
{
    private readonly string _name;
    private readonly decimal _taxAmount;
    private readonly List<decimal> _yearlyTaxes;

    public Employee(string name, decimal taxAmount, List<decimal> yearlyTaxes)
    {
        _name = name;
        _taxAmount = taxAmount;
        _yearlyTaxes = yearlyTaxes;
    }

    public decimal GetTaxAmount() => _taxAmount;

    public decimal GetTaxDiscount()
    {
        return _taxAmount % 2 == 0 ? _taxAmount : _taxAmount / 2;
    }

    public decimal GetTotalTaxYTD()
    {
        return _yearlyTaxes.Sum();
    }
}

The Composite

public class Department : ITaxManager
{
    private readonly string _name;
    private readonly List<ITaxManager> _members = new();

    public Department(string name)
    {
        _name = name;
    }

    public void Add(ITaxManager member) => _members.Add(member);
    public void Remove(ITaxManager member) => _members.Remove(member);

    public decimal GetTaxAmount()
    {
        return _members.Sum(m => m.GetTaxAmount());
    }

    public decimal GetTaxDiscount()
    {
        return _members.Sum(m => m.GetTaxDiscount());
    }

    public decimal GetTotalTaxYTD()
    {
        return _members.Sum(m => m.GetTotalTaxYTD());
    }
}

Using It in C#

var alice = new Employee("Alice", 150000, Enumerable.Repeat(25000m, 12).ToList());

var bob = new Employee("Bob", 80000, Enumerable.Repeat(15000m, 12).ToList());

var carol = new Employee("Carol", 120000, Enumerable.Repeat(20000m, 12).ToList());

var dave = new Employee("Dave", 95000, Enumerable.Repeat(18000m, 12).ToList());


var engineering = new Department("Engineering");
engineering.Add(alice);
engineering.Add(bob);


var design = new Department("Design");
design.Add(carol);
design.Add(dave);


var company = new Department("TechCorp");
company.Add(engineering);
company.Add(design);


Console.WriteLine($"Alice tax: {alice.GetTaxAmount()}");
Console.WriteLine($"Engineering total: {engineering.GetTaxAmount()}");

// entire company — traverses all departments and all employees
Console.WriteLine($"Company total tax: {company.GetTaxAmount()}");
Console.WriteLine($"Company total discount: {company.GetTaxDiscount()}");
Console.WriteLine($"Company YTD: {company.GetTotalTaxYTD()}");

The structure is identical to the Dart implementation. ITaxManager is the Component, Employee is the Leaf, and Department is the Composite. The hierarchy nests: a Department of Departments forms the company. The calling code calls the same three methods on any node in the tree and gets the correct aggregated result.

This is the same pattern solving the same problem in a different language. The structural principle is universal.

When to Use the Composite Pattern

Use the Composite pattern when you have a part-whole hierarchy where both parts and wholes need to be treated uniformly.

It's also a good choice when the calling code shouldn't need to distinguish between individual objects and groups. If you find yourself writing writing conditional statements to check if an object is a group or single frequently, that's a signal that Composite would eliminate those branches.

It's helpful when the hierarchy needs to be flexible and deeply nestable. File systems, organizational charts, UI component trees, category hierarchies, tax systems, or shopping carts with bundles: any domain where containers can hold other containers benefits from Composite.

And it's useful when new types of leaves or composites might be added in the future. Because everything implements the same Component interface, adding a new type of leaf (a CorporateTaxpayer alongside SingleUser) or a new type of composite (a TaxBracketGroup) means creating one new class. The calling code and all existing classes remain unchanged.

When Not to Use It

Avoid Composite when the hierarchy is simple and unlikely to nest. If you have individual items and exactly one level of grouping with no nesting, the pattern adds abstraction that a simpler approach would not require.

It's also not a good choice when individual objects and groups genuinely need different interfaces. If groups need many additional methods that individuals never need, forcing them into the same interface creates an interface that's too broad and violates the Interface Segregation Principle.

Avoid it when performance is critical and the overhead of recursive traversal matters. Deep hierarchies with millions of nodes traversed frequently might benefit from a different approach that caches aggregated results.

Conclusion

The Composite Design Pattern solves a fundamental problem in hierarchical systems: how do you perform the same operation on both individual objects and groups of objects without writing two separate implementations or littering your code with type checks?

The answer is a common interface. Every object in the hierarchy implements the same contract. Individual objects implement it with their own data. Groups implement it by delegating to their children and aggregating the results. The calling code calls the same method and gets the correct answer regardless of whether it's talking to a leaf or a composite containing a hundred nested levels.

The shopping cart example shows this for pricing: one getPrice() method, called identically on a single item or a bundle containing other bundles. The tax management example shows this for a domain with multiple operations: getTaxAmount(), getTaxDiscount(), and getTotalTaxYTD() called identically on a single taxpayer, a family group, or a composite of family groups.

The nested composite demonstration shows the full power: a UserGroup containing other UserGroups, each containing SingleUsers, all responding to the same interface and producing correct aggregated results at every level. Seven people, one method call. The tree is traversed automatically.

C# shows the same principle in a corporate payroll context: employees as leaves, departments as composites, and the company as a composite of departments. One interface, any level of the hierarchy. Correct result every time.

The Composite pattern doesn't eliminate complexity. It contains it. The complexity of aggregating results across a deep hierarchy lives inside the Composite's fold calls, not scattered across the calling code. The calling code stays clean. The hierarchy stays flexible. New types can be added without changing anything that already exists.

That's the structural discipline the Composite pattern provides.

Happy Coding!

This handbook serves as a practical guide to understanding software design patterns. I wrote it for every developer, regardless of the language you program in. Examples are written in C#, but every concept here applies equally to Python, Java, TypeScript, Go, and beyond.

The source code lives at github.com/Clifftech123/design-patterns-handbook.

Things to Keep in Mind:

• Design patterns aren't code. They're a way of thinking about how to structure your code. They're a tool, not a silver bullet, for solving specific design problems.

• The concepts are universal. The examples here are written in C#, but the same patterns exist in every language. If you write Python, Java, Go, or TypeScript, you're already using some of these without knowing it.

• There's no one-size-fits-all pattern. Each pattern exists to address a particular kind of problem. Understanding what problem a pattern solves is more important than memorizing the implementation.

I use C# here as the teaching language because it's clear, readable, and widely understood. The goal of this handbook is for you to walk away understanding the pattern itself, not just the C# code.

There are three main types of design patterns: Creational, Structural, and Behavioral. We'll look at each one in turn here, starting with Creational.

What We'll Cover:

• Things to Keep in Mind

• Creational Design Patterns

  • 1. Singleton Design Pattern

  • 2. The Factory Method

  • 3. The Abstract Factory Design Pattern

  • 4. The Builder Design Pattern

  • 5. The Prototype Design Pattern

• Structural Design Patterns

  • 1. The Adapter Design Pattern

  • 2. The Bridge Design Pattern

  • 3. The Composite Design Pattern

  • 4. The Decorator Design Pattern

  • 5. The Facade Design Pattern

  • 6. The Flyweight Design Pattern

  • 7. The Proxy Design Pattern

• Behavioral Design Patterns

  • 1. The Chain of Responsibility Design Pattern

  • 2. The Command Design Pattern

  • 3. The Interpreter Design Pattern

  • 4. The Iterator Design Pattern

  • 5. The Mediator Design Pattern

  • 6. The Memento Design Pattern

  • 7. The Observer Design Pattern

  • 8. The State Design Pattern

  • 9. The Strategy Design Pattern

  • 10. The Template Method Design Pattern

  • 11. The Visitor Design Pattern

• Conclusion

  • A few things worth remembering

Creational Design Patterns

Simply put, Creational patterns are all about how objects are created. They can be divided into class-creation patterns, which use inheritance to decide which class to instantiate, and object-creation patterns, which use delegation to get the job done.

Wikipedia describes them as:

"A creational pattern aims to separate a system from how its objects are created, composed, and represented. They increase the system's flexibility in terms of the what, who, how, and when of object creation."

(Source)

So Creational patterns keep the details of object creation hidden from the client code, making the system easier to manage and maintain.

They also abstract away how objects are created, composed, and represented, so the rest of your code doesn't need to care.

There are five Creational design patterns, which we'll go over one by one below:

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

2. Factory Method: Defines an interface for creating an object, but lets subclasses decide which class to instantiate.

3. Abstract Factory: Provides an interface for creating families of related or dependent objects without specifying their concrete classes.

4. Builder: Separates the construction of a complex object from its representation, so the same construction process can produce different results.

5. Prototype: Creates new objects by cloning an existing instance rather than building one from scratch.

1. Singleton Design Pattern

Real World Example:

Think of the conductor of an orchestra. An orchestra has one conductor. Every musician on stage looks to that same conductor for direction: when to start, when to stop, how fast to play, and how loud to go.

The conductor is the single point of authority that all musicians connect to and take decisions from. You can't have two conductors standing at the front giving different instructions. That would cause chaos. No matter which musician needs guidance, they all reach the same one person.

That's exactly how the Singleton works in code: one instance, shared by everyone who needs it, making decisions from one place.

Problems it solves:

• What if two musicians get different conductors giving different instructions? The performance falls apart. There must be one conductor that every musician looks to, without exception.

• How does a musician find the conductor? They don't go searching. There's one well-known place everyone looks, and the same conductor is always there.

• What stops someone from appointing a second conductor? The orchestra itself controls this. Once a conductor is on the podium, no second one can take it.

In simple terms, there's only one instance of the class, and every part of the system that needs it gets access to that exact same instance (never a new one).

Here's how Wikipedia describes the Singleton pattern:

"In object-oriented programming, the singleton pattern is a software design pattern that restricts the instantiation of a class to a singular instance. The pattern is useful when exactly one object is needed to coordinate actions across a system." (Source)

Programming Example:

We'll model the analogy directly now. The OrchestraConductor is the Singleton: one instance, shared by all musicians, making all decisions.

public class OrchestraConductor
{
    // Step 1: Hold the one instance here
    private static OrchestraConductor _instance;

    // Step 2: Private constructor - nobody outside can do: new OrchestraConductor()
    private OrchestraConductor() { }

    // Step 3: The only way to get the conductor
    public static OrchestraConductor GetInstance()
    {
        if (_instance == null)
        {
            _instance = new OrchestraConductor();
        }

        return _instance;
    }

    // Decisions the conductor makes
    public void Start()                    => Console.WriteLine("Conductor: Begin playing.");
    public void Stop()                     => Console.WriteLine("Conductor: Stop playing.");
    public void SetTempo(string tempo)     => Console.WriteLine($"Conductor: Tempo is now {tempo}.");
}

Now let's see it in action:

// Violinist asks for the conductor
OrchestraConductor violinist = OrchestraConductor.GetInstance();

// Pianist asks for the conductor
OrchestraConductor pianist = OrchestraConductor.GetInstance();

// Are they talking to the same conductor?
Console.WriteLine(object.ReferenceEquals(violinist, pianist)); // True

violinist.SetTempo("Allegro");
pianist.Start();

Output:

True
Conductor: Tempo is now Allegro.
Conductor: Begin playing.

Both musicians got the same conductor. The constructor never ran twice. That is the Singleton pattern.

When to Use the Singleton Pattern

Reach for Singleton when you need one shared resource that the whole application talks to, such as a logger, a configuration manager, or a database connection pool.

It's also a good idea when having more than one instance would cause incorrect behaviour or conflicting state.

And it's helpful when you want a global point of access to an object without passing it around everywhere.

2. The Factory Method

Think of a recruitment agency. A company calls the agency and says "we need a worker." The company doesn't go out and create the worker themselves. They just make the request.

The agency decides which specific person to send: a developer, a designer, or a tester, depending on what the company needs. The company doesn't know or care exactly who is coming. They just know the person will be able to do the job.

That's the Factory Method. Your code asks for an object. The Factory decides which specific type to create and hands it back. You work with it without needing to know exactly what it is under the hood.

Problems it solves:

• The company shouldn't need to know who they're getting. They just need someone who can do the job. The agency handles the decision of whom to send. The company never has to worry about the details.

• What if the company needs a different type of worker tomorrow? They call the same agency. The agency decides. The company's process doesn't change, only the agency's decision does.

• What if a new type of worker needs to be introduced? A new specialist agency is created to handle that. Everything else stays exactly the same.

In simple terms, we define an interface for creating an object, but let subclasses decide which class to instantiate. The factory method lets a class defer instantiation to subclasses.

Wikipedia describes it like this:

"In object-oriented programming, the factory method pattern is a design pattern that uses factory methods to deal with the problem of creating objects without having to specify their exact classes. Factory methods can be specified in an interface and implemented by subclasses, or implemented in a base class and optionally overridden by subclasses." (Source)

Programming Example:

The agency is the factory. The worker types are the products. The company is the client.

// The worker interface - all workers can do a job
public interface IWorker
{
    void DoWork();
}

// The concrete workers
public class Developer : IWorker
{
    public void DoWork() => Console.WriteLine("Developer: Writing code.");
}

public class Designer : IWorker
{
    public void DoWork() => Console.WriteLine("Designer: Creating designs.");
}

// The base agency - declares the factory method
public abstract class RecruitmentAgency
{
    // This is the Factory Method - subclasses decide who to hire
    public abstract IWorker HireWorker();
}

// Concrete agencies - each one decides which worker to send
public class TechAgency : RecruitmentAgency
{
    public override IWorker HireWorker() => new Developer();
}

public class DesignAgency : RecruitmentAgency
{
    public override IWorker HireWorker() => new Designer();
}

Now let's see it in action:

// Company A needs a tech worker
RecruitmentAgency agency = new TechAgency();
IWorker worker = agency.HireWorker();
worker.DoWork();

// Company B needs a design worker
RecruitmentAgency agency2 = new DesignAgency();
IWorker worker2 = agency2.HireWorker();
worker2.DoWork();

Output:

Developer: Writing code.
Designer: Creating designs.

The company never used new Developer() or new Designer() directly. The agency made that decision. That is the Factory Method.

3. The Abstract Factory Design Pattern

Real World Example

Think of a furniture store that sells collections. You walk in and choose a style: Modern or Victorian. Once you choose, everything you get comes from that same collection. The sofa, the chair, and the coffee table all match. The store ensures that you never walk out with a modern sofa paired with a Victorian chair. You don't pick individual pieces and hope they go together. The collection guarantees they will.

That's the Abstract Factory. You choose a family, and the Factory produces every object you need from that same family. Everything it gives you is guaranteed to work together.

Problems it solves:

• What if a customer mixes furniture from different collections? The room looks inconsistent. The store solves this by grouping everything into collections. You pick one collection and everything comes from it.

• What if the store wants to introduce a new collection? They create a new collection set. Every existing collection stays untouched. The customer's experience doesn't change, only the options grow.

• What if different stores carry different collections? Each store is its own factory. A customer walks into any store and follows the same process. The store handles which specific pieces to provide.

In simple terms, you provide an interface for creating families of related objects, without specifying their concrete classes.

Wikipedia describes it like this:

"The abstract factory pattern provides a way to create families of related objects without imposing their concrete classes, by encapsulating a group of individual factories that have a common theme without specifying their concrete classes."

Source: Wikipedia - Abstract factory pattern

Programming Example:

The furniture store is the abstract factory. Modern and Victorian are the concrete factories. Sofa and Chair are the products.

// The product interfaces - every furniture type has a contract
public interface ISofa  { void Describe(); }
public interface IChair { void Describe(); }

// Modern collection
public class ModernSofa : ISofa
{
    public void Describe() => Console.WriteLine("Sofa: Sleek modern design.");
}

public class ModernChair : IChair
{
    public void Describe() => Console.WriteLine("Chair: Minimalist modern style.");
}

// Victorian collection
public class VictorianSofa : ISofa
{
    public void Describe() => Console.WriteLine("Sofa: Ornate Victorian design.");
}

public class VictorianChair : IChair
{
    public void Describe() => Console.WriteLine("Chair: Classic Victorian style.");
}

// The abstract factory - every store can produce a sofa and a chair
public interface IFurnitureFactory
{
    ISofa  CreateSofa();
    IChair CreateChair();
}

// Concrete factories - each one produces its own collection
public class ModernFurnitureFactory : IFurnitureFactory
{
    public ISofa  CreateSofa()  => new ModernSofa();
    public IChair CreateChair() => new ModernChair();
}

public class VictorianFurnitureFactory : IFurnitureFactory
{
    public ISofa  CreateSofa()  => new VictorianSofa();
    public IChair CreateChair() => new VictorianChair();
}

Now let's see it in action:

// Customer orders a Modern collection
IFurnitureFactory factory = new ModernFurnitureFactory();
ISofa  sofa  = factory.CreateSofa();
IChair chair = factory.CreateChair();
sofa.Describe();
chair.Describe();

// Customer orders a Victorian collection
IFurnitureFactory factory2 = new VictorianFurnitureFactory();
ISofa  sofa2  = factory2.CreateSofa();
IChair chair2 = factory2.CreateChair();
sofa2.Describe();
chair2.Describe();

Output:

Sofa: Sleek modern design.
Chair: Minimalist modern style.
Sofa: Ornate Victorian design.
Chair: Classic Victorian style.

Every piece came from the same collection. The client never used new ModernSofa() or new VictorianChair() directly. The factory kept the family together. That's the Abstract Factory.

When to Use Abstract Factory:

Use the Abstract Factory pattern when your system needs to work with multiple families of related objects and you need to ensure they're always used together.

It also works well when you want to swap out an entire family of objects in one place without touching the rest of your code.

And it's a good choice when you want to enforce consistency across related objects, so nothing from one family gets accidentally mixed with another.

4. The Builder Design Pattern

Real World Example

Think of a tailor making a suit. Every customer that walks in goes through the same process: take measurements, choose the fabric, select the lining, pick the buttons, and decide on the lapel style.

The tailor follows those same steps for every order. But the finished suit is completely unique to each customer. A businessman walks out with a sharp formal suit. A wedding guest walks out with something entirely different. Same process, same tailor, but with different result every time.

That's the Builder. The construction process stays the same. What changes are the choices made at each step.

Problems it solves:

• What if a suit had to be assembled all at once with no steps? You would have to know every detail upfront and get it all right in one go. The tailor breaks it down into steps so each decision is made clearly, one at a time.

• What if two customers want completely different suits but go through the same tailor? The tailor follows the same process for both. The steps don't change, only the choices within each step.

• What if a new suit style needs to be introduced? A new set of choices is defined for that style. The tailoring process itself stays untouched.

In simple terms, you separate the construction of a complex object from its representation, so that the same construction process can create different results.

Wikipedia describes it like this:

"The Builder pattern separates the construction of a complex object from its representation so that the same construction process can create different representations." (Source)

Programming Example:

The tailor is the director. The suit is the product. The builder handles the step-by-step construction.

// The product
public class Suit
{
    public string Fabric  { get; set; }
    public string Lining  { get; set; }
    public string Buttons { get; set; }

    public void Describe()
    {
        Console.WriteLine($"Suit: {Fabric} fabric, {Lining} lining, {Buttons} buttons.");
    }
}

// The builder - defines the steps
public interface ISuitBuilder
{
    void SetFabric();
    void SetLining();
    void SetButtons();
    Suit GetSuit();
}

// Business suit builder
public class BusinessSuitBuilder : ISuitBuilder
{
    private Suit _suit = new Suit();

    public void SetFabric()  => _suit.Fabric  = "Dark wool";
    public void SetLining()  => _suit.Lining  = "Silk";
    public void SetButtons() => _suit.Buttons = "Black horn";
    public Suit GetSuit()    => _suit;
}

// Wedding suit builder
public class WeddingSuitBuilder : ISuitBuilder
{
    private Suit _suit = new Suit();

    public void SetFabric()  => _suit.Fabric  = "Ivory linen";
    public void SetLining()  => _suit.Lining  = "Satin";
    public void SetButtons() => _suit.Buttons = "Pearl";
    public Suit GetSuit()    => _suit;
}

// The tailor - the director who runs the process
public class Tailor
{
    public Suit MakeSuit(ISuitBuilder builder)
    {
        builder.SetFabric();
        builder.SetLining();
        builder.SetButtons();
        return builder.GetSuit();
    }
}

Now let's see it in action:

Tailor tailor = new Tailor();

Suit businessSuit = tailor.MakeSuit(new BusinessSuitBuilder());
businessSuit.Describe();

Suit weddingSuit = tailor.MakeSuit(new WeddingSuitBuilder());
weddingSuit.Describe();

Output:

Suit: Dark wool fabric, Silk lining, Black horn buttons.
Suit: Ivory linen fabric, Satin lining, Pearl buttons.

The same tailor, following the same process, creates two completely different suits. That is the Builder.

When to Use the Builder Design Pattern

Use the Builder pattern when an object has many parts or configurations and building it all at once would be confusing.

It's also a good choice when you want the same construction process to produce different results depending on the choices made at each step.

And reach for it when you want to keep the construction logic separate from the object itself, so each can change independently.

5. The Prototype Design Pattern

Real World Example

Imagine you're building a drawing application. Users can create shapes like circles, rectangles, or triangles, each with its own colour, size, and position.

Now imagine the user wants ten red circles of the same size placed across the canvas. Creating each one from scratch means repeating the same setup ten times. What if the shape is complex, with many configured properties? That becomes expensive and repetitive.

The Prototype pattern solves this by letting you take one fully configured shape and clone it. The clone starts as an exact copy. The user then moves it, recolours it, or resizes it independently. The original shape is never touched. This also means new shape types can be added at runtime without the application needing to know about them in advance.

Problems it solves:

• Creating a new shape from scratch every time is expensive. If a shape has many properties, setting them all up repeatedly wastes resources. Cloning an already configured object is far cheaper.

• The application shouldn't need to know the exact type of shape it's copying. At runtime, shapes can be added or removed dynamically. The app just calls clone and gets back a ready object, whatever type it happens to be.

• Modifying a copy should never affect the original. Each cloned shape is fully independent. Changes to the copy stay with the copy.

In simple terms, you can create new objects by copying an existing one. The copy starts identical to the original and can then be changed independently.

Wikipedia describes it like this:

"The Prototype pattern is used when the type of objects to create is determined by a prototypical instance, which is cloned to produce new objects." (Source)

Programming Example:

Every shape knows how to clone itself. The application never calls new Circle() or new Rectangle() directly at runtime. It clones what already exists.

// The prototype interface - every shape must be able to clone itself
public abstract class Shape
{
    public string Colour { get; set; }
    public int    Size   { get; set; }

    public abstract Shape Clone();
    public abstract void  Describe();
}

// Concrete shapes
public class Circle : Shape
{
    public override Shape Clone()    => (Shape)this.MemberwiseClone();
    public override void  Describe() => Console.WriteLine($"Circle  | Colour: {Colour} | Size: {Size}");
}

public class Rectangle : Shape
{
    public override Shape Clone()    => (Shape)this.MemberwiseClone();
    public override void  Describe() => Console.WriteLine($"Rectangle | Colour: {Colour} | Size: {Size}");
}

Now let's see it in action:

// Create one configured circle
Circle original = new Circle { Colour = "Red", Size = 50 };

// Clone it instead of building from scratch
Shape clone1 = original.Clone();
Shape clone2 = original.Clone();

// Modify the clones independently
clone2.Colour = "Blue";

original.Describe();
clone1.Describe();
clone2.Describe();

Output:

Circle  | Colour: Red  | Size: 50
Circle  | Colour: Red  | Size: 50
Circle  | Colour: Blue | Size: 50

clone2 changed to blue. The original stayed red. Each object is fully independent. That's the Prototype.

When to Use the Prototype Design Pattern:

Use Prototype when creating a new object from scratch is expensive or complex and an existing object already has everything configured.

It's also helpful when the application needs to create objects at runtime without knowing their exact type in advance.

And it's great when you need many variations of an object and want to start from a known good state rather than rebuild every time.

Structural Design Patterns

Simply put, structural patterns are all about how classes and objects are composed to form larger structures. They use inheritance and composition to let you build flexible, efficient structures without having to rewrite everything from scratch.

Wikipedia describes them as:

"In software engineering, structural patterns are design patterns that ease the design by identifying a simple way to realize relationships among entities." (Source)

Structural design patterns describe how objects and classes are combined to form larger, more complex structures while keeping those structures flexible and efficient.

They focus on composition over inheritance: how you connect things, not just what things are.

There are seven Structural design patterns:

1. Adapter: Converts one interface into another that a client expects, letting incompatible interfaces work together.

2. Bridge: Decouples an abstraction from its implementation so the two can vary independently.

3. Composite: Composes objects into tree structures to represent part-whole hierarchies, letting clients treat individual objects and compositions uniformly.

4. Decorator: Attaches additional responsibilities to an object dynamically, as a flexible alternative to subclassing.

5. Facade: Provides a simplified, unified interface to a complex subsystem.

6. Flyweight: Uses sharing to efficiently support a large number of fine-grained objects.

7. Proxy: Provides a surrogate or placeholder for another object to control access to it.

1. The Adapter Design Pattern

Real World Example

Think of a language translator at a business meeting. A British CEO needs to address a Japanese team. The CEO speaks only English. The team speaks only Japanese. A translator sits between them, converting every English sentence into Japanese and delivering it to the team. Both sides keep speaking their own language. Neither the CEO nor the team change anything about how they communicate. The translator makes them compatible.

That's the Adapter. The client speaks one interface, while the other side speaks a different one. The Adapter sits between them and makes both sides work together without either having to change.

Problems it solves:

• The CEO can't speak Japanese, and the team can't speak English. They're incompatible. The translator adapts one to the other without changing either side.

• What if the CEO now needs to address a French team? A French translator is brought in. The CEO's process doesn't change. Only the translator changes.

• What if an existing class has a useful method but the wrong interface? You wrap it in an adapter. The rest of the system talks to the adapter while the existing class stays untouched.

In simple terms, you wrap an existing class with a new interface so the client can use it without any changes to either side.

Wikipedia describes it like this:

"In software engineering, the adapter pattern is a software design pattern (also known as wrapper) that allows the interface of an existing class to be used as another interface. It is often used to make existing classes work with others without modifying their source code." (Source)

Programming Example:

The CEO is the client and the Japanese team member is the adaptee. They're useful, but they speak the wrong interface. The Translator is the adapter.

// What the CEO expects, someone who can receive a message in English
public interface IEnglishSpeaker
{
    void Speak(string message);
}

// The Japanese team member, speaks only Japanese (the adaptee)
public class JapaneseTeamMember
{
    public void SpeakJapanese(string message)
    {
        Console.WriteLine($"Team member (Japanese): {message}");
    }
}

// The Translator, adapts the Japanese speaker to the English interface
public class Translator : IEnglishSpeaker
{
    private readonly JapaneseTeamMember _teamMember;

    public Translator(JapaneseTeamMember teamMember)
    {
        _teamMember = teamMember;
    }

    public void Speak(string message)
    {
        string translated = TranslateToJapanese(message);
        _teamMember.SpeakJapanese(translated);
    }

    private string TranslateToJapanese(string english) => english switch
    {
        "Good morning, team."         => "おはようございます、チームの皆さん。",
        "Please review the proposal." => "提案書を確認してください。",
        _                             => $"[Japanese: {english}]"
    };
}

// The CEO, only knows how to talk to an IEnglishSpeaker
public class CEO
{
    private readonly IEnglishSpeaker _speaker;

    public CEO(IEnglishSpeaker speaker)
    {
        _speaker = speaker;
    }

    public void Address(string message)
    {
        Console.WriteLine($"CEO (English): {message}");
        _speaker.Speak(message);
    }
}

Now let's see it in action:

JapaneseTeamMember teamMember = new JapaneseTeamMember();
IEnglishSpeaker translator    = new Translator(teamMember);
CEO ceo = new CEO(translator);

ceo.Address("Good morning, team.");
ceo.Address("Please review the proposal.");

Output:

CEO (English): Good morning, team.
Team member (Japanese): おはようございます、チームの皆さん。
CEO (English): Please review the proposal.
Team member (Japanese): 提案書を確認してください。

The CEO never knew about JapaneseTeamMember. The team never knew about the CEO's interface. The Translator made both sides work together without touching either. That's the Adapter.

When to Use it

Use Adapter when you want to use an existing class but its interface doesn't match what your code expects.

It's also helpful when you want to create a reusable class that cooperates with classes that don't have compatible interfaces.

And reach for it when you need to integrate a third-party library or legacy code without modifying it.

2. The Bridge Design Pattern

Real World Example

Think of a TV remote control and a television. The remote is one thing and the TV is another. You can have a basic remote or a smart remote. You can have a Sony TV or a Samsung TV. Any remote works with any TV you're not locked in. Buy a new Samsung TV, and your old remote still works. Buy a smart universal remote, and it works with every TV you own. Neither side needs to know the inner details of the other.

That's the Bridge. The abstraction (remote) and the implementation (TV) are two separate hierarchies that can grow and change completely independently of each other.

Problems it solves:

• What if every remote was hardwired to one specific TV brand? You would need a SonyBasicRemote, a SamsungBasicRemote, a SonySmartRemote, a SamsungSmartRemote...and so on. One class for every combination. Adding one new TV brand would double your remote classes. The Bridge stops this explosion.

• What if you want to add a new remote type without touching the TVs? With Bridge, you just create a new remote class. The TVs are untouched.

• What if you want to add a new TV brand without touching the remotes? Same answer. You add a new TV class. Every existing remote already works with it.

In simple terms, you split a large class into two separate hierarchies (the abstraction and the implementation) so each can be changed and extended without affecting the other.

Wikipedia describes it like this:

"The bridge pattern is a design pattern used in software engineering that is meant to decouple an abstraction from its implementation so that the two can vary independently." (Source)

Programming Example:

The remote control is the abstraction and the TV brand is the implementation. They're connected through a bridge (the ITV interface), but neither hierarchy depends on the other's details.

// The implementation interface — what any TV must be able to do
public interface ITV
{
    void TurnOn();
    void TurnOff();
    void SetChannel(int channel);
    void SetVolume(int volume);
}

// Concrete implementations — each brand handles things its own way
public class SonyTV : ITV
{
    public void TurnOn()           => Console.WriteLine("Sony TV: Powering on. BRAVIA display ready.");
    public void TurnOff()          => Console.WriteLine("Sony TV: Shutting down.");
    public void SetChannel(int ch) => Console.WriteLine($"Sony TV: Switching to channel {ch}.");
    public void SetVolume(int vol) => Console.WriteLine($"Sony TV: Volume set to {vol}.");
}

public class SamsungTV : ITV
{
    public void TurnOn()           => Console.WriteLine("Samsung TV: Turning on. Smart Hub loading.");
    public void TurnOff()          => Console.WriteLine("Samsung TV: Powering off.");
    public void SetChannel(int ch) => Console.WriteLine($"Samsung TV: Channel {ch} selected.");
    public void SetVolume(int vol) => Console.WriteLine($"Samsung TV: Volume at {vol}.");
}

// The abstraction — the remote holds a reference to whichever TV it controls
public abstract class RemoteControl
{
    protected ITV _tv;

    protected RemoteControl(ITV tv) { _tv = tv; }

    public abstract void TurnOn();
    public abstract void TurnOff();
    public abstract void SetChannel(int channel);
}

// Refined abstraction — a basic remote, does exactly what the TV does
public class BasicRemote : RemoteControl
{
    public BasicRemote(ITV tv) : base(tv) { }

    public override void TurnOn()           => _tv.TurnOn();
    public override void TurnOff()          => _tv.TurnOff();
    public override void SetChannel(int ch) => _tv.SetChannel(ch);
}

// Refined abstraction — a smart remote, adds its own behaviour on top
public class SmartRemote : RemoteControl
{
    public SmartRemote(ITV tv) : base(tv) { }

    public override void TurnOn()
    {
        Console.WriteLine("Smart Remote: Activating voice control.");
        _tv.TurnOn();
    }

    public override void TurnOff()
    {
        Console.WriteLine("Smart Remote: Saving watch history.");
        _tv.TurnOff();
    }

    public override void SetChannel(int ch)
    {
        Console.WriteLine("Smart Remote: Looking up channel guide.");
        _tv.SetChannel(ch);
    }

    public void SetVolume(int vol) => _tv.SetVolume(vol);
}

Now let's see it in action:

// Basic remote paired with a Sony TV
Console.WriteLine("--- Basic Remote + Sony TV ---");
RemoteControl basicSony = new BasicRemote(new SonyTV());
basicSony.TurnOn();
basicSony.SetChannel(5);
basicSony.TurnOff();

// Smart remote paired with a Samsung TV
Console.WriteLine("\n--- Smart Remote + Samsung TV ---");
SmartRemote smartSamsung = new SmartRemote(new SamsungTV());
smartSamsung.TurnOn();
smartSamsung.SetChannel(10);
smartSamsung.SetVolume(20);
smartSamsung.TurnOff();

// Swap freely — smart remote now with Sony, no code changes needed
Console.WriteLine("\n--- Smart Remote + Sony TV ---");
SmartRemote smartSony = new SmartRemote(new SonyTV());
smartSony.TurnOn();
smartSony.SetChannel(3);
smartSony.TurnOff();

Output:

--- Basic Remote + Sony TV ---
Sony TV: Powering on. BRAVIA display ready.
Sony TV: Switching to channel 5.
Sony TV: Shutting down.

--- Smart Remote + Samsung TV ---
Smart Remote: Activating voice control.
Samsung TV: Turning on. Smart Hub loading.
Smart Remote: Looking up channel guide.
Samsung TV: Channel 10 selected.
Samsung TV: Volume at 20.
Smart Remote: Saving watch history.
Samsung TV: Powering off.

--- Smart Remote + Sony TV ---
Smart Remote: Activating voice control.
Sony TV: Powering on. BRAVIA display ready.
Smart Remote: Looking up channel guide.
Sony TV: Switching to channel 3.
Smart Remote: Saving watch history.
Sony TV: Shutting down.

The same SmartRemote worked with both Sony and Samsung without any changes. Adding a new TV brand like LG means creating one new class, and every existing remote works with it immediately. That's the Bridge.

When to Use it

Use the Bridge pattern when you want to avoid a permanent binding between an abstraction and its implementation, so either can be swapped at runtime.

You can also use it when both the abstraction and the implementation should be independently extensible through subclassing.

And it's a good fit when changes to the implementation should have no impact on the client code. The client shouldn't need to be recompiled.

3. The Composite Design Pattern

Real World Example

Think of a company organisation chart. A company has a CEO. Under the CEO are department heads, each leading a department full of employees. Under some departments are even smaller sub-teams.

Now imagine you want to know the total salary cost. You can ask a single employee they tell you their salary. You can ask a whole department, which adds up every person inside it, including nested teams. Or you can ask the entire company: it rolls up every salary across every level.

The same question, asked the same way, whether you're talking to one person or thousands.

That's the Composite pattern. Individual items and groups of items share the same interface. The caller never needs to know which one they're dealing with.

Problems it solves:

• What if you had to write different code to handle a single employee versus a whole department? You would end up with if checks everywhere just to figure out what you're talking to. Composite removes that entirely: one interface, always.

• What if departments can contain other departments? Composite handles any depth of nesting naturally. The caller just asks the top of the tree and the operation flows down automatically.

• What if you want to add a new type of team or role? You implement the same interface. Everything above it in the tree keeps working without any changes.

In simple terms, you compose objects into tree structures. This lets individual objects and groups of objects be treated through the same interface, so the caller never has to care about the difference.

Wikipedia describes it like this:

"The composite pattern describes a group of objects that are treated the same way as a single instance of the same type of object. The intent of a composite is to compose objects into tree structures to represent part-whole hierarchies." (Source)

Programming Example:

Every node in the tree (whether a single employee or an entire department) implements IEmployee. The caller treats them identically.

// The component interface — every leaf and composite shares this contract
public interface IEmployee
{
    string Name    { get; }
    int    GetSalary();
    void   GetDetails(string indent = "");
}

// The leaf — a single employee with no reports
public class Employee : IEmployee
{
    private readonly int _salary;

    public string Name { get; }

    public Employee(string name, int salary)
    {
        Name    = name;
        _salary = salary;
    }

    public int  GetSalary()                    => _salary;
    public void GetDetails(string indent = "") => Console.WriteLine($"{indent}- {Name} (£{_salary:N0})");
}

// The composite — a department that holds employees or other departments
public class Department : IEmployee
{
    private readonly List<IEmployee> _members = new();

    public string Name { get; }

    public Department(string name) { Name = name; }

    public void Add(IEmployee employee)    => _members.Add(employee);
    public void Remove(IEmployee employee) => _members.Remove(employee);

    public int GetSalary() => _members.Sum(m => m.GetSalary());

    public void GetDetails(string indent = "")
    {
        Console.WriteLine($"{indent}[{Name}] Total: £{GetSalary():N0}");
        foreach (var member in _members)
            member.GetDetails(indent + "  ");
    }
}

Now let's see it in action:

// Individual employees
var ceo        = new Employee("Alice (CEO)",        120_000);
var cto        = new Employee("Bob (CTO)",           95_000);
var dev1       = new Employee("Carol (Developer)",   65_000);
var dev2       = new Employee("David (Developer)",   62_000);
var cfo        = new Employee("Eve (CFO)",           90_000);
var accountant = new Employee("Frank (Accountant)",  55_000);

// Build the Engineering department
var engineering = new Department("Engineering");
engineering.Add(cto);
engineering.Add(dev1);
engineering.Add(dev2);

// Build the Finance department
var finance = new Department("Finance");
finance.Add(cfo);
finance.Add(accountant);

// Build the whole company
var company = new Department("Acme Corp");
company.Add(ceo);
company.Add(engineering);
company.Add(finance);

// Ask the whole company — one call, rolls up everything
Console.WriteLine("=== Full Company ===");
company.GetDetails();

// Ask just one department — same call, same interface
Console.WriteLine("\n=== Engineering Only ===");
engineering.GetDetails();

// Ask a single employee — same call, same interface
Console.WriteLine("\n=== Single Employee ===");
dev1.GetDetails();

Output:

=== Full Company ===
[Acme Corp] Total: £487,000
  - Alice (CEO) (£120,000)
  [Engineering] Total: £222,000
    - Bob (CTO) (£95,000)
    - Carol (Developer) (£65,000)
    - David (Developer) (£62,000)
  [Finance] Total: £145,000
    - Eve (CFO) (£90,000)
    - Frank (Accountant) (£55,000)

=== Engineering Only ===
[Engineering] Total: £222,000
  - Bob (CTO) (£95,000)
  - Carol (Developer) (£65,000)
  - David (Developer) (£62,000)

=== Single Employee ===
- Carol (Developer) (£65,000)

company.GetDetails(), engineering.GetDetails(), and dev1.GetDetails(): the same call on three different levels of the tree. The caller never checked what it was talking to. That's the Composite pattern.

When to Use it

Use Composite when you need to represent part-whole hierarchies, like trees where individual items and groups of items need to be used interchangeably.

It also works well when you want client code to treat single objects and collections of objects uniformly, without any special-casing.

And it's a good fit when the structure can be nested to any depth and that depth shouldn't affect how the caller interacts with it.

4. The Decorator Design Pattern

Real World Example

Think of ordering a coffee at a cafe. You start with a plain espresso. Then you ask for milk. Then vanilla syrup. Then whipped cream on top. Each addition wraps around or adds to what was already there, adding its own cost and its own description. The espresso at the centre never changes. You're just layering on top of it, one addition at a time. You could add two shots of syrup. You could skip the milk entirely. Every combination is possible without creating a new type of coffee for each one.

That's the Decorator pattern. You start with a base object and wrap it in layers. Each layer adds its own behaviour and then delegates to whatever is underneath it.

Problems it solves:

• What if you needed a class for every combination? EspressoWithMilk, EspressoWithMilkAndVanilla, EspressoWithMilkAndVanillaAndCream...the list explodes. Decorator adds behaviour at runtime, so you never need those classes.

• What if the base coffee shouldn't change? It does not. The espresso class stays untouched. The decorators wrap around it and extend it independently.

• What if a new topping needs to be added? You create one new decorator class. Every existing combination still works exactly as before.

In simple terms, you wrap an object in one or more layers, where each layer adds its own behaviour before or after delegating to the layer beneath it.

Wikipedia describes it like this:

"The decorator pattern is a design pattern that allows behaviour to be added to an individual object, dynamically, without affecting the behaviour of other instances of the same class." (Source)

Programming Example:

The coffee is the component. Each topping is a decorator. Every decorator wraps the component and adds to its description and cost.

// The component interface — every coffee, plain or decorated, shares this
public interface ICoffee
{
    string GetDescription();
    double GetCost();
}

// The base component — a plain espresso
public class Espresso : ICoffee
{
    public string GetDescription() => "Espresso";
    public double GetCost()        => 1.00;
}

// The base decorator — wraps any ICoffee and delegates to it
public abstract class CoffeeDecorator : ICoffee
{
    protected readonly ICoffee _coffee;

    protected CoffeeDecorator(ICoffee coffee) { _coffee = coffee; }

    public virtual string GetDescription() => _coffee.GetDescription();
    public virtual double GetCost()        => _coffee.GetCost();
}

// Concrete decorators — each one adds its own layer
public class Milk : CoffeeDecorator
{
    public Milk(ICoffee coffee) : base(coffee) { }

    public override string GetDescription() => _coffee.GetDescription() + ", Milk";
    public override double GetCost()        => _coffee.GetCost() + 0.30;
}

public class VanillaSyrup : CoffeeDecorator
{
    public VanillaSyrup(ICoffee coffee) : base(coffee) { }

    public override string GetDescription() => _coffee.GetDescription() + ", Vanilla Syrup";
    public override double GetCost()        => _coffee.GetCost() + 0.50;
}

public class WhippedCream : CoffeeDecorator
{
    public WhippedCream(ICoffee coffee) : base(coffee) { }

    public override string GetDescription() => _coffee.GetDescription() + ", Whipped Cream";
    public override double GetCost()        => _coffee.GetCost() + 0.75;
}

Now let's see it in action:

// A plain espresso
ICoffee order = new Espresso();
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

// Wrap it with milk
order = new Milk(order);
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

// Wrap it with vanilla syrup on top
order = new VanillaSyrup(order);
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

// Wrap it with whipped cream on top of that
order = new WhippedCream(order);
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

Output:

Espresso => £1.00
Espresso, Milk => £1.30
Espresso, Milk, Vanilla Syrup => £1.80
Espresso, Milk, Vanilla Syrup, Whipped Cream => £2.55

Each line is a new layer wrapped around the previous one. The espresso never changed. The cost and description grew with every wrapper. That's the Decorator pattern.

When to Use it

Use the Decorator pattern when you want to add responsibilities to individual objects without affecting other objects of the same class.

It's also a good choice when subclassing would lead to an explosion of classes to cover every possible combination of behaviours.

And use it when you need to be able to stack behaviours in any order at runtime, independently of each other.

5. The Facade Design Pattern

Real World Example

Think of clicking "Place Order" on a shopping website. In that single click, several things happen behind the scenes: the system checks whether the item is in stock, your payment is charged, a shipping label is generated, and a confirmation email is sent to you. You don't see any of that. You click one button and get one result. The complexity of four separate systems is hidden behind a single, clean action.

That's the Facade pattern: one simple interface in front of many complex moving parts. The caller doesn't need to know what's happening behind the scenes.

Problems it solves:

• What if the client had to call each subsystem directly? Check inventory, then process payment, then generate a label, and then send an email, all in the right order, handling each failure separately. The Facade wraps all of that into one call.

• What if one of the subsystems changes? The Facade absorbs the change. The client code never needs to know. Only the Facade is updated.

• What if different clients need the same flow? They all call the same Facade method. The logic is in one place, not duplicated across every caller.

In simple terms, you provide a single, simple interface that hides the complexity of a set of subsystems behind it.

Wikipedia describes it like this:

"The facade pattern (also spelled façade) is a software-design pattern commonly used in object-oriented programming. Analogous to a facade in architecture, a facade is an object that serves as a front-facing interface masking more complex underlying or structural code."(Source)

Programming Example:

Each subsystem does its own job. The OrderFacade is the single entry point that coordinates all of them. The client only ever talks to the facade.

// Subsystem 1: checks whether the item is available
public class InventoryService
{
    public bool CheckStock(string item)
    {
        Console.WriteLine($"Inventory: Checking stock for {item}.");
        return true;
    }
}

// Subsystem 2: handles the payment
public class PaymentService
{
    public bool ProcessPayment(string cardNumber, double amount)
    {
        Console.WriteLine($"Payment: Charging £{amount:F2} to card ending {cardNumber[^4..]}.");
        return true;
    }
}

// Subsystem 3: generates a shipping label
public class ShippingService
{
    public string GenerateLabel(string item, string address)
    {
        Console.WriteLine($"Shipping: Generating label for {item} to {address}.");
        return "TRACK-29384";
    }
}

// Subsystem 4: sends the confirmation email
public class EmailService
{
    public void SendConfirmation(string email, string trackingCode)
    {
        Console.WriteLine($"Email: Confirmation sent to {email}. Tracking code: {trackingCode}.");
    }
}

// The Facade — one method, hides all four subsystems
public class OrderFacade
{
    private readonly InventoryService _inventory = new();
    private readonly PaymentService   _payment   = new();
    private readonly ShippingService  _shipping  = new();
    private readonly EmailService     _email     = new();

    public void PlaceOrder(string item, string cardNumber, double amount, string address, string email)
    {
        Console.WriteLine("=== Placing Order ===");

        if (!_inventory.CheckStock(item))
        {
            Console.WriteLine("Order failed: item out of stock.");
            return;
        }

        if (!_payment.ProcessPayment(cardNumber, amount))
        {
            Console.WriteLine("Order failed: payment declined.");
            return;
        }

        string trackingCode = _shipping.GenerateLabel(item, address);
        _email.SendConfirmation(email, trackingCode);

        Console.WriteLine($"\nOrder complete. Your tracking code is {trackingCode}.");
    }
}

Now let's see it in action:

OrderFacade store = new OrderFacade();

store.PlaceOrder(
    item:       "Wireless Headphones",
    cardNumber: "4111111111111234",
    amount:     79.99,
    address:    "42 Maple Street, London",
    email:      "customer@email.com"
);

Output:

=== Placing Order ===
Inventory: Checking stock for Wireless Headphones.
Payment: Charging £79.99 to card ending 1234.
Shipping: Generating label for Wireless Headphones to 42 Maple Street, London.
Email: Confirmation sent to customer@email.com. Tracking code: TRACK-29384.

Order complete. Your tracking code is TRACK-29384.

The client called one method. Four subsystems ran in the right order. None of that complexity was visible to the caller. That is the Facade.

When to Use it

Use Facade when you want to provide a simple interface to a complex subsystem so callers aren't burdened by its internals.

It also works well when you want to layer your system so that high-level code talks to facades, not directly to low-level subsystems.

And it's a good choice when you want a single entry point that coordinates a sequence of steps across multiple services.

6. The Flyweight Design Pattern

Real World Example

Think of a game that renders a forest. The forest has ten thousand trees. Each tree has a type name, a colour, and a texture. But most of those trees are Oaks, and all Oaks look exactly the same.

Creating ten thousand separate objects, each storing the same name, colour, and texture, wastes enormous amounts of memory. Instead, you create one shared Oak object that holds all that data. Every Oak tree in the forest points to that same shared object and only stores its own position on the map.

That's the Flyweight pattern. The data that's the same across many instances is shared. The data that's unique per instance is stored separately and passed in only when needed.

Problems it solves:

• What if you created a full object for every single tree? With ten thousand trees, you store the same name, colour, and texture ten thousand times. Flyweight stores that shared data once and reuses it everywhere.

• What if a new tree type is introduced? The factory creates one new shared object for it. Every tree of that type immediately uses it without any extra memory.

• What if the forest needs to render each tree at its own position? The position is unique per tree, so it's stored on the tree itself and passed to the shared object only at render time. The shared object never holds it.

In simple terms, you split an object's data into what's shared across many instances and what's unique per instance. Share the common part. Pass the unique part in only when needed.

Wikipedia describes it like this:

"A flyweight is an object that minimizes memory usage by sharing as much data as possible with other similar objects. It is a way to use objects in large numbers when a simple repeated representation would use an unacceptable amount of memory." (Source)

Programming ExampleL

TreeType is the flyweight: it holds shared data. Tree holds only the unique position and a reference to a shared TreeType. The factory ensures each TreeType is created only once.

// The flyweight — holds shared intrinsic state (same for all trees of this type)
public class TreeType
{
    public string Name    { get; }
    public string Colour  { get; }
    public string Texture { get; }

    public TreeType(string name, string colour, string texture)
    {
        Name    = name;
        Colour  = colour;
        Texture = texture;
    }

    public void Render(int x, int y)
    {
        Console.WriteLine($"Rendering {Name} tree ({Colour}, {Texture}) at ({x}, {y})");
    }
}

// The flyweight factory — creates and caches tree types so they are never duplicated
public class TreeTypeFactory
{
    private readonly Dictionary<string, TreeType> _cache = new();

    public TreeType GetTreeType(string name, string colour, string texture)
    {
        string key = $"{name}_{colour}_{texture}";

        if (!_cache.ContainsKey(key))
        {
            Console.WriteLine($"Factory: Creating new TreeType for '{name}'.");
            _cache[key] = new TreeType(name, colour, texture);
        }

        return _cache[key];
    }

    public int TotalTypes => _cache.Count;
}

// The context — holds unique extrinsic state (position) and a reference to a shared flyweight
public class Tree
{
    private readonly int      _x;
    private readonly int      _y;
    private readonly TreeType _type;

    public Tree(int x, int y, TreeType type)
    {
        _x    = x;
        _y    = y;
        _type = type;
    }

    public void Render() => _type.Render(_x, _y);
}

// The forest — plants trees using shared flyweights
public class Forest
{
    private readonly List<Tree>      _trees   = new();
    private readonly TreeTypeFactory _factory = new();

    public void PlantTree(int x, int y, string name, string colour, string texture)
    {
        TreeType type = _factory.GetTreeType(name, colour, texture);
        _trees.Add(new Tree(x, y, type));
    }

    public void Render()
    {
        foreach (var tree in _trees)
            tree.Render();
    }

    public int TreeCount     => _trees.Count;
    public int TreeTypeCount => _factory.TotalTypes;
}

Now let's see it in action:

Forest forest = new Forest();

// Plant 6 trees — but only 2 unique types
forest.PlantTree(1,  5,  "Oak",  "Dark Green",  "Rough bark");
forest.PlantTree(3,  12, "Oak",  "Dark Green",  "Rough bark");
forest.PlantTree(7,  2,  "Oak",  "Dark Green",  "Rough bark");
forest.PlantTree(10, 8,  "Pine", "Light Green", "Smooth bark");
forest.PlantTree(15, 3,  "Pine", "Light Green", "Smooth bark");
forest.PlantTree(20, 14, "Pine", "Light Green", "Smooth bark");

forest.Render();

Console.WriteLine($"\nTrees planted:              {forest.TreeCount}");
Console.WriteLine($"Unique tree types in memory: {forest.TreeTypeCount}");

Output:

Factory: Creating new TreeType for 'Oak'.
Factory: Creating new TreeType for 'Pine'.
Rendering Oak tree (Dark Green, Rough bark) at (1, 5)
Rendering Oak tree (Dark Green, Rough bark) at (3, 12)
Rendering Oak tree (Dark Green, Rough bark) at (7, 2)
Rendering Pine tree (Light Green, Smooth bark) at (10, 8)
Rendering Pine tree (Light Green, Smooth bark) at (15, 3)
Rendering Pine tree (Light Green, Smooth bark) at (20, 14)

Trees planted:              6
Unique tree types in memory: 2

Six trees, but only two TreeType objects were ever created. Scale that to ten thousand trees and the factory still creates exactly two. The positions are unique per tree, and the appearance is shared. That's the Flyweight.

When to Use it

Use Flyweight when your application needs to create a very large number of similar objects that would otherwise consume too much memory.

It's also useful when most of the object's state can be made shared across instances, with only a small part being unique per instance.

And it's a good choice when the unique part of the state can be passed in externally rather than stored inside every object.

7. The Proxy Design Pattern

Real World Example

Think of a security guard at the entrance of an office building. You can't walk straight into the building. You have to go through the guard first. The guard checks your name against the authorised list, logs your visit, and only then lets you through. If you're not on the list, you're turned away. The building itself never deals with any of that. It just lets people in. All the checking, logging, and decision-making happens at the guard (the proxy) before the building ever gets involved.

That's the Proxy pattern. It sits between the caller and the real object, controls what gets through, and can add behaviour like access checks or logging without the real object knowing anything about it.

Problems it solves:

• What if anyone could walk straight into the building? There would be no access control. The proxy intercepts every request and decides whether it should be allowed through.

• What if you need to log every entry without changing the building? The proxy handles it. The real building stays simple and focused on its own job.

• What if the real object is expensive to create and you want to delay that? The proxy can hold off creating it until someone actually passes the check and needs it.

In simple terms, you place an object in front of another object to control access to it. The caller thinks it's talking directly to the real object, but the proxy is handling it first.

Wikipedia describes it like this:

"A proxy, in its most general form, is a class functioning as an interface to something else. The proxy could interface to anything: a network connection, a large object in memory, a file, or some other resource that is expensive or impossible to duplicate." (Source)

Programming Example:

The client talks to IBuilding. The SecurityGuard is the proxy: it implements the same interface, controls access, and only lets authorised visitors through to the OfficeBuilding.

// The subject interface — the building and the proxy both implement this
public interface IBuilding
{
    void Enter(string visitorName);
}

// The real subject — the actual building, just grants entry
public class OfficeBuilding : IBuilding
{
    public void Enter(string visitorName)
    {
        Console.WriteLine($"Building: {visitorName} has entered.");
    }
}

// The proxy — the security guard controls who gets through
public class SecurityGuard : IBuilding
{
    private readonly OfficeBuilding _building          = new();
    private readonly List<string>   _authorisedVisitors = new() { "Alice", "Bob", "Carol" };

    public void Enter(string visitorName)
    {
        Console.WriteLine($"Guard: {visitorName} is requesting entry.");

        if (_authorisedVisitors.Contains(visitorName))
        {
            Console.WriteLine("Guard: ID verified. Access granted.");
            _building.Enter(visitorName);
        }
        else
        {
            Console.WriteLine($"Guard: {visitorName} is not on the list. Access denied.");
        }
    }
}

Now let's see it in action:

IBuilding entrance = new SecurityGuard();

entrance.Enter("Alice");
Console.WriteLine();
entrance.Enter("David");
Console.WriteLine();
entrance.Enter("Bob");

Output:

Guard: Alice is requesting entry.
Guard: ID verified. Access granted.
Building: Alice has entered.

Guard: David is requesting entry.
Guard: David is not on the list. Access denied.

Guard: Bob is requesting entry.
Guard: ID verified. Access granted.
Building: Bob has entered.

The client called Enter() on what it thought was the building. It was actually the security guard. The guard decided what happened. The building only ever saw the people who were allowed through. That's the Proxy.

When to Use it

Use Proxy when you need access control, like only letting certain callers through to the real object.

It's a good fit when you want to add behaviour such as logging, caching, or validation without changing the real object.

And you can use it when the real object is expensive to create and you want to delay or guard that creation until it's truly needed.

Behavioral Design Patterns

Simply put, behavioral patterns are all about how objects communicate and share responsibility. They focus on the assignment of responsibilities between objects, and how objects cooperate to get a job done.

Wikipedia describes them as:

"In software engineering, behavioral design patterns are design patterns that identify common communication patterns among objects. By doing so, these patterns increase flexibility in carrying out this communication." (Source)

Behavioral design patterns describe how objects interact and distribute responsibility, not just how they're structured. They focus on communication between objects: who talks to whom, and how much each side knows about the other.

There are 11 behavioral design patterns:

1. Chain of Responsibility: Passes a request along a chain of handlers, letting each one decide to handle it or pass it on.

2. Command: Encapsulates a request as an object, letting you parameterize clients, queue actions, and support undo.

3. Interpreter: Given a language, defines a representation for its grammar along with an interpreter that evaluates sentences in it.

4. Iterator: Provides a way to access the elements of a collection sequentially without exposing how it's built underneath.

5. Mediator: Defines an object that encapsulates how a set of objects interact, so they don't refer to each other directly.

6. Memento: Captures an object's internal state so it can be restored later, without breaking encapsulation.

7. Observer: Defines a one-to-many dependency so that when one object changes state, everything depending on it is notified automatically.

8. State: Lets an object change its behaviour when its internal state changes, as if it had changed its class.

9. Strategy: Defines a family of interchangeable algorithms and lets the client pick which one to use at runtime.

10. Template Method: Defines the skeleton of an algorithm in a method, leaving some steps for subclasses to fill in.

11. Visitor: Lets you define a new operation without changing the classes of the elements it operates on.

1. The Chain of Responsibility Design Pattern

Real World Example

Think of an expense approval process at a company. An employee submits a request to their director. If the amount is small enough, the director approves it and that's the end of it. If it's too large for the director to sign off on, it goes up to the vice president. If it's still too large, it goes up to the chief executive.

Each person in the chain only needs to know two things: what they're allowed to approve, and who to hand it to if they can't. The employee never needs to know who ends up approving it.

That's the Chain of Responsibility design pattern. A request travels along a chain of handlers until one of them deals with it, and each handler only cares about its own link in that chain.

Problems it solves:

• What if the sender had to know exactly who should handle the request? That would tie the sender to a specific handler and break the moment the approval structure changed. The chain lets the sender submit the request without knowing who will end up handling it.

• What if one handler could only ever approve or reject, with no fallback? Requests that fell outside its authority would simply fail. The chain lets a handler pass what it can't deal with further along.

• What if you needed to change the approval structure? Rewiring which handler comes after which is enough. Neither the sender nor the other handlers need to change.

In simple terms, you pass a request along a chain of handlers. Each handler decides whether to deal with it or hand it off to the next one in line.

Wikipedia describes it like this:

"In object-oriented design, the chain-of-responsibility pattern is a behavioral design pattern consisting of a source of command objects and a series of processing objects. Each processing object contains logic that defines the types of command objects that it can handle; the rest are passed to the next processing object in the chain."

(Source)

Programming Example:

Each Approver knows its own approval limit and holds a reference to the next approver in the chain. The ExpenseRequest is passed along until someone can approve it, or nobody can.

// The request that travels along the chain
public class ExpenseRequest
{
    public string Description { get; }
    public decimal Amount     { get; }

    public ExpenseRequest(string description, decimal amount)
    {
        Description = description;
        Amount      = amount;
    }
}

// The handler, every link in the chain implements this
public abstract class Approver
{
    private Approver? _next;

    public void SetNext(Approver next) => _next = next;

    public void Approve(ExpenseRequest request)
    {
        if (CanApprove(request))
        {
            Console.WriteLine($"{GetType().Name}: Approved '{request.Description}' (${request.Amount}).");
        }
        else if (_next is not null)
        {
            Console.WriteLine($"{GetType().Name}: Can't approve '{request.Description}' (${request.Amount}). Passing it up.");
            _next.Approve(request);
        }
        else
        {
            Console.WriteLine($"{GetType().Name}: No one left to approve '{request.Description}' (${request.Amount}). Request denied.");
        }
    }

    protected abstract bool CanApprove(ExpenseRequest request);
}

// Concrete handlers, each with its own approval limit
public class Director : Approver
{
    protected override bool CanApprove(ExpenseRequest request) => request.Amount <= 1000;
}

public class VicePresident : Approver
{
    protected override bool CanApprove(ExpenseRequest request) => request.Amount <= 20000;
}

public class Chief : Approver
{
    protected override bool CanApprove(ExpenseRequest request) => request.Amount <= 50000;
}

Now let's see it in action:

Approver directorApprover = new Director();
Approver vpApprover       = new VicePresident();
Approver ceoApprover      = new Chief();

directorApprover.SetNext(vpApprover);
vpApprover.SetNext(ceoApprover);

directorApprover.Approve(new ExpenseRequest("Laptop", 800));
Console.WriteLine();
directorApprover.Approve(new ExpenseRequest("Team offsite", 12000));
Console.WriteLine();
directorApprover.Approve(new ExpenseRequest("New office lease", 90000));

Output:

Director: Approved 'Laptop' ($800).

Director: Can't approve 'Team offsite' ($12000). Passing it up.
VicePresident: Approved 'Team offsite' ($12000).

Director: Can't approve 'New office lease' ($90000). Passing it up.
VicePresident: Can't approve 'New office lease' ($90000). Passing it up.
Chief: No one left to approve 'New office lease' ($90000). Request denied.

The employee only ever talked to the director. Whether the director, the vice president, or the chief ended up approving it, was decided by the chain itself, not the employee.

When to Use it

Use Chain of Responsibility when more than one object might handle a request, and the handler isn't known in advance.

It's also a good choice when you want to issue a request without specifying the receiver explicitly.

And it's helpful when the set of handlers, and their order, should be configurable rather than hard-coded.

2. The Command Design Pattern

Real World Example

Think of a universal remote control. Every button is programmed to do one specific thing: turn a light on, turn a light off, and so on. When you press a button, the remote doesn't know or care how the light actually works internally. It just triggers the action that button was set up to perform. And because each button's action is a self-contained thing, the remote can also press it in reverse, undoing what it just did.

That's the Command pattern. A request "turn the light on" is wrapped up as its own object. The thing that triggers it doesn't need to know anything about how it's carried out.

Problems it solves:

• What if the button had to know exactly how the light worked? Every button would need to be rewritten if the light's internals changed. Wrapping the action as a command means the remote never touches those details.

• What if you wanted to undo the last action? Without a command object there's nothing to reverse, only a completed side effect. Wrapping the action gives you something you can also unwind.

• What if you wanted to queue actions, log them, or trigger them later? A plain method call happens immediately and leaves nothing behind. A command is an object, so it can be stored, queued, and replayed.

In simple terms, you wrap a request up as an object, so the thing that triggers it doesn't need to know how it's carried out, and the action itself can be queued, logged, or undone.

Wikipedia describes it like this:

"The command pattern is a behavioral design pattern in which an object is used to encapsulate all information needed to perform an action or trigger an event at a later time." (Source)

Programming Example:

The RemoteControl is the invoker it only knows about ICommand. LightOnCommand and LightOffCommand are the concrete commands, each wrapping the Light receiver and the action to perform on it.

// The command interface, every action implements this
public interface ICommand
{
    void Execute();
    void Undo();
}

// The receiver, the object that actually does the work
public class Light
{
    private readonly string _room;

    public Light(string room) => _room = room;

    public void On()  => Console.WriteLine($"{_room} light: turned on.");
    public void Off() => Console.WriteLine($"{_room} light: turned off.");
}

// Concrete commands, each wraps a receiver and an action
public class LightOnCommand : ICommand
{
    private readonly Light _light;

    public LightOnCommand(Light light) => _light = light;

    public void Execute() => _light.On();
    public void Undo()    => _light.Off();
}

public class LightOffCommand : ICommand
{
    private readonly Light _light;

    public LightOffCommand(Light light) => _light = light;

    public void Execute() => _light.Off();
    public void Undo()    => _light.On();
}

// The invoker, it holds a command and triggers it without knowing what it does
public class RemoteControl
{
    private ICommand? _command;

    public void SetCommand(ICommand command) => _command = command;

    public void PressButton() => _command?.Execute();
    public void PressUndo()   => _command?.Undo();
}

Now let's see it in action:

var livingRoomLight = new Light("Living Room");
var remote          = new RemoteControl();

remote.SetCommand(new LightOnCommand(livingRoomLight));
remote.PressButton();

remote.SetCommand(new LightOffCommand(livingRoomLight));
remote.PressButton();

Console.WriteLine();
Console.WriteLine("Undoing last action...");
remote.PressUndo();

Output:

Living Room light: turned on.
Living Room light: turned off.

Undoing last action...
Living Room light: turned on.

The remote never called _light.On() or _light.Off() directly. It called Execute() and Undo() on whatever command it was holding. That's the Command pattern: the request itself became an object.

When to Use it

Use the Command pattern when you want to parameterize objects with an action to perform, rather than hard-coding it.

Reach for it when you need to queue, log, or support undo for requests.

And consider it when you want to decouple the object that invokes an action from the object that knows how to perform it.

3. The Interpreter Design Pattern

Real World Example

Think of a basic calculator reading an expression like (5 + 3) - 2. Nobody hardcodes a single method that handles every possible expression. Instead, the expression is broken down into small pieces: numbers and operation buttons, each of which knows how to evaluate itself and combine with the others. (5 + 3) - 2 becomes a subtraction of two things: the number 2, and the result of adding 5 and 3. Each piece only needs to know how to interpret itself.

That's the Interpreter pattern. A grammar is represented as a tree of small objects, and each one knows how to evaluate its own little piece of it.

Problems it solves:

• What if you tried to evaluate an entire expression in one big method? It would grow unmanageable the moment the grammar got more complex. Breaking the grammar into small classes, one per rule, keeps each piece simple.

• What if the grammar needed to grow? Adding a new operation, like multiplication, is just a new class. The existing pieces don't need to change.

• What if the same expression needed to be evaluated more than once, or in different contexts? Because each piece is just an object, the same tree can be interpreted again without rebuilding it.

In simple terms, you represent a grammar as a tree of small objects, where each object knows how to interpret its own piece of the expression.

Wikipedia describes it like this:

"In computer programming, the interpreter pattern is a design pattern that specifies how to evaluate sentences in a language. The basic idea is to have a class for each symbol (terminal or nonterminal) in a specialized computer language." (Source)

Programming Example:

Number is the terminal expression, a plain value. Add and Subtract are non-terminal expressions, each combining two other expressions. Every node, terminal or not, knows how to Interpret() itself.

// The abstract expression, every node in the grammar implements this
public abstract class Expression
{
    public abstract int Interpret();
}

// A terminal expression, a plain number that needs no further interpretation
public class Number : Expression
{
    private readonly int _value;

    public Number(int value) => _value = value;

    public override int Interpret() => _value;
}

// Non-terminal expressions, each combines other expressions
public class Add : Expression
{
    private readonly Expression _left;
    private readonly Expression _right;

    public Add(Expression left, Expression right)
    {
        _left  = left;
        _right = right;
    }

    public override int Interpret() => _left.Interpret() + _right.Interpret();
}

public class Subtract : Expression
{
    private readonly Expression _left;
    private readonly Expression _right;

    public Subtract(Expression left, Expression right)
    {
        _left  = left;
        _right = right;
    }

    public override int Interpret() => _left.Interpret() - _right.Interpret();
}

Now let's see it in action:

// (5 plus 3) minus 2
Expression expression = new Subtract(
    new Add(new Number(5), new Number(3)),
    new Number(2)
);

Console.WriteLine($"Result: {expression.Interpret()}");

// (10 minus 4) plus (2 plus 2)
Expression another = new Add(
    new Subtract(new Number(10), new Number(4)),
    new Add(new Number(2), new Number(2))
);

Console.WriteLine($"Result: {another.Interpret()}");

Output:

Result: 6
Result: 10

Nothing ever evaluated the whole expression at once. Subtract asked its own _left and _right to interpret themselves, and those asked their own children, all the way down to plain numbers. That's the Interpreter pattern: the grammar interprets itself, one small piece at a time.

When to Use it

Use Interpreter when you have a simple language or grammar to evaluate, and representing it as a tree of expressions keeps it manageable.

It also works well when the grammar is relatively stable. For example, adding new rules means adding new classes, not rewriting existing ones.

And it's useful when you would rather have many small, focused classes than one large method trying to parse and evaluate everything at once.

4. The Iterator Design Pattern

Real World Example

Think of a bookshelf. You want to go through it one book at a time, from left to right, without needing to know whether the books are held in an array, multiple piles and stacks, or something else entirely. All you need is a way to ask "what's next?" and to know when you've reached the end. How the shelf actually stores its books internally is none of your concern.

That's the Iterator pattern. It gives you a consistent way to step through a collection, one element at a time, without exposing how that collection is built underneath.

Problems it solves:

• What if the client had to know how the collection was stored internally to loop over it? Any change to that internal structure would break every piece of code that loops over it. The iterator hides that structure behind a simple "get next" interface.

• What if you needed more than one traversal in progress at the same time? A single shared position wouldn't work. Each iterator keeps its own position, so multiple traversals can happen independently.

• What if you wanted to loop over the collection using the language's own foreach? Implementing the iterator interface the language expects means your custom collection gets that support for free.

In simple terms, you give a collection a way to be walked through, one element at a time, without exposing how it's actually built underneath.

Wikipedia describes it like this:

"In object-oriented programming, the iterator pattern is a design pattern in which an iterator is used to traverse a container and access the container's elements." (Source)

Programming Example:

Bookshelf is the aggregate it exposes an IEnumerator<string> without revealing that it stores books in a List<string> internally. BookshelfIterator is the iterator that walks through them one at a time.

// The aggregate, exposes an iterator without revealing how books are stored
public class Bookshelf : IEnumerable<string>
{
    private readonly List<string> _books = new();

    public void Add(string title) => _books.Add(title);

    public IEnumerator<string> GetEnumerator() => new BookshelfIterator(_books);

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
}

// The iterator, walks the collection one book at a time
public class BookshelfIterator : IEnumerator<string>
{
    private readonly List<string> _books;
    private int _position = -1;

    public BookshelfIterator(List<string> books) => _books = books;

    public string Current => _books[_position];

    object IEnumerator.Current => Current;

    public bool MoveNext()
    {
        _position++;
        return _position < _books.Count;
    }

    public void Reset() => _position = -1;

    public void Dispose() { }
}

Now let's see it in action:

var bookshelf = new Bookshelf();
bookshelf.Add("Clean Code");
bookshelf.Add("The Pragmatic Programmer");
bookshelf.Add("Design Patterns");

foreach (var book in bookshelf)
{
    Console.WriteLine($"On the shelf: {book}");
}

Output:

On the shelf: Clean Code
On the shelf: The Pragmatic Programmer
On the shelf: Design Patterns

The foreach loop never touched the List<string> inside Bookshelf directly. It called MoveNext() and Current on the BookshelfIterator, one step at a time. That's the Iterator pattern: the traversal logic lives outside the collection itself.

When to Use it

Use Iterator when you want to traverse a collection without exposing its internal structure.

It's also a good choice when you need to support multiple simultaneous traversals over the same collection.

And try it when you want your custom collection to work with the language's built-in iteration syntax, like foreach.

5. The Mediator Design Pattern

Real World Example

Think of an air traffic control tower. Planes don't radio each other directly to negotiate who lands first. That would be chaos: dozens of pilots all trying to coordinate with each other at once.

Instead, every plane talks only to the tower. The tower knows the state of the runway and tells each plane what to do. The planes never need to know how many other planes are around, or what they're doing.

That's the Mediator pattern. Instead of objects talking to each other directly, they all talk to one central object that coordinates them.

Problems it solves:

• What if every aircraft had to communicate directly with every other aircraft? The number of connections would explode as more aircraft joined, and each one would need to know about all the others. The mediator means each aircraft only needs to know about the tower.

• What if the coordination logic was scattered across every object involved? Changing how landings get prioritised would mean touching every aircraft. With a mediator, that logic lives in one place.

• What if you wanted to add a new aircraft to the system? It only needs to know how to talk to the tower. It doesn't need to be introduced to every other aircraft already in the sky.

In simple terms, instead of letting objects talk to each other directly, you route all communication through one central object that knows how to coordinate them.

Wikipedia describes it like this:

"In software engineering, the mediator pattern defines an object that encapsulates how a set of objects interact. This pattern is considered to be a behavioral pattern due to the way it can alter the program's running behavior." (Source)

Programming Example:

ControlTower is the mediator. It's the only thing an Aircraft ever talks to. It decides whether a plane can land based on the state it holds, and no aircraft ever contacts another aircraft directly.

// The mediator interface
public interface IControlTower
{
    void RequestLanding(Aircraft requester);
}

// The concrete mediator, coordinates all the aircraft instead of letting them talk to each other
public class ControlTower : IControlTower
{
    private readonly List<Aircraft> _aircraft = new();
    private bool _runwayFree = true;

    public void Register(Aircraft aircraft) => _aircraft.Add(aircraft);

    public void RequestLanding(Aircraft requester)
    {
        if (_runwayFree)
        {
            _runwayFree = false;
            Console.WriteLine($"Tower: Runway clear. {requester.Name}, you are cleared to land.");
        }
        else
        {
            Console.WriteLine($"Tower: Runway occupied. {requester.Name}, please hold your position.");
        }
    }
}

// The colleague, only ever talks to the mediator, never to other aircraft directly
public class Aircraft
{
    public string Name { get; }

    private readonly IControlTower _tower;

    public Aircraft(string name, IControlTower tower)
    {
        Name   = name;
        _tower = tower;
    }

    public void RequestLanding()
    {
        Console.WriteLine($"{Name}: Requesting permission to land.");
        _tower.RequestLanding(this);
    }
}

Now let's see it in action:

var tower = new ControlTower();

var flight101 = new Aircraft("Flight 101", tower);
var flight202 = new Aircraft("Flight 202", tower);

tower.Register(flight101);
tower.Register(flight202);

flight101.RequestLanding();
flight202.RequestLanding();

Output:

Flight 101: Requesting permission to land.
Tower: Runway clear. Flight 101, you are cleared to land.
Flight 202: Requesting permission to land.
Tower: Runway occupied. Flight 202, please hold your position.

Flight 101 and Flight 202 never spoke to each other. Neither one even knows the other exists. Both only ever talked to the tower, and the tower decided what happened next. That's the Mediator pattern.

When to Use it

Use Mediator when a group of objects communicate in complex, tangled ways, and you want to centralise that communication.

It's also helpful when you want to reuse objects independently, without them being locked together by direct references to each other.

And reach for it when the way objects interact changes often, and you'd rather change it in one place than in every object involved.

6. The Memento Design Pattern

Real World Example

Think of the undo history in a text editor. Every so often, the editor quietly takes a snapshot of what the document looks like. It doesn't ask the document to expose its internals to do this. It just captures a copy of the content at that moment.

When you press undo, the editor hands that snapshot back, and the document restores itself to exactly how it was. The history keeps a pile of these snapshots, but it never looks inside them or changes them. It only stores them and hands them back.

That's the Memento pattern. It lets you capture and restore an object's state without exposing how that state is structured internally.

Problems it solves:

• What if undo required exposing every private field of the document? That would break encapsulation, and any change to the document's internals would ripple out to whatever handles undo. The memento hides that structure inside an object only the document itself knows how to read.

• What if the history needed to inspect or modify old snapshots? It shouldn't be able to. The caretaker only stores and returns mementos, it never reads or changes what's inside them.

• What if you needed several restore points, not just one? Because each memento is just an object, they can be stacked, listed, or discarded, giving you as many restore points as you want to keep.

In simple terms, you capture an object's state in a snapshot you can restore later, without exposing how that state is put together internally.

Wikipedia describes it like this:

"The memento pattern is a software design pattern that provides the ability to restore an object to its previous state (undo via rollback)."

(Source)

Programming Example:

TextEditor is the originator: it creates EditorMemento snapshots of itself and can restore from one. History is the caretaker: it stores mementos on a stack without ever looking inside them.

// The memento, an immutable snapshot of the editor's state
public class EditorMemento
{
    public string Content { get; }

    public EditorMemento(string content) => Content = content;
}

// The originator, creates and restores from mementos of its own state
public class TextEditor
{
    public string Content { get; private set; } = string.Empty;

    public void Write(string text) => Content += text;

    public EditorMemento Save() => new(Content);

    public void Restore(EditorMemento memento) => Content = memento.Content;
}

// The caretaker, stores mementos without ever looking inside them
public class History
{
    private readonly Stack<EditorMemento> _snapshots = new();

    public void Save(EditorMemento memento) => _snapshots.Push(memento);

    public EditorMemento Undo() => _snapshots.Pop();
}

Now let's see it in action:

var editor  = new TextEditor();
var history = new History();

editor.Write("Hello");
history.Save(editor.Save());

editor.Write(", world");
history.Save(editor.Save());

editor.Write("!!!");
Console.WriteLine($"Current: {editor.Content}");

editor.Restore(history.Undo());
Console.WriteLine($"After undo: {editor.Content}");

editor.Restore(history.Undo());
Console.WriteLine($"After undo: {editor.Content}");

Output:

Current: Hello, world!!!
After undo: Hello, world
After undo: Hello

History never read or changed the text inside a snapshot. It just pushed mementos on and popped them off. Only TextEditor knew what to do with the content inside one. That's the Memento pattern.

When to Use it

Use Memento when you need undo/redo functionality and want to capture state without exposing an object's internals.

It's also a good choice when taking a snapshot directly would break encapsulation by exposing private fields.

And it's helpful when you want the object that stores history to stay dumb: like holding snapshots without knowing or caring what's inside them.

7. The Observer Design Pattern

Real World Example

Think of subscribing to a YouTube channel. You don't sit there refreshing the page, checking if a new video has been uploaded. You subscribe once, and the moment the channel uploads something, you get notified automatically.

The channel doesn't know or care what each subscriber does with that notification. It just knows it has a list of subscribers, and when something changes, it tells all of them.

That's the Observer pattern. One object holds a list of dependents, and whenever its state changes, it notifies every one of them automatically.

Problems it solves:

• What if every subscriber had to keep checking the channel for updates? That would waste effort and add delay. The channel notifying its subscribers directly means they find out the moment it happens.

• What if the channel had to know exactly what each subscriber wanted to do with a new video? It shouldn't need to. The channel only calls Notify(), each subscriber decides for itself what that means.

• What if you wanted to add or remove subscribers at runtime? The channel doesn't need to change. It just keeps a list, and subscribing or unsubscribing only ever affects that list.

In simple terms, one object keeps a list of dependents and automatically notifies all of them whenever its own state changes.

Wikipedia describes it like this:

"The observer pattern is a software design pattern in which an object, named the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes, usually by calling one of their methods." (Source)

Programming Example:

YouTubeChannel is the subject: it keeps a list of ISubscribers and notifies all of them whenever a video is uploaded. Subscriber is the concrete observer, deciding for itself what to do with that notification.

// The observer interface, every subscriber implements this
public interface ISubscriber
{
    void Notify(string channelName, string videoTitle);
}

// The concrete observer
public class Subscriber : ISubscriber
{
    private readonly string _name;

    public Subscriber(string name) => _name = name;

    public void Notify(string channelName, string videoTitle)
    {
        Console.WriteLine($"{_name}: {channelName} just uploaded '{videoTitle}'!");
    }
}

// The subject, keeps track of its subscribers and notifies them of changes
public class YouTubeChannel
{
    private readonly string _name;
    private readonly List<ISubscriber> _subscribers = new();

    public YouTubeChannel(string name) => _name = name;

    public void Subscribe(ISubscriber subscriber)   => _subscribers.Add(subscriber);
    public void Unsubscribe(ISubscriber subscriber) => _subscribers.Remove(subscriber);

    public void UploadVideo(string title)
    {
        Console.WriteLine($"{_name}: Uploaded '{title}'.");

        foreach (var subscriber in _subscribers)
        {
            subscriber.Notify(_name, title);
        }
    }
}

Now let's see it in action:

var channel = new YouTubeChannel("Code With Isaiah");

var alice = new Subscriber("Alice");
var bob   = new Subscriber("Bob");

channel.Subscribe(alice);
channel.Subscribe(bob);

channel.UploadVideo("Design Patterns Explained");

channel.Unsubscribe(bob);
channel.UploadVideo("Understanding the Observer Pattern");

Output:

Code With Isaiah: Uploaded 'Design Patterns Explained'.
Alice: Code With Isaiah just uploaded 'Design Patterns Explained'!
Bob: Code With Isaiah just uploaded 'Design Patterns Explained'!
Code With Isaiah: Uploaded 'Understanding the Observer Pattern'.
Alice: Code With Isaiah just uploaded 'Understanding the Observer Pattern'!

Once Bob unsubscribed, he stopped hearing about new uploads entirely. The channel never singled him out, it just no longer had him on the list it notifies. That's the Observer pattern.

When to Use it

Use Observer when a change to one object should automatically update an unknown number of others.

It's also useful when you want objects to stay loosely coupled: the subject only knows about an observer interface, never concrete details.

And it's a good option when the number of dependents can grow or shrink at runtime, such as subscribing and unsubscribing.

8. The State Design Pattern

Real World Example

Think of an online order moving through its lifecycle: pending, then shipped, then delivered. What "moving to the next step" actually means is different at every stage. From pending it means handing the package to a courier. From shipped it means marking it as received. From delivered, there's nowhere left to go. Rather than one giant method full of if checks for every possible stage, each stage can just know what comes after it.

That's the State pattern. The object's behaviour changes based on its current state, and each state knows how to transition to the next one.

Problems it solves:

• What if one method had to handle every stage with a long chain of conditionals? It would grow harder to follow every time a new stage was added. Giving each stage its own class keeps the logic for that stage self-contained.

• What if adding a new stage meant editing that same giant method? It's easy to introduce a bug in an unrelated stage while doing so. A new state is just a new class, dropped in alongside the others.

• What if the object needed to behave completely differently depending on where it was in its lifecycle? Delegating to the current state object means the context doesn't need to know the details. It just asks the current state what to do.

In simple terms, you let an object change its behaviour by changing which state object it's currently holding, so the object appears to change how it acts as its state changes.

Wikipedia describes it like this:

"The state pattern is a behavioral software design pattern that allows an object to alter its behavior when its internal state changes. This pattern is close to the concept of finite-state machines." (Source)

Programming Example:

Order is the context: it holds whatever IOrderState it's currently in and delegates to it. Each concrete state, PendingState, ShippedState, DeliveredState, knows what the next state should be.

// The state interface, every state implements this
public interface IOrderState
{
    void Next(Order order);
    string Name { get; }
}

// The context, delegates behaviour to whatever state it currently holds
public class Order
{
    public IOrderState State { get; set; } = new PendingState();

    public void Next()
    {
        Console.WriteLine($"Order is currently: {State.Name}");
        State.Next(this);
    }
}

// Concrete states, each knows what comes after it
public class PendingState : IOrderState
{
    public string Name => "Pending";

    public void Next(Order order) => order.State = new ShippedState();
}

public class ShippedState : IOrderState
{
    public string Name => "Shipped";

    public void Next(Order order) => order.State = new DeliveredState();
}

public class DeliveredState : IOrderState
{
    public string Name => "Delivered";

    public void Next(Order order)
    {
        Console.WriteLine("Order has already been delivered. Nothing left to do.");
    }
}

Now let's see it in action:

var order = new Order();

order.Next();
order.Next();
order.Next();
order.Next();

Output:

Order is currently: Pending
Order is currently: Shipped
Order is currently: Delivered
Order has already been delivered. Nothing left to do.

Order never checked "if pending, do this, if shipped, do that." It just asked its current state what to do next, and the state itself decided what came after. That's the State pattern.

When to Use it

Use State when an object's behaviour depends on its state, and it must change that behaviour at runtime as the state changes.

It's also helpful when you have large conditional blocks that branch on the object's current state or type.

And choose it when transitions between states should be explicit and self-contained, rather than scattered across one big method.

9. The Strategy Design Pattern

Real World Example

Think of checking out of an online store. You can pay by credit card, or you can pay through PayPal. The shopping cart doesn't care which one you pick. It just knows the total, hands it to whichever payment method you chose, and lets that method handle the details of actually charging you. Swap the payment method, and the cart's own code never changes.

That's the Strategy pattern. An algorithm (in this case "how to pay") is pulled out into its own interchangeable object, and the client just picks which one to use.

Problems it solves:

• What if the cart had a big if/else for every payment method? Adding a new one would mean editing that method every time. Pulling each payment method out into its own class means the cart never needs to change.

• What if you wanted to swap the algorithm at runtime? A hardcoded method can't be swapped. A strategy object can simply be replaced with another one that implements the same interface.

• What if two different payment methods needed to share a common interface but nothing else? Each one implements the strategy interface, but its internal details (a card number here, an email there) stay private to it.

In simple terms, you pull an algorithm out into its own interchangeable object, so the class using it doesn't need to know or care which specific version is running.

Wikipedia describes it like this:

"The strategy pattern is a behavioral software design pattern that enables selecting an algorithm at runtime." (Source)

Programming Example:

ShoppingCart is the context: it holds an IPaymentStrategy and delegates the actual payment to it. CreditCardPayment and PayPalPayment are concrete strategies, each a different way to pay.

// The strategy interface, every payment method implements this
public interface IPaymentStrategy
{
    void Pay(decimal amount);
}

// Concrete strategies, each a different way to pay
public class CreditCardPayment : IPaymentStrategy
{
    private readonly string _cardNumber;

    public CreditCardPayment(string cardNumber) => _cardNumber = cardNumber;

    public void Pay(decimal amount)
    {
        Console.WriteLine($"Charged ${amount} to credit card ending in {_cardNumber[^4..]}.");
    }
}

public class PayPalPayment : IPaymentStrategy
{
    private readonly string _email;

    public PayPalPayment(string email) => _email = email;

    public void Pay(decimal amount)
    {
        Console.WriteLine($"Charged ${amount} via PayPal account {_email}.");
    }
}

// The context, holds a strategy and delegates the actual payment work to it
public class ShoppingCart
{
    private readonly decimal _total;
    private IPaymentStrategy? _paymentMethod;

    public ShoppingCart(decimal total) => _total = total;

    public void SetPaymentMethod(IPaymentStrategy method) => _paymentMethod = method;

    public void Checkout()
    {
        if (_paymentMethod is null)
        {
            Console.WriteLine("No payment method selected.");
            return;
        }

        _paymentMethod.Pay(_total);
    }
}

Now let's see it in action:

var cart = new ShoppingCart(59.99m);

cart.SetPaymentMethod(new CreditCardPayment("4111 1111 1111 1111"));
cart.Checkout();

cart.SetPaymentMethod(new PayPalPayment("isaiah@example.com"));
cart.Checkout();

Output:

Charged $59.99 to credit card ending in 1111.
Charged $59.99 via PayPal account isaiah@example.com.

ShoppingCart never knew how a payment actually got processed. It just called Pay() on whatever strategy it was holding at the time. That's the Strategy pattern: the algorithm is swapped out, the class using it stays exactly the same.

When to Use it

Use Strategy when you have several variants of an algorithm, and want to switch between them at runtime.

It's also helpful when you want to avoid a class full of conditionals that pick behaviour based on a type or flag.

And it's a solid choice when related classes only differ in the behaviour they use, and that behaviour should be interchangeable.

10. The Template Method Design Pattern

Real World Example

Think of making a hot drink, tea or coffee. Both follow the exact same basic steps: boil water, brew, pour into a cup, and add something to taste. What differs is only two of those steps: tea gets steeped, and coffee gets brewed through grounds. Tea gets lemon, and coffee gets sugar and milk. The overall recipe never changes, only the specific details of a couple of steps within it.

That's the Template Method pattern. A base class defines the fixed skeleton of an algorithm, and subclasses only fill in the steps that are actually allowed to vary.

Problems it solves:

• What if every beverage repeated the entire recipe from scratch? Boiling water and pouring into a cup would be duplicated in every single class. The template method keeps those steps in one place, written once.

• What if a subclass could reorder the steps, or skip one entirely? That would let each beverage break the overall recipe. Because the algorithm's skeleton lives in the base class as a single method, the order and structure stay fixed.

• What if you wanted to add a new beverage? Only the steps that differ, brewing and condiments, need to be written. Everything else is already handled by the base class.

In simple terms, you define the fixed skeleton of an algorithm in a base class, and let subclasses fill in only the steps that are actually allowed to differ.

Wikipedia describes it like this:

"In object-oriented programming, the template method is one of the behavioral design patterns identified by Gamma et al. in the book Design Patterns. The template method is a method in a superclass, usually an abstract superclass, and defines the skeleton of an operation in terms of a number of high-level steps." (Source)

Programming Example:

Beverage defines Prepare() as the template method: the fixed sequence of steps. Tea and Coffee only override Brew() and AddCondiments(), the two steps that are actually allowed to vary.

// The abstract class, defines the skeleton of the algorithm
public abstract class Beverage
{
    // The template method, the steps and their order never change
    public void Prepare()
    {
        BoilWater();
        Brew();
        PourInCup();
        AddCondiments();
    }

    private void BoilWater() => Console.WriteLine("Boiling water.");
    private void PourInCup() => Console.WriteLine("Pouring into cup.");

    // Steps left for subclasses to fill in
    protected abstract void Brew();
    protected abstract void AddCondiments();
}

// A concrete class, fills in the steps specific to tea
public class Tea : Beverage
{
    protected override void Brew() => Console.WriteLine("Steeping the tea bag.");
    protected override void AddCondiments() => Console.WriteLine("Adding lemon.");
}

// Another concrete class, fills in the steps specific to coffee
public class Coffee : Beverage
{
    protected override void Brew() => Console.WriteLine("Brewing the coffee grounds.");
    protected override void AddCondiments() => Console.WriteLine("Adding sugar and milk.");
}

Now let's see it in action:

Beverage tea    = new Tea();
Beverage coffee = new Coffee();

tea.Prepare();
Console.WriteLine();
coffee.Prepare();

Output:

Boiling water.
Steeping the tea bag.
Pouring into cup.
Adding lemon.

Boiling water.
Brewing the coffee grounds.
Pouring into cup.
Adding sugar and milk.

Both drinks boiled water and poured into a cup in exactly the same way, because Prepare() in the base class handled that. Only brewing and condiments changed, because those were the steps each subclass was actually responsible for. That's the Template Method pattern.

When to Use it

Use Template Method when several classes share the same overall algorithm, but differ in a few specific steps.

It's a good choice when you want to enforce a fixed sequence of steps, while still letting subclasses customise parts of it.

And it's helpful when you want to avoid duplicating the parts of an algorithm that never change across every subclass.

11. The Visitor Design Pattern

Real World Example

Think of a shopping cart with different kinds of items: books and electronics, each taxed differently at checkout. You don't want to bake pricing logic into the Book and Electronic classes themselves, especially if you'll need other operations on them later too, like generating a shipping label or a warranty summary. Instead, each item just accepts a visitor and hands itself over. The visitor is the one that actually knows how to price a book differently from an electronic.

That's the Visitor pattern. The operation lives outside the objects it acts on, and each object just lets the visitor know what it needs to know: what type of thing it actually is.

Problems it solves:

• What if pricing logic was written directly inside Book and Electronic? Every new operation (tax, shipping, warranty) would mean editing both classes again and again. The visitor keeps each new operation in its own self-contained class instead.

• What if you needed to add a new operation without touching the existing item classes? Normally that means modifying every class the operation applies to. A new visitor is a new class, while Book and Electronic never change.

• What if a generic loop had to guess the concrete type of each item? That usually means a chain of type checks. Accept() calling Visit(this) lets the compiler pick the right overload automatically, without a single if or type check.

In simple terms, you move an operation out of the objects it acts on and into its own class. Each object just accepts a visitor and lets it know what concrete type it is.

Wikipedia describes it like this:

"The visitor design pattern is a way of separating an algorithm from an object structure on which it operates." (Source)

Programming Example:

Book and Electronic both implement IItem and simply call visitor.Visit(this). PricingVisitor implements IVisitor with an overload for each concrete type, so the right pricing logic runs automatically.

// The element interface, every item in the cart implements this
public interface IItem
{
    void Accept(IVisitor visitor);
}

// Concrete elements, each accepts a visitor and hands itself over
public class Book : IItem
{
    public string Title { get; }
    public decimal Price { get; }

    public Book(string title, decimal price)
    {
        Title = title;
        Price = price;
    }

    public void Accept(IVisitor visitor) => visitor.Visit(this);
}

public class Electronic : IItem
{
    public string Name { get; }
    public decimal Price { get; }

    public Electronic(string name, decimal price)
    {
        Name  = name;
        Price = price;
    }

    public void Accept(IVisitor visitor) => visitor.Visit(this);
}

// The visitor interface, one Visit overload per concrete element
public interface IVisitor
{
    void Visit(Book book);
    void Visit(Electronic electronic);
}

// A concrete visitor, adds a new operation without touching Book or Electronic
public class PricingVisitor : IVisitor
{
    public decimal Total { get; private set; }

    public void Visit(Book book)
    {
        Console.WriteLine($"Book: {book.Title} — ${book.Price:F2} (no tax).");
        Total += book.Price;
    }

    public void Visit(Electronic electronic)
    {
        var priceWithTax = electronic.Price * 1.15m;
        Console.WriteLine($"Electronic: {electronic.Name} — ${priceWithTax:F2} (with 15% tax).");
        Total += priceWithTax;
    }
}

Now let's see it in action:

var cart = new List<IItem>
{
    new Book("Design Patterns", 45.00m),
    new Electronic("Headphones", 120.00m)
};

var pricingVisitor = new PricingVisitor();

foreach (var item in cart)
{
    item.Accept(pricingVisitor);
}

Console.WriteLine($"Total: ${pricingVisitor.Total:F2}");

Output:

Book: Design Patterns — $45.00 (no tax).
Electronic: Headphones — $138.00 (with 15% tax).
Total: $183.00

Neither Book nor Electronic contained a single line of pricing logic. Each one only knew how to Accept() a visitor. PricingVisitor was the one that actually decided how each type gets priced. That's the Visitor pattern: the operation lives outside the object structure, not inside it.

When to Use it

Use Visitor when you need to perform operations across a group of unrelated classes, without polluting each class with that logic.

It's also helpful when you want to add new operations often, but the object structure itself rarely changes.

And it's a good choice when you'd otherwise need type checks or casting to figure out what to do with each object in a collection.

Conclusion

That covers all 23 classic design patterns across the three families: Creational, Structural, and Behavioral.

None of them are rules you must follow. They're answers to problems that show up again and again in software: how to create objects without hard-coding their exact type, how to compose bigger structures out of smaller ones, and how to let objects communicate without being tightly bound to each other.

A few things worth remembering:

• You won't use most of these patterns most of the time. Recognising when a problem calls for one is the actual skill. Forcing a pattern onto a problem that doesn't need it usually makes the code harder to follow, not easier.

• The real world analogies exist to build intuition, not to be taken literally. Once a pattern's shape clicks in a story you understand, spotting it in real code becomes far easier.

• Patterns compose. A Factory Method might produce objects that are themselves Decorators. A Composite tree might be built with a Builder. Real systems mix and layer patterns rather than using them in isolation.

• The language doesn't matter. Every example here is in C#, but the same shapes exist in Python, Java, TypeScript, Go, Rust, and beyond. If you understand the problem a pattern solves, translating it to any language is straightforward.

The goal isn't to memorise 23 names. It's to recognise the recurring problems underneath them, so that when one shows up in your own code, you already know a proven shape for solving it.

"Each pattern describes a problem which occurs over and over again in our environment, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice."

Source: Christopher Alexander, A Pattern Language — the architectural work that originally inspired software design patterns.

If this handbook was useful, the source lives at github.com/Clifftech123/design-patterns-handbook. Star it, fork it, or open a PR with a pattern you think is missing.

Other objects aren't simple at all, like a carousel widget that needs an item count, an item builder function, a controller, a height, a viewport fraction, autoplay settings, page change callbacks, and infinite scroll configuration. Or like an HTTP request that needs a URL, headers, authentication tokens, a body, a timeout, and retry logic. Or a notification that needs a title, body, icon, channel, priority, sound, vibration, and action buttons.

When you need to construct objects like these, the naïve approach is a constructor with many parameters. It works, but it creates problems that compound as the object grows more complex. Parameters become hard to tell apart. Optional parameters require null checks everywhere. The order of arguments matters and is easy to get wrong. The constructor call becomes a wall of values that nobody wants to read or maintain.

The Builder Design Pattern solves this. It separates the construction of a complex object from its representation, allowing the same construction process to create different configurations through a readable, step-by-step interface.

Table of Contents

• Prerequisites

• What is the Builder Pattern?

• The Problem It Solves

• Core Components

• Method Chaining: The Fluent Interface

• Real World Example One: Flutter Carousel Builder

• Real World Example Two: HTTP Request Builder

• The Builder Pattern in C#

• Builder vs Constructor vs Factory

• When to Use the Builder Pattern

• When Not to Use It

• Conclusion

Prerequisites

Before reading this article, you should be comfortable with:

• Object-oriented programming: classes, constructors, and methods

• What a design pattern is at a conceptual level

• Basic Dart or C# syntax

You don't need prior experience with design patterns. This article introduces the Builder pattern from first principles.

What is the Builder Pattern?

The Builder Pattern is a creational design pattern. Creational patterns deal with how objects are created. The Builder pattern specifically deals with the construction of complex objects that require many configuration steps.

The pattern separates two concerns that are often tangled together in simpler code: what an object is, and how it's built. The object holds its own data and behavior. The Builder holds the construction logic and accumulates the configuration step by step before producing the final object.

The result is a construction process that reads like a description of what you're building rather than a list of values to pass to a constructor.

The Problem It Solves

Here's what constructing a complex widget looks like without the Builder pattern:

// constructing a carousel directly — hard to read, easy to get wrong
CarouselSlider.builder(
  options: CarouselOptions(
    height: 200,
    viewportFraction: 0.97,
    enableInfiniteScroll: false,
    autoPlayCurve: Curves.easeIn,
    enlargeCenterPage: true,
    pauseAutoPlayOnManualNavigate: true,
    onPageChanged: onPageChanged,
    autoPlay: false,
  ),
  itemBuilder: (context, index, realIndex) => AdCard(ad: ads[index]),
  itemCount: ads.length,
)

This works. But look at what happens when you need to create two different carousels in the same screen: one for ads and one for account balances. Both need different heights, viewport fractions, item builders, and item counts. You copy the entire construction block, modify the values, and now you have two walls of configuration that are visually similar but subtly different.

When a new requirement comes in to add autoplay to the ads carousel but not the balance carousel, you have to find the right block, modify it carefully, and hope you're modifying the right one.

The deeper problem is that the construction logic is scattered across the codebase. Every place a carousel is created knows all the details of carousel construction. There's no single place where that knowledge lives.

The Builder pattern collects construction knowledge into one place and exposes it through a clean interface.

Core Components

The Builder pattern has three components.

The Product

The complex object being built. It doesn't know about the Builder. It holds its configuration and has behavior based on that configuration. The Product is often constructed with a private constructor so it can only be created by its Builder.

The Builder

The class responsible for accumulating configuration and producing the Product. Each method on the Builder configures one aspect of the Product and returns the Builder itself. This return is what enables method chaining. The final method on the Builder produces the completed Product.

The Director (optional)

A class that knows how to use a Builder to produce specific pre-configured Products. The Director encodes the knowledge of how to build common configurations so callers don't need to know the details. In practice, a Factory method often serves this role.

Method Chaining: The Fluent Interface

Method chaining is the technique that makes Builder code read naturally. Each Builder method returns this (the Builder itself) so the next method call can follow immediately on the same line or the next line.

// without method chaining
final builder = RequestBuilder();
builder.setUrl('https://api.example.com/users');
builder.setMethod('POST');
builder.addHeader('Authorization', 'Bearer $token');
builder.setBody({'name': 'John'});
final request = builder.build();

// with method chaining
final request = RequestBuilder()
    .setUrl('https://api.example.com/users')
    .setMethod('POST')
    .addHeader('Authorization', 'Bearer $token')
    .setBody({'name': 'John'})
    .build();

Both produce exactly the same result. The chained version reads like a sentence describing the request. The unchained version is a sequence of imperative statements.

Method chaining is sometimes called a Fluent Interface. The name comes from how the code reads: fluently, like natural language, from left to right or top to bottom.

Real World Example One: Flutter Carousel Builder

This is a real production implementation from a Flutter fintech application. The app needs to show two different carousels on the dashboard: one for promotional ads and one for account balances. Each carousel has a different configuration but shares the same underlying construction mechanism.

The Configuration Objects

import 'package:flutter/widgets.dart';
import 'package:equatable/equatable.dart';
import 'package:carousel_slider/carousel_slider.dart';

class CarouselArgs extends Equatable {
  final CarouselSliderController? carouselController;
  final int itemCount;
  final Widget Function(BuildContext, int, int) itemBuilder;
  final CarouselOptions options;

  const CarouselArgs({
    this.carouselController,
    required this.itemCount,
    required this.itemBuilder,
    required this.options,
  });

  @override
  List<Object?> get props => [
        carouselController,
        itemCount,
        itemBuilder,
        options,
      ];
}

class CarouselOptions extends Equatable {
  final double? height;
  final double? viewPortFraction;
  final bool? enableInfiniteScroll;
  final bool? enlargeCenterPage;
  final bool? pauseAutoPlayOnManualNavigate;
  final bool? autoplay;
  final Curve? autoplayCurve;
  final void Function(int, CarouselPageChangedReason)? onPageChanged;

  const CarouselOptions({
    this.height,
    this.viewPortFraction,
    this.enableInfiniteScroll,
    this.enlargeCenterPage,
    this.pauseAutoPlayOnManualNavigate,
    this.autoplay,
    this.autoplayCurve,
    this.onPageChanged,
  });

  @override
  List<Object?> get props => [
        height,
        viewPortFraction,
        enableInfiniteScroll,
        enlargeCenterPage,
        pauseAutoPlayOnManualNavigate,
        autoplay,
        autoplayCurve,
        onPageChanged,
      ];
}

CarouselArgs and CarouselOptions are the configuration objects. They hold all the data needed to construct a carousel. They're simple data containers with no construction logic of their own.

The Product

import 'package:flutter/material.dart';
import 'package:carousel_slider/carousel_slider.dart' as n;

class CustomCarousel extends StatelessWidget {
  final CarouselArgs dto;

  // private constructor only the Builder can create this widget
  CustomCarousel._builder(CustomCarouselBuilder builder)
      : dto = builder._dto!;

  @override
  Widget build(BuildContext context) {
    return n.CarouselSlider.builder(
      options: n.CarouselOptions(
        height: dto.options.height,
        viewportFraction: dto.options.viewPortFraction!,
        enableInfiniteScroll: dto.options.enableInfiniteScroll!,
        enlargeCenterPage: dto.options.enlargeCenterPage,
        onPageChanged: dto.options.onPageChanged,
        autoPlayCurve: dto.options.autoplayCurve!,
        autoPlay: dto.options.autoplay!,
      ),
      itemBuilder: dto.itemBuilder,
      itemCount: dto.itemCount,
    );
  }
}

CustomCarousel is the Product. Its constructor is private: CustomCarousel._builder. The underscore prefix and the named constructor ensure that nobody outside this class can instantiate a CustomCarousel directly. The only way to create one is through the Builder.

This is intentional. It enforces that all carousel construction goes through the Builder, where the configuration is validated and assembled consistently.

The Builder

class CustomCarouselBuilder {
  BuildContext? _context;
  CarouselArgs? _dto;

  CustomCarouselBuilder setArgs(BuildContext context, CarouselArgs value) {
    _context = context;
    _dto = value;
    return this;
  }

  Widget get buildCarousel =>
      CustomCarousel._builder(this).build(_context!);
}

CustomCarouselBuilder is the Builder. It accumulates the BuildContext and the CarouselArgs through setArgs. The setArgs method returns this, enabling the call to be chained.

buildCarousel is the terminal step. It calls the private constructor of CustomCarousel, passing itself as the argument, and then calls build to produce the final widget. The carousel can't be built until both the context and the args have been provided.

The Director: A Factory That Uses the Builder

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:carousel_slider/carousel_slider.dart' as n;

class CarouselWidgetFactory {
  static CustomCarouselBuilder showCarouselAds(
    BuildContext context, {
    void Function(int, n.CarouselPageChangedReason)? onPageChanged,
  }) =>
      CustomCarouselBuilder().setArgs(
        context,
        CarouselArgs(
          itemCount: context.read<DashboardLogic>().dashboardAds.length,
          itemBuilder: (context, index, realIndex) => DashboardAdsList(
            dto: context.read<DashboardLogic>().dashboardAds[index],
          ),
          options: CarouselOptions(
            height: 200,
            viewPortFraction: 0.97,
            enableInfiniteScroll: false,
            autoplayCurve: Curves.easeIn,
            enlargeCenterPage: true,
            pauseAutoPlayOnManualNavigate: true,
            onPageChanged: onPageChanged,
            autoplay: false,
          ),
        ),
      );

  static CustomCarouselBuilder showCarouselAccountBalance(
    BuildContext context, {
    void Function(int, n.CarouselPageChangedReason)? onPageChanged,
  }) =>
      CustomCarouselBuilder().setArgs(
        context,
        CarouselArgs(
          itemCount: context.read<DashboardLogic>().allBalances.length,
          itemBuilder: (context, index, realIndex) => BalanceList(
            dto: context.read<DashboardLogic>().allBalances[index],
          ),
          options: CarouselOptions(
            height: 230,
            viewPortFraction: 1,
            enableInfiniteScroll: false,
            autoplayCurve: Curves.decelerate,
            enlargeCenterPage: true,
            pauseAutoPlayOnManualNavigate: true,
            onPageChanged: onPageChanged,
            autoplay: false,
          ),
        ),
      );
}

CarouselWidgetFactory is the Director. It knows exactly how to configure the Builder for each specific carousel type. The knowledge of what a dashboard ads carousel looks like (height 200, viewport 0.97, easeIn curve) lives in one place. The knowledge of what an account balance carousel looks like (height 230, viewport 1, decelerate curve) lives in one place.

A developer who needs to add a new carousel type adds one static method to CarouselWidgetFactory. They don't need to understand the internals of CustomCarouselBuilder or CustomCarousel. They describe what they want using the Factory.

Using It

class DashboardPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // the factory creates the right builder configuration
        // buildCarousel produces the final widget
        CarouselWidgetFactory.showCarouselAds(context).buildCarousel,
        const SizedBox(height: 16),
        CarouselWidgetFactory.showCarouselAccountBalance(context).buildCarousel,
      ],
    );
  }
}

Two carousels, two lines. The calling code has zero knowledge of carousel configuration. It doesn't know about viewport fractions, autoplay curves, or item builders. It calls the Factory, which uses the Builder, which produces the Product. Each layer knows only what it needs to know.

Real World Example Two: HTTP Request Builder

The carousel example shows Builder for widget construction. This second example shows it for non-UI object construction: building HTTP requests. This is a common pattern in data layers and API clients.

The Product

class ApiRequest {
  final String url;
  final String method;
  final Map<String, String> headers;
  final Map<String, dynamic>? body;
  final Duration timeout;
  final int maxRetries;

  // private constructor — only the Builder can create ApiRequest
  ApiRequest._({
    required this.url,
    required this.method,
    required this.headers,
    this.body,
    required this.timeout,
    required this.maxRetries,
  });
}

ApiRequest holds everything needed to make an HTTP request. Its private constructor ensures it's always created through the Builder, where defaults are applied and validation happens.

The Builder

class ApiRequestBuilder {
  String? _url;
  String _method = 'GET';
  final Map<String, String> _headers = {};
  Map<String, dynamic>? _body;
  Duration _timeout = const Duration(seconds: 30);
  int _maxRetries = 0;

  ApiRequestBuilder url(String url) {
    _url = url;
    return this;
  }

  ApiRequestBuilder method(String method) {
    _method = method;
    return this;
  }

  ApiRequestBuilder header(String key, String value) {
    _headers[key] = value;
    return this;
  }

  ApiRequestBuilder bearerToken(String token) {
    _headers['Authorization'] = 'Bearer $token';
    return this;
  }

  ApiRequestBuilder contentType(String type) {
    _headers['Content-Type'] = type;
    return this;
  }

  ApiRequestBuilder body(Map<String, dynamic> body) {
    _body = body;
    return this;
  }

  ApiRequestBuilder timeout(Duration timeout) {
    _timeout = timeout;
    return this;
  }

  ApiRequestBuilder withRetries(int maxRetries) {
    _maxRetries = maxRetries;
    return this;
  }

  ApiRequest build() {
    if (_url == null || _url!.isEmpty) {
      throw ArgumentError('URL is required to build an ApiRequest');
    }

    return ApiRequest._(
      url: _url!,
      method: _method,
      headers: Map.unmodifiable(_headers),
      body: _body,
      timeout: _timeout,
      maxRetries: _maxRetries,
    );
  }
}

Each method on ApiRequestBuilder sets one configuration value and returns this. The build() method is the terminal step. It validates that required fields are present and constructs the immutable ApiRequest.

Notice that _method, _timeout, and _maxRetries all have sensible defaults. A caller doesn't need to specify these unless they want to override the defaults. This is one of the key advantages of the Builder over a constructor: optional configuration is genuinely optional, with no null checks or default parameter workarounds.

Using It

// a standard authenticated POST request
final createUserRequest = ApiRequestBuilder()
    .url('https://api.example.com/users')
    .method('POST')
    .bearerToken(authToken)
    .contentType('application/json')
    .body({'name': 'Oluwaseyi', 'email': 'seyi@example.com'})
    .timeout(const Duration(seconds: 15))
    .build();

// a GET request with retry logic
final getUserRequest = ApiRequestBuilder()
    .url('https://api.example.com/users/$userId')
    .bearerToken(authToken)
    .withRetries(3)
    .build();

// a request with custom headers for a third-party service
final webhookRequest = ApiRequestBuilder()
    .url('https://webhook.example.com/events')
    .method('POST')
    .header('X-API-Key', apiKey)
    .header('X-Webhook-Secret', webhookSecret)
    .contentType('application/json')
    .body(eventPayload)
    .timeout(const Duration(seconds: 5))
    .build();

Each request reads like a description of itself. The URL, the method, the authentication, the body, and the timeout. You can read any of these and understand immediately what kind of request it is and what it contains.

Compare this to calling a constructor directly:

// without Builder — hard to read, parameter order matters
final request = ApiRequest._(
  url: 'https://api.example.com/users',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $authToken',
    'Content-Type': 'application/json',
  },
  body: {'name': 'Oluwaseyi', 'email': 'seyi@example.com'},
  timeout: const Duration(seconds: 15),
  maxRetries: 0,
);

The constructor version requires you to know every field and its order. The Builder version lets you specify only what you need and reads like documentation.

The Builder Pattern in C#

The same pattern in C# demonstrates that this is a universal design principle, not a Dart-specific technique. C# is particularly expressive for Builder implementations because of its method chaining conventions.

HTTP Request Builder in C#

public class ApiRequest
{
    public string Url { get; }
    public string Method { get; }
    public Dictionary<string, string> Headers { get; }
    public object? Body { get; }
    public TimeSpan Timeout { get; }
    public int MaxRetries { get; }

    // private constructor
    private ApiRequest(
        string url,
        string method,
        Dictionary<string, string> headers,
        object? body,
        TimeSpan timeout,
        int maxRetries)
    {
        Url = url;
        Method = method;
        Headers = headers;
        Body = body;
        Timeout = timeout;
        MaxRetries = maxRetries;
    }

    public static ApiRequestBuilder Create() => new ApiRequestBuilder();
}

public class ApiRequestBuilder
{
    private string? _url;
    private string _method = "GET";
    private readonly Dictionary<string, string> _headers = new();
    private object? _body;
    private TimeSpan _timeout = TimeSpan.FromSeconds(30);
    private int _maxRetries = 0;

    public ApiRequestBuilder Url(string url)
    {
        _url = url;
        return this;
    }

    public ApiRequestBuilder Method(string method)
    {
        _method = method;
        return this;
    }

    public ApiRequestBuilder Header(string key, string value)
    {
        _headers[key] = value;
        return this;
    }

    public ApiRequestBuilder BearerToken(string token)
    {
        _headers["Authorization"] = $"Bearer {token}";
        return this;
    }

    public ApiRequestBuilder ContentType(string contentType)
    {
        _headers["Content-Type"] = contentType;
        return this;
    }

    public ApiRequestBuilder Body(object body)
    {
        _body = body;
        return this;
    }

    public ApiRequestBuilder Timeout(TimeSpan timeout)
    {
        _timeout = timeout;
        return this;
    }

    public ApiRequestBuilder WithRetries(int maxRetries)
    {
        _maxRetries = maxRetries;
        return this;
    }

    public ApiRequest Build()
    {
        if (string.IsNullOrEmpty(_url))
            throw new ArgumentException("URL is required");

        return new ApiRequest(
            _url!,
            _method,
            new Dictionary<string, string>(_headers),
            _body,
            _timeout,
            _maxRetries
        );
    }
}

Using It in C#

// authenticated POST request
var createUserRequest = ApiRequest.Create()
    .Url("https://api.example.com/users")
    .Method("POST")
    .BearerToken(authToken)
    .ContentType("application/json")
    .Body(new { name = "Oluwaseyi", email = "seyi@example.com" })
    .Timeout(TimeSpan.FromSeconds(15))
    .Build();

// GET with retry logic
var getUserRequest = ApiRequest.Create()
    .Url($"https://api.example.com/users/{userId}")
    .BearerToken(authToken)
    .WithRetries(3)
    .Build();

The pattern is identical. The method names are capitalized following C# conventions. The Build() method is the terminal step. The private constructor is enforced. The result reads exactly like its Dart equivalent.

A UI Builder in C# (ASP.NET)

The Builder pattern also appears naturally in .NET for constructing complex objects in backend systems. Here's a notification builder:

public class Notification
{
    public string Title { get; }
    public string Body { get; }
    public string? ImageUrl { get; }
    public NotificationPriority Priority { get; }
    public Dictionary<string, string> Data { get; }
    public bool Silent { get; }

    private Notification(
        string title,
        string body,
        string? imageUrl,
        NotificationPriority priority,
        Dictionary<string, string> data,
        bool silent)
    {
        Title = title;
        Body = body;
        ImageUrl = imageUrl;
        Priority = priority;
        Data = data;
        Silent = silent;
    }

    public static NotificationBuilder Builder(string title, string body)
        => new NotificationBuilder(title, body);
}

public class NotificationBuilder
{
    private readonly string _title;
    private readonly string _body;
    private string? _imageUrl;
    private NotificationPriority _priority = NotificationPriority.Default;
    private readonly Dictionary<string, string> _data = new();
    private bool _silent = false;

    internal NotificationBuilder(string title, string body)
    {
        _title = title;
        _body = body;
    }

    public NotificationBuilder WithImage(string imageUrl)
    {
        _imageUrl = imageUrl;
        return this;
    }

    public NotificationBuilder WithPriority(NotificationPriority priority)
    {
        _priority = priority;
        return this;
    }

    public NotificationBuilder WithData(string key, string value)
    {
        _data[key] = value;
        return this;
    }

    public NotificationBuilder AsSilent()
    {
        _silent = true;
        return this;
    }

    public Notification Build() => new Notification(
        _title,
        _body,
        _imageUrl,
        _priority,
        new Dictionary<string, string>(_data),
        _silent
    );
}

// usage
var notification = Notification
    .Builder("New Transaction", "You received NGN 50,000")
    .WithPriority(NotificationPriority.High)
    .WithData("transaction_id", "txn_001")
    .WithData("type", "credit")
    .Build();

var silentNotification = Notification
    .Builder("Background Sync", "")
    .AsSilent()
    .WithData("sync_type", "full")
    .Build();

Builder vs Constructor vs Factory

Understanding when to reach for a Builder versus a constructor or a Factory method requires understanding what problem each one solves.

A constructor is the right choice when the object is simple enough that all its parameters can be understood at a glance and there are few optional configurations. A User with an id, name, and email doesn't need a Builder.

A Factory method is the right choice when you need to control which type of object is created, or when creation requires logic that determines which concrete type to instantiate. A Repository.create() that returns either a SqlRepository or a HiveRepository based on the environment is a Factory.

A Builder is the right choice when the object has many optional or complex configuration parameters, when the construction requires multiple steps, when you want to prevent the creation of invalid objects by deferring construction until all required parameters are present, or when you want construction code to read clearly and be self-documenting.

The carousel example uses both Builder and Factory together deliberately. The Factory provides named, pre-configured entry points (showCarouselAds, showCarouselAccountBalance). The Builder handles the step-by-step construction of the complex configuration. Each pattern does its job.

When to Use the Builder Pattern

There are various solid use cases for the Builder pattern.

Use it when the object being constructed has many parameters, especially many optional ones. Named constructors with ten optional parameters are hard to read and easy to misconfigure.

It's also a good choice when the construction requires multiple steps that should be validated before the object is created. A Builder can enforce that required fields are present before calling build().

Choose it when you want the construction code to be self-documenting. Method chaining with descriptive names reads like documentation. A reader can understand what is being built without knowing the internals.

It's helpful when you need different representations of the same object. The same Builder can be used to create a test request, a staging request, and a production request by changing which methods are called, without modifying the Request class itself.

And it works well when you want to prevent the creation of invalid objects. By making the Product's constructor private and putting validation in the Builder's build() method, you ensure that invalid objects simply can't be created.

When Not to Use It

Avoid the Builder pattern when the object is simple and its constructor is already clear. Adding a Builder to a class with two required parameters is over-engineering that adds complexity without adding value.

It's also not a great choice when immutability isn't a concern and the object can be configured after creation through property setters. Some objects benefit from simple post-construction configuration rather than Builder-pattern construction.

And it's best to avoid it when the construction steps have strict ordering that a linear Builder can't represent. If step B absolutely must know the result of step A before it can run, a different pattern may be more appropriate.

Conclusion

The Builder Design Pattern addresses a problem that every developer encounters as their objects grow more complex. Constructors with many parameters become walls of values that are hard to read, hard to maintain, and easy to misconfigure. Optional parameters require null checks and default value workarounds that obscure the intent of the code.

The Builder separates the construction of a complex object from the object itself. Configuration accumulates step by step through descriptive method calls. Construction happens in one terminal step that validates and produces the final object. The Product's private constructor ensures that bypassing the Builder isn't possible.

The carousel example from a real Flutter fintech application shows this in a UI context: a Builder that accumulates widget configuration, a Factory that provides pre-configured Builder calls for specific carousel types, and a Product that can only be constructed through its Builder. Adding a new carousel type means one new Factory method. Changing carousel configuration means changing the relevant Factory method. The calling code never touches carousel internals.

The HTTP Request Builder shows the same pattern in a data layer context: step by step configuration through method chaining, sensible defaults for optional values, validation before construction, and an immutable Product that can't be created in an invalid state.

Method chaining is what makes Builder code readable. Each method call returns the Builder, enabling the next call to follow immediately. The chain reads from left to right or top to bottom like a description of what's being built. This isn't just aesthetics. It's what makes Builder code self-documenting and maintainable over time.

Complex object construction is a problem every codebase will encounter. The Builder pattern is how experienced engineers solve it.

It starts small: a simple validation check, an if statement here, another there. Then requirements grow and more conditions get added. The function gets longer. Someone adds a comment that says "don't modify without reading the full thing first." The function becomes a rite of passage. New developers are warned about it during onboarding.

This is what happens when complex business rules pile up in one place without a deliberate structure to contain them.

The Chain of Responsibility pattern exists to prevent exactly this. Instead of one method that knows everything and does everything, you build a chain of focused handlers. Each handler knows one rule and checks whether the request passes its rule. If it does, the request moves forward to the next handler. If it doesn't, the chain stops right there.

No handler knows how long the chain is. No handler knows what comes before or after it. Each one just does its job and decides: stop here, or pass it forward.

Table of Contents

• What is the Chain of Responsibility Pattern?

• The Problem It Solves

• Core Components

• Real World Example One: Transaction Approval Flow

• Real World Example Two: User Onboarding Validation

• What Makes These Two Examples Interesting Together

• When to Use the Chain of Responsibility Pattern

• When Not to Use It

• Conclusion

What is the Chain of Responsibility Pattern?

The Chain of Responsibility is a behavioral design pattern that lets you pass a request along a chain of handlers. Each handler in the chain decides either to process the request and stop the chain, or to pass the request to the next handler.

The pattern gives you three things that matter in production systems.

First, it decouples the sender of a request from its receivers. The code that initiates a transaction validation doesn't know which handler will ultimately process it or stop it. It just starts the chain.

Second, it gives you a single responsibility per handler. Each handler owns exactly one business rule. When that rule changes, you modify one class. Nothing else changes.

Third, it makes the chain configurable. You can add, remove, or reorder handlers without touching existing handler code. A new compliance requirement becomes a new handler plugged into the chain, not a new branch inside an existing method.

The Problem It Solves

Here's what transaction validation looks like without the pattern:

void handleTransaction(Transaction transaction) {
  if (transaction.isFraud) {
    // block transaction
    return;
  }

  if (!transaction.isKycVerified) {
    // reject transaction
    return;
  }

  if (!transaction.isAccountActive) {
    // reject transaction
    return;
  }

  if (transaction.amount < 50000) {
    // junior officer approval
    return;
  }

  if (transaction.amount <= 200000) {
    // mid level approval
    return;
  }

  if (transaction.amount <= 1000000) {
    // manager approval
    return;
  }

  // executive approval
}

This works today. Tomorrow your compliance team adds a credit score check. Your fraud team adds a velocity check. Your legal team adds a sanctions screening step. Your product manager adds a daily limit check.

Every new rule goes into this same method. The method grows to fifty lines. Then a hundred. The conditions interact in ways that are hard to reason about. Testing it requires setting up every possible combination of flags. A bug in one condition can affect every other condition below it.

The Chain of Responsibility pattern says: each rule gets its own handler. Chain the handlers together. The method that starts the chain doesn't need to know any of the rules. It just starts the chain and gets out of the way.

Core Components

The pattern has three building blocks.

1. The Handler Interface

This is the contract every handler in the chain must implement. It declares the method for handling a request and provides the mechanism for linking handlers together. Every concrete handler extends or implements this.

2. The Concrete Handlers

These are the actual implementations. Each one owns exactly one business rule. It checks whether the request satisfies its rule. If the rule fails, it stops the chain and handles the failure. If the rule passes, it calls the next handler and passes the request forward.

3. The Chain

This isn't a class. It's the act of connecting handlers together using the setNext method. You build the chain in your composition root or your dependency injection setup. The order you connect them is the order they execute.

Real World Example One: Transaction Approval Flow

A fintech platform processes thousands of transactions daily. Before any transaction is approved, it must pass through several validation and approval gates. Each gate is independent. Each one has a single responsibility.

The gates in order:

1. Fraud check: is this transaction flagged as fraudulent?

2. KYC verification: has the user completed identity verification?

3. Account status: is the account active and in good standing?

4. Approval level: which officer tier has the authority to approve this amount?

The Transaction Model

class Transaction {
  final num amount;
  final bool isFraud;
  final bool isKycVerified;
  final bool isAccountActive;

  const Transaction({
    required this.amount,
    required this.isFraud,
    required this.isKycVerified,
    required this.isAccountActive,
  });
}

The transaction model carries all the data each handler needs to make its decision. It owns the data and nothing else. No validation logic lives here.

The Handler Interface

abstract class TransactionHandler {
  TransactionHandler? _next;

  void setNext(TransactionHandler handler) {
    _next = handler;
  }

  void handle(Transaction transaction);

  void passToNext(Transaction transaction) {
    if (_next != null) {
      _next!.handle(transaction);
    } else {
      print('End of chain reached with no handler stopping the transaction');
    }
  }
}

TransactionHandler is the contract every handler implements.

_next is nullable because the last handler in the chain has no next handler. Making it nullable and checking before calling prevents a null pointer crash at the end of the chain.

setNext connects one handler to the next. You call this when building the chain.

passToNext is a helper method that every concrete handler calls when its rule passes. It checks whether a next handler exists before calling it. If we reach the end of the chain without any handler stopping the transaction, we log it. In a real system, this would trigger an alert because it means the chain wasn't configured correctly.

The Concrete Handlers

class FraudHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (transaction.isFraud) {
      print('Transaction blocked: fraud detected');
      return;
    }
    print('Fraud check passed');
    passToNext(transaction);
  }
}

FraudHandler is the first gate. If the transaction is flagged as fraudulent, it prints a rejection message and returns. The chain stops here. No other handler sees this transaction. If the fraud check passes, it calls passToNext and the transaction moves to the next handler.

class KycHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (!transaction.isKycVerified) {
      print('Transaction blocked: KYC verification incomplete');
      return;
    }
    print('KYC check passed');
    passToNext(transaction);
  }
}

KycHandler checks whether the user has completed identity verification. If they haven't, the chain stops. If they have, the transaction moves forward. This handler knows nothing about fraud checks. It knows nothing about account status. It owns one rule.

class AccountHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (!transaction.isAccountActive) {
      print('Transaction blocked: account is not active');
      return;
    }
    print('Account status check passed');
    passToNext(transaction);
  }
}

AccountHandler checks account status. Same pattern, one rule: stop or pass.

class ApprovalHandler extends TransactionHandler {
  @override
  void handle(Transaction transaction) {
    if (transaction.amount < 50000) {
      print('Approved by Junior Officer — amount: ${transaction.amount}');
      return;
    }

    if (transaction.amount <= 200000) {
      print('Approved by Mid-Level Officer — amount: ${transaction.amount}');
      return;
    }

    if (transaction.amount <= 1000000) {
      print('Approved by Manager — amount: ${transaction.amount}');
      return;
    }

    print('Escalated to Executive Approval — amount: ${transaction.amount}');
    passToNext(transaction);
  }
}

ApprovalHandler is the final gate. It routes the transaction to the appropriate approval tier based on amount. Transactions below 50,000 are approved by a junior officer. Up to 200,000 go to a mid-level officer. Up to 1,000,000 go to a manager. Above that, the transaction is escalated further.

Note that this handler can still call passToNext if the amount exceeds the manager threshold, allowing you to add an executive handler to the chain later without touching ApprovalHandler.

Building and Running the Chain

void main() {
  // create the handlers
  final fraud = FraudHandler();
  final kyc = KycHandler();
  final account = AccountHandler();
  final approval = ApprovalHandler();

  // build the chain
  fraud.setNext(kyc);
  kyc.setNext(account);
  account.setNext(approval);

  // test with a fraudulent transaction
  print('Test 1: Fraudulent Transaction');
  final fraudulentTransaction = Transaction(
    amount: 100000,
    isFraud: true,
    isKycVerified: true,
    isAccountActive: true,
  );
  fraud.handle(fraudulentTransaction);

  // test with unverified KYC
  print('Test 2: KYC Not Verified');
  final unverifiedTransaction = Transaction(
    amount: 50000,
    isFraud: false,
    isKycVerified: false,
    isAccountActive: true,
  );
  fraud.handle(unverifiedTransaction);

  // test with a valid transaction
  print('Test 3: Valid Transaction');
  final validTransaction = Transaction(
    amount: 150000,
    isFraud: false,
    isKycVerified: true,
    isAccountActive: true,
  );
  fraud.handle(validTransaction);

  // test with a high value transaction
  print('Test 4: Executive Level Transaction');
  final executiveTransaction = Transaction(
    amount: 2000000,
    isFraud: false,
    isKycVerified: true,
    isAccountActive: true,
  );
  fraud.handle(executiveTransaction);
}

Output:

Test 1: Fraudulent Transaction
Transaction blocked: fraud detected

Test 2: KYC Not Verified
Fraud check passed
Transaction blocked: KYC verification incomplete

Test 3: Valid Transaction
Fraud check passed
KYC check passed
Account status check passed
Approved by Mid-Level Officer — amount: 150000

Test 4: Executive Level Transaction
Fraud check passed
KYC check passed
Account status check passed
Escalated to Executive Approval — amount: 2000000
End of chain reached with no handler stopping the transaction

Test 1 stops at the first handler. Test 2 passes fraud but stops at KYC. Test 3 passes all validation handlers and gets routed to the correct approval tier. Test 4 exceeds the manager threshold and gets escalated.

Notice that the calling code always starts from fraud.handle(transaction). It doesn't know how many handlers exist. It doesn't know which handler will stop the chain. And it doesn't know what the approval tiers are. It just hands the transaction to the first handler and the chain takes over.

When your compliance team adds a User Indemnity check next month, you create a UserIdemnityCheck, add it to the chain, and nothing else changes:

final indemnity = UserIndemnityStatus();

fraud.setNext(indemnity);
indemnity.setNext(kyc);
kyc.setNext(account);
account.setNext(approval);

One new class and one updated chain setup. Every existing handler untouched.

Real World Example Two: User Onboarding Validation

A user fills in a registration form and submits it. Before the account is created, the request must pass through several validation steps. If any step fails, the user gets a specific error explaining exactly what went wrong.

The steps in order:

1. Email validation: is the email format valid?

2. Password strength: does the password meet security requirements?

3. Age verification: is the user old enough to register?

4. Duplicate account check: does an account already exist with this email?

5. Account creation: all checks passed, create the account

The Registration Request Model

class RegistrationRequest {
  final String email;
  final String password;
  final int age;

  const RegistrationRequest({
    required this.email,
    required this.password,
    required this.age,
  });
}

The Handler Interface

abstract class RegistrationHandler {
  RegistrationHandler? _next;

  void setNext(RegistrationHandler handler) {
    _next = handler;
  }

  void handle(RegistrationRequest request);

  void passToNext(RegistrationRequest request) {
    if (_next != null) {
      _next!.handle(request);
    }
  }
}

This is the same structure as before. Nullable next, SetNext to build the chain, and PassToNext to move the request forward.

The Concrete Handlers

class EmailValidationHandler extends RegistrationHandler {
  @override
  void handle(RegistrationRequest request) {
    final emailRegex = RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$');

    if (!emailRegex.hasMatch(request.email)) {
      print('Registration failed: invalid email format — ${request.email}');
      return;
    }

    print('Email validation passed');
    passToNext(request);
  }
}

EmailValidationHandler checks the email format using a regex. If the format is invalid, it stops the chain immediately with a specific message. If it's valid, the request moves forward.

class PasswordStrengthHandler extends RegistrationHandler {
  @override
  void handle(RegistrationRequest request) {
    final password = request.password;
    final hasMinLength = password.length >= 8;
    final hasUppercase = password.contains(RegExp(r'[A-Z]'));
    final hasNumber = password.contains(RegExp(r'[0-9]'));
    final hasSpecialChar = password.contains(RegExp(r'[!@#\$%^&*]'));

    if (!hasMinLength || !hasUppercase || !hasNumber || !hasSpecialChar) {
      print('Registration failed: password does not meet security requirements');
      print('Requirements: 8+ characters, uppercase, number, special character');
      return;
    }

    print('Password strength check passed');
    passToNext(request);
  }
}

PasswordStrengthHandler enforces four password rules in one place. Minimum length, at least one uppercase letter, at least one number, and at least one special character. If any of these fail, the user gets a clear message explaining all the requirements. If all pass, the request moves forward.

class AgeVerificationHandler extends RegistrationHandler {
  final int minimumAge;

  AgeVerificationHandler({this.minimumAge = 18});

  @override
  void handle(RegistrationRequest request) {
    if (request.age < minimumAge) {
      print('Registration failed: user must be at least $minimumAge years old');
      return;
    }

    print('Age verification passed');
    passToNext(request);
  }
}

AgeVerificationHandler checks the user's age against a minimum threshold. Notice that this handler accepts the minimum age as a constructor parameter. This makes it configurable without modifying the class. If the minimum age requirement changes from 18 to 16 for a specific product, you just pass a different value when building the chain.

class DuplicateAccountHandler extends RegistrationHandler {
  final Set<String> existingEmails;

  DuplicateAccountHandler({required this.existingEmails});

  @override
  void handle(RegistrationRequest request) {
    if (existingEmails.contains(request.email)) {
      print('Registration failed: an account already exists with ${request.email}');
      return;
    }

    print('Duplicate account check passed');
    passToNext(request);
  }
}

DuplicateAccountHandler checks whether an account already exists with the provided email. In a real system, this would call a repository or database. Here we use a Set of existing emails to keep the example focused on the pattern.

class AccountCreationHandler extends RegistrationHandler {
  @override
  void handle(RegistrationRequest request) {
    print('All validation passed');
    print('Creating account for: ${request.email}');
    // call account creation service
    print('Account created successfully');
  }
}

AccountCreationHandler is the final handler. It only runs if every previous handler passed the request forward. By the time execution reaches here, the request has been validated on every dimension. This handler simply creates the account.

Building and Running the Chain

void main() {
  final existingEmails = {'existing@seyi.com', 'taken@seyi.com'};

  // create the handlers
  final emailValidation = EmailValidationHandler();
  final passwordStrength = PasswordStrengthHandler();
  final ageVerification = AgeVerificationHandler(minimumAge: 18);
  final duplicateCheck = DuplicateAccountHandler(existingEmails: existingEmails);
  final accountCreation = AccountCreationHandler();

  // build the chain
  emailValidation.setNext(passwordStrength);
  passwordStrength.setNext(ageVerification);
  ageVerification.setNext(duplicateCheck);
  duplicateCheck.setNext(accountCreation);

  // test with invalid email
  print('Test 1: Invalid Email');
  emailValidation.handle(RegistrationRequest(
    email: 'notanemail',
    password: 'SecureP@ss1',
    age: 25,
  ));

  // test with weak password
  print('Test 2: Weak Password');
  emailValidation.handle(RegistrationRequest(
    email: 'user@example.com',
    password: 'weak',
    age: 25,
  ));

  // test with underage user
  print('Test 3: Underage User');
  emailValidation.handle(RegistrationRequest(
    email: 'young@example.com',
    password: 'SecureP@ss1',
    age: 16,
  ));

  // test with duplicate account
  print('Test 4: Duplicate Account');
  emailValidation.handle(RegistrationRequest(
    email: 'existing@example.com',
    password: 'SecureP@ss1',
    age: 25,
  ));

  // test with valid registration
  print('Test 5: Valid Registration');
  emailValidation.handle(RegistrationRequest(
    email: 'newuser@example.com',
    password: 'SecureP@ss1',
    age: 25,
  ));
}

Output:

Test 1: Invalid Email
Registration failed: invalid email format — notanemail

Test 2: Weak Password
Email validation passed
Registration failed: password does not meet security requirements
Requirements: 8+ characters, uppercase, number, special character

Test 3: Underage User
Email validation passed
Password strength check passed
Age verification passed
Registration failed: user must be at least 18 years old

Test 4: Duplicate Account
Email validation passed
Password strength check passed
Age verification passed
Duplicate account check passed
Registration failed: an account already exists with existing@example.com

Test 5: Valid Registration
Email validation passed
Password strength check passed
Age verification passed
Duplicate account check passed
All validation passed
Creating account for: newuser@example.com
Account created successfully

Each test stops at exactly the right handler. Each failure message is specific. The valid registration flows through all five handlers and creates the account.

When a new requirement arrives, say a phone number verification step before account creation, you create a PhoneVerificationHandler and plug it into the chain between duplicate check and account creation. Five existing handlers remain completely untouched.

What Makes These Two Examples Interesting Together

The transaction flow and the onboarding flow look similar on the surface, but they represent two different ways the pattern gets used in production.

The transaction flow combines validation handlers and routing handlers in one chain. Fraud, KYC, and account handlers are gates. The approval handler is a router. The chain validates first, then routes. This is common in payment and compliance systems where every transaction must pass multiple independent checks before being directed to the appropriate authority.

The onboarding flow is a pure validation chain. Every handler is a gate. The final handler is the action that runs only if all gates pass. This is common in form processing, API request validation, and any multi-step verification flow.

Both use the same pattern and are configured the same way. The difference is just in what the handlers do when they let the request through.

When to Use the Chain of Responsibility Pattern

Use it when you have a request that must pass through multiple independent checks or processing steps.

It's also a good fit when the number of checks or their order might change over time. Adding a new step or reordering existing steps should not require modifying existing handler code.

It works well when each check or processing step has genuinely independent logic. If the steps are deeply interdependent and need to share a lot of state, a single class might be cleaner.

It does well when you want each step to be independently testable. With the chain pattern, testing FraudHandler means creating one handler, calling handle with a transaction, and checking the output. No other handler is involved.

And it's great when different configurations of the chain might be needed in different contexts. A junior officer's system might have a shorter chain than an executive's system. The same handlers, configured differently.

When Not to Use It

Avoid the pattern when you only have one or two checks. The overhead of defining an abstract class and multiple concrete classes is not worth it for simple validation.

It's also not the best when the order of processing steps is fixed and will never change. If the chain will always be the same, a simpler sequential function call might be clearer.

Don't use it when handlers need to communicate results back to each other. The pattern works best when each handler makes an independent decision. If Handler B needs to know what Handler A found, consider a different approach.

And it's not a good choice when you need guaranteed execution of all handlers regardless of earlier results. The Chain of Responsibility stops when a handler handles the request. If you need all steps to always run, a middleware pipeline or decorator pattern might suit you better.

Conclusion

The Chain of Responsibility pattern solves the problem that every growing system eventually faces. Business rules accumulate and validation logic expands. A method that started as ten lines becomes a hundred. The conditions interact in ways nobody fully understands anymore. Nobody wants to touch it.

The pattern gives you a way out. Each business rule gets its own handler. Each handler owns one responsibility and makes one decision: stop here, or pass it forward. The chain is built once in the configuration layer. The handlers never need to know about each other.

In the transaction approval flow, adding a new compliance rule means one new handler class. In the onboarding flow, adding a new verification step means one new handler class. In both cases, nothing else changes.

That's the promise of the pattern. Complexity that grows by addition, not by modification. Business rules that are isolated, testable, and replaceable. A system that can absorb new requirements without accumulating more debt every time.

Applying this behavioral pattern helps to bring some level of organization and scalability to your codes and makes it easy to manage based on further business rules to come in the nearest future.

Happy Coding!!

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.